README
¶
pgdesign
A PostgreSQL schema compiler. You write your schema declaratively in TOML; pgdesign compiles it to SQL DDL, migrations, diagrams, documentation, and type-safe client code — with strict enforcement of database design principles.
What makes pgdesign more than a DDL generator is that every schema has a content-addressed identity. The fully-resolved schema hashes to a single revision; every artifact pgdesign produces is stamped with the revision that produced it; and migrations form a git-like chain of content-addressed edges with recorded inverses, apply-time preconditions, a durable journal, and a post-apply reconcile. The result: generated artifacts cannot silently diverge from each other or from the schema, a migration that lies about what it does is not representable, and a database that has drifted from its schema is caught loudly instead of corrupted quietly.
Installation
Go
go install github.com/smm-h/pgdesign/cmd/pgdesign@v0
@v0, not @latest. The Go module proxy has a cached v1.0.0 for this
module that was never a real release, and @latest resolves to it. See
the phantom v1.0.0 note below.
npm
npm install pgdesign
pip
pip install pgdesign
The phantom v1.0.0
A v1.0.0 tag was pushed to this repository once and immediately removed, but
the Go module proxy had already cached it. Proxy entries are permanent and
immutable: github.com/smm-h/pgdesign@v1.0.0 will resolve forever, to code that
was never released under that version, and go install ...@latest picks it up
in preference to every real release.
It cannot be retracted. A retract directive only takes effect in a version the
proxy also serves, so retracting v1.0.0 would mean tagging v1.0.1 -- and this
project does not issue 1.x tags. Pin @v0 (or an exact @v0.x.y) and the proxy
serves the real releases.
What you get
- Declarative TOML → everything. One schema definition compiles to SQL DDL, D2/SVG diagrams, JSON snapshots, human-readable docs, GraphQL SDL, and client code in six languages.
- A migration chain with integrity guarantees. Migrations are content-addressed edges between schema revisions. Identity is derived from content, so regenerating an unchanged schema never churns git and two divergent branches produce distinct edges (a fork, resolved with
migrate rebase). Apply is preconditioned (the database must be where the edge says it is), journaled (rollback replays recorded inverses, never re-reads files), and reconciled (the database is verified to have arrived at the target revision). - A rename data-loss gate. A column or table drop+add that looks like a rename is refused unless you declare it in
[renames]— turning a silent data-loss trap into an explicit, mechanically-invertible rename. - Cross-repository imports. Reference another pgdesign project's tables across a git pin;
import lockvendors the referenced surface plus its type closure for reproducible offline builds, andcheck --tag importscatches column-level semantic drift. - Branded, type-safe codegen. Generated Go/TypeScript/Java/Kotlin/Python/Zig carries the schema's revision and uses validating branded types, verified by per-language compile checks in CI.
- Normal-form auditing. 1NF through BCNF from declared functional dependencies, with BCNF decomposition and Armstrong-relation counterexamples.
- Design intelligence, workload analysis, and type-aware seed data.
- A DB-free HTTP API and web UI (
serve) that returns the same canonical schema payload thejsonoutput produces.
The one-command workflow
Edit your schema, then run:
pgdesign revise
revise regenerates every configured output, chains the resulting migration, and commits — the pure tier (outputs + migration + blocking normal-form/structural checks) first, then the non-retroactive database tier (live FD discovery, pg_stat workload analysis, live import verification) when a database is reachable. One command, one revision everywhere.
Commands
| Command | Description |
|---|---|
revise |
Regenerate all outputs, chain the migration, and commit — the one-command project revision |
generate |
Generate SQL DDL (or JSON, D2, SVG, doc, GraphQL) from schema file(s) |
build |
Generate all outputs configured in pgdesign.toml |
check |
Run project checks (validation, nf, coverage, design, structural, workload, build, revision, imports) |
fmt |
Format schema file(s) in place |
codegen |
Generate type-safe application code (Go, TS, Java, Kotlin, Python, Zig) |
introspect |
Introspect a live PostgreSQL database into TOML |
diff |
Diff a schema against a live database, another TOML, or a git ref |
seed |
Generate type-aware test data |
stats |
Analyze live database health (sizes, index usage, bloat) |
serve |
Start the HTTP API server and web UI (runs without a database) |
migrate generate |
Generate a chain edge from schema changes (pure — no database) |
migrate plan |
Preview the pending chain edges |
migrate apply |
Apply pending edges via the path-finder |
migrate rollback |
Roll back applied edges from the journal |
migrate status |
Show a database's chain position and pending edges |
migrate squash |
Consolidate a range of edges into one consolidation edge |
migrate rebase |
Resolve a two-head fork by re-parenting a tail |
migrate upgrade |
One-time adoption of a legacy (pre-chain) database onto the chain |
migrate baseline |
Adopt an existing or intentionally-drifted database without running SQL |
migrate test |
Apply-then-rollback (or --shadow replay) against a staging database |
import lock |
Resolve and vendor imported schema surfaces; write the lockfile |
import update |
Re-pin and re-vendor imported surfaces |
testdb setup / teardown / gc / init |
Manage ephemeral test databases |
Documentation
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
pgdesign
command
|
|
|
internal
|
|
|
audit
Package audit provides normal form analysis (1NF through BCNF) for pgdesign schemas using declared functional dependencies and Bernstein synthesis.
|
Package audit provides normal form analysis (1NF through BCNF) for pgdesign schemas using declared functional dependencies and Bernstein synthesis. |
|
catalog
Package catalog is the shared, SCOPED pg_catalog query layer (roadmap 5.5+5.7).
|
Package catalog is the shared, SCOPED pg_catalog query layer (roadmap 5.5+5.7). |
|
chain
Package chain is the pure kernel of pgdesign's migration algebra: revision manifests, the parent-linked edge graph (the free category on edges), and three-way typed invertibility (roadmap kernel 1.4, laws L3 + L4 + L7).
|
Package chain is the pure kernel of pgdesign's migration algebra: revision manifests, the parent-linked edge graph (the free category on edges), and three-way typed invertibility (roadmap kernel 1.4, laws L3 + L4 + L7). |
|
codegen
Package codegen generates type-safe application-layer code from resolved pgdesign schemas across six target languages including Go, TypeScript, and Python.
|
Package codegen generates type-safe application-layer code from resolved pgdesign schemas across six target languages including Go, TypeScript, and Python. |
|
config
Package config loads and validates pgdesign.toml project configuration files including output targets, suppression rules, and extension declarations.
|
Package config loads and validates pgdesign.toml project configuration files including output targets, suppression rules, and extension declarations. |
|
diagnostic
Package diagnostic re-exports shared diagnostic types from pkg/diagnostic for use by internal pgdesign packages.
|
Package diagnostic re-exports shared diagnostic types from pkg/diagnostic for use by internal pgdesign packages. |
|
diff
Package diff compares two resolved schemas or a schema against a live database and produces a structured diff with risk annotations on each change.
|
Package diff compares two resolved schemas or a schema against a live database and produces a structured diff with risk annotations on each change. |
|
discover
Package discover provides automatic functional dependency discovery from live PostgreSQL data using the TANE algorithm (Huhtala et al., 1999).
|
Package discover provides automatic functional dependency discovery from live PostgreSQL data using the TANE algorithm (Huhtala et al., 1999). |
|
enc
Package enc is pgdesign's canonical per-object encoder: it maps each resolved model object to canonical JSON bytes, and decodes those bytes back to the object.
|
Package enc is pgdesign's canonical per-object encoder: it maps each resolved model object to canonical JSON bytes, and decodes those bytes back to the object. |
|
extregistry
Package extregistry implements the PostgreSQL extension capability registry, mapping extension names to the types, opclasses, and functions they provide.
|
Package extregistry implements the PostgreSQL extension capability registry, mapping extension names to the types, opclasses, and functions they provide. |
|
fd
Package fd provides functional dependency primitives including closure computation, minimal cover, candidate keys, and BCNF decomposition for audit.
|
Package fd provides functional dependency primitives including closure computation, minimal cover, candidate keys, and BCNF decomposition for audit. |
|
format
Package format implements canonical TOML formatting for pgdesign schema files, reordering sections via a comment-preserving go-toml-edit AST in place.
|
Package format implements canonical TOML formatting for pgdesign schema files, reordering sections via a comment-preserving go-toml-edit AST in place. |
|
generate
Package generate transforms a resolved model.Schema into PostgreSQL DDL output including tables, views, materialized views, functions, and triggers.
|
Package generate transforms a resolved model.Schema into PostgreSQL DDL output including tables, views, materialized views, functions, and triggers. |
|
graph
Package graph provides generic topological sorting and cycle detection algorithms used by model, generate, and format for dependency ordering.
|
Package graph provides generic topological sorting and cycle detection algorithms used by model, generate, and format for dependency ordering. |
|
imports
Package imports implements cross-repository schema imports (roadmap 7.2): the surface snapshot, pinning, and offline drift check for another pgdesign project's schema referenced via an [imports.<alias>] declaration.
|
Package imports implements cross-repository schema imports (roadmap 7.2): the surface snapshot, pinning, and offline drift check for another pgdesign project's schema referenced via an [imports.<alias>] declaration. |
|
introspect
Package introspect provides live PostgreSQL database introspection, extracting schema information from pg_catalog into the resolved IR model.
|
Package introspect provides live PostgreSQL database introspection, extracting schema information from pg_catalog into the resolved IR model. |
|
livenorm
Package livenorm implements LIVE ROUND-TRIP NORMALIZATION (roadmap 1.2, boundary item 4): the concrete diff.LiveNormalizer that resolves the ≈_pg RESIDUE — catalog-dependent cast materialization — that no pure normalizer can reach.
|
Package livenorm implements LIVE ROUND-TRIP NORMALIZATION (roadmap 1.2, boundary item 4): the concrete diff.LiveNormalizer that resolves the ≈_pg RESIDUE — catalog-dependent cast materialization — that no pure normalizer can reach. |
|
livestats
Package livestats fetches live table statistics from a running PostgreSQL server and shapes them into the generate.D2Options.Stats contract (a map keyed by model.TableKey).
|
Package livestats fetches live table statistics from a running PostgreSQL server and shapes them into the generate.D2Options.Stats contract (a map keyed by model.TableKey). |
|
migrate
Package migrate provides migration generation, application, rollback, squash consolidation, and safety linting with risk classification for schema changes.
|
Package migrate provides migration generation, application, rollback, squash consolidation, and safety linting with risk classification for schema changes. |
|
migrate/design
Package design is the phase-5 DESIGN GATE (roadmap subphase 5.0).
|
Package design is the phase-5 DESIGN GATE (roadmap subphase 5.0). |
|
model
Package model provides the resolved intermediate representation for pgdesign, the canonical in-memory schema that all downstream packages consume.
|
Package model provides the resolved intermediate representation for pgdesign, the canonical in-memory schema that all downstream packages consume. |
|
modelgen
Package modelgen is a pure random generator of VALID pgdesign models, built on pgregory.net/rapid so shrinking is structural and comes for free with the combinators.
|
Package modelgen is a pure random generator of VALID pgdesign models, built on pgregory.net/rapid so shrinking is structural and comes for free with the combinators. |
|
objstore
Package objstore is the content-addressed object store: a hash-keyed put/get map with deduplication, an on-disk layout under a configurable root, and codec-epoch awareness.
|
Package objstore is the content-addressed object store: a hash-keyed put/get map with deduplication, an on-disk layout under a configurable root, and codec-epoch awareness. |
|
parse
Package parse turns pgdesign schema TOML into a RawSchema.
|
Package parse turns pgdesign schema TOML into a RawSchema. |
|
parse/pgschema
Code generated by strictspec.
|
Code generated by strictspec. |
|
predicate
Package predicate is the migration PRECONDITION IR (roadmap 5.5+5.7, law L5's domain check / L1's single ≈_syn / L8).
|
Package predicate is the migration PRECONDITION IR (roadmap 5.5+5.7, law L5's domain check / L1's single ≈_syn / L8). |
|
project
Package project is the shared project-loading core: it reconciles a parsed schema set, the project's pgdesign.toml config, and the vendored import surface into ONE resolved model — the semtype registry (builtin + config [[extensions]] + user types + imported enums), the vendored import reference tables, and the config/toml pg_version tiers folded into schema.PGVersion.
|
Package project is the shared project-loading core: it reconciles a parsed schema set, the project's pgdesign.toml config, and the vendored import surface into ONE resolved model — the semtype registry (builtin + config [[extensions]] + user types + imported enums), the vendored import reference tables, and the config/toml pg_version tiers folded into schema.PGVersion. |
|
rev
Package rev is pgdesign's whole-model canonical form, revision identity, and the single JSON envelope serializer (roadmap kernel 1.5, laws L1 + L7).
|
Package rev is pgdesign's whole-model canonical form, revision identity, and the single JSON envelope serializer (roadmap kernel 1.5, laws L1 + L7). |
|
risk
Package risk provides shared risk classification for schema change operations, categorizing DDL statements by safety level for diff and migrate.
|
Package risk provides shared risk classification for schema change operations, categorizing DDL statements by safety level for diff and migrate. |
|
semtype
Package semtype implements the semantic type system for pgdesign, mapping user-defined enums, scalar domains, composite types, and state machines.
|
Package semtype implements the semantic type system for pgdesign, mapping user-defined enums, scalar domains, composite types, and state machines. |
|
serve
Package serve provides an HTTP API server and web UI for pgdesign schema inspection, validation, database statistics, and interactive exploration.
|
Package serve provides an HTTP API server and web UI for pgdesign schema inspection, validation, database statistics, and interactive exploration. |
|
splitfmt
Package splitfmt implements a sealed, terminal file format for carrying split SQL statements.
|
Package splitfmt implements a sealed, terminal file format for carrying split SQL statements. |
|
sql
Package sql provides shared SQL builder functions for PostgreSQL DDL generation, the single place where SQL text is constructed across all packages.
|
Package sql provides shared SQL builder functions for PostgreSQL DDL generation, the single place where SQL text is constructed across all packages. |
|
sqlexpr
Package sqlexpr is a recursive descent parser for a subset of PostgreSQL SQL expressions.
|
Package sqlexpr is a recursive descent parser for a subset of PostgreSQL SQL expressions. |
|
sqlparse
Package sqlparse wraps wasilibs/go-pgquery, a WASM-based PostgreSQL parser requiring no CGo, for SQL statement splitting and expression deparsing.
|
Package sqlparse wraps wasilibs/go-pgquery, a WASM-based PostgreSQL parser requiring no CGo, for SQL statement splitting and expression deparsing. |
|
sqlutil
Package sqlutil provides a shared adapter between the sqlexpr parser and the diagnostic package for consistent parse-error-to-diagnostic conversion.
|
Package sqlutil provides a shared adapter between the sqlexpr parser and the diagnostic package for consistent parse-error-to-diagnostic conversion. |
|
testenv
Package testenv binds the suite-wide test-environment floor.
|
Package testenv binds the suite-wide test-environment floor. |
|
typeinfo
Package typeinfo provides structured PostgreSQL type representation.
|
Package typeinfo provides structured PostgreSQL type representation. |
|
validate
Package validate provides the strict validation engine for pgdesign schemas, operating on the resolved IR to detect rule violations and anti-patterns.
|
Package validate provides the strict validation engine for pgdesign schemas, operating on the resolved IR to detect rule violations and anti-patterns. |
|
pkg
|
|
|
diagnostic
Package diagnostic provides shared error, warning, and hint reporting types used by schema compiler passes.
|
Package diagnostic provides shared error, warning, and hint reporting types used by schema compiler passes. |
|
genkit
Package genkit provides the generator interface contract and freshness/orphan orchestration for deterministic code generation pipelines.
|
Package genkit provides the generator interface contract and freshness/orphan orchestration for deterministic code generation pipelines. |
Click to show internal directories.
Click to hide internal directories.