pgdesign Documentation

Architecture: The Laws

2026-08-12T00:00:00Z

pgdesign rests on a small algebra — a content-addressed object model wrapped around a category of schema migrations, governed by one equivalence relation. Every defect class the system guards against is a violation of one of the laws below, so those defect classes are eliminated by construction rather than case-by-case. Any future proposal is judged the same way: which law does it implement, check, or violate?

pgdesign build

2026-08-12T00:00:00Z

pgdesign check

2026-08-12T00:00:00Z

pgdesign codegen

2026-08-12T00:00:00Z

pgdesign diff

2026-08-12T00:00:00Z

pgdesign fmt

2026-08-12T00:00:00Z

pgdesign generate

2026-08-12T00:00:00Z

pgdesign import

2026-08-12T00:00:00Z

pgdesign CLI Reference

2026-08-12T00:00:00Z

pgdesign introspect

2026-08-12T00:00:00Z

pgdesign migrate

2026-08-12T00:00:00Z

pgdesign revise

2026-08-12T00:00:00Z

pgdesign seed

2026-08-12T00:00:00Z

pgdesign serve

2026-08-12T00:00:00Z

pgdesign stats

2026-08-12T00:00:00Z

pgdesign testdb

2026-08-12T00:00:00Z

Format Reference

2026-08-12T00:00:00Z

pgdesign schemas are written in TOML. A schema file defines metadata, custom types, and table definitions.

API Reference

2026-08-12T00:00:00Z

Cross-Repository Imports

2026-08-12T00:00:00Z

Imports let one pgdesign project reference tables owned by *another* pgdesign project — a shared "framework" schema, a platform team's user table, a billing service's accounts — across a git dependency, without copying the definitions by hand or coupling the two repositories at build time.

pgdesign

2026-08-12T00:00:00Z

A PostgreSQL schema compiler. You declare your database in TOML; pgdesign compiles it to SQL DDL and enforces database design principles on the way.

internal/audit

2026-08-12T00:00:00Z

internal/catalog

2026-08-12T00:00:00Z

internal/chain

2026-08-12T00:00:00Z

internal/codegen

2026-08-12T00:00:00Z

internal/config

2026-08-12T00:00:00Z

internal/dbutil

2026-08-12T00:00:00Z

internal/diagnostic

2026-08-12T00:00:00Z

internal/diff

2026-08-12T00:00:00Z

internal/discover

2026-08-12T00:00:00Z

internal/enc

2026-08-12T00:00:00Z

internal/extregistry

2026-08-12T00:00:00Z

internal/fd

2026-08-12T00:00:00Z

internal/format

2026-08-12T00:00:00Z

internal/generate

2026-08-12T00:00:00Z

internal/graph

2026-08-12T00:00:00Z

internal/imports

2026-08-12T00:00:00Z

internal/introspect

2026-08-12T00:00:00Z

internal/livenorm

2026-08-12T00:00:00Z

internal/livestats

2026-08-12T00:00:00Z

internal/migrate/design

2026-08-12T00:00:00Z

internal/migrate

2026-08-12T00:00:00Z

internal/model

2026-08-12T00:00:00Z

internal/modelgen

2026-08-12T00:00:00Z

internal/objstore

2026-08-12T00:00:00Z

internal/parse/pgschema

2026-08-12T00:00:00Z

internal/parse

2026-08-12T00:00:00Z

internal/predicate

2026-08-12T00:00:00Z

internal/project

2026-08-12T00:00:00Z

internal/rev

2026-08-12T00:00:00Z

internal/risk

2026-08-12T00:00:00Z

internal/seed

2026-08-12T00:00:00Z

internal/semtype

2026-08-12T00:00:00Z

internal/serve

2026-08-12T00:00:00Z

internal/splitfmt

2026-08-12T00:00:00Z

internal/sql

2026-08-12T00:00:00Z

internal/sqlexpr

2026-08-12T00:00:00Z

internal/sqlparse

2026-08-12T00:00:00Z

internal/sqlutil

2026-08-12T00:00:00Z

internal/testdb

2026-08-12T00:00:00Z

internal/typeinfo

2026-08-12T00:00:00Z

internal/validate

2026-08-12T00:00:00Z

internal/workload

2026-08-12T00:00:00Z

The Migration Chain

2026-08-12T00:00:00Z

This page explains the *concepts* behind pgdesign's migration system — what a revision is, what an edge is, and why the design gives you integrity guarantees that file-numbered migration tools cannot. For the command-by-command how-to (generate, apply, rollback, squash, rebase, upgrade, baseline), see the [Migration Guide](migration-guide.md).

Quickstart

2026-08-12T00:00:00Z

pgdesign is a PostgreSQL schema compiler. You define your database schema in TOML, and pgdesign compiles it to SQL DDL with strict enforcement of database design principles.

Validation Rules

2026-08-12T00:00:00Z

pgdesign enforces **134** diagnostic rules across 6 categories (E: 78 errors, W: 32 warnings, I: 11 info, S: 5 seed, C: 7 codegen, A: 1 audit).

Code Generation Guide

2026-07-29T00:00:00Z

pgdesign generates type-safe application code from your schema definitions. Instead of manually writing struct definitions, ORM models, enum types, or validation logic that mirrors your database schema, you run `pgdesign codegen` and get generated source files that stay in sync with your TOML schema.

Diff Guide

2026-07-29T00:00:00Z

The `pgdesign diff` command compares your current TOML schema against a target and reports every difference: tables, columns, enums, views, functions, constraints, indexes, policies, sequences, domains, composite types, state machines, and partitioning configuration. Each column change carries a risk classification (Safe, Caution, or Dangerous) so you know what will happen before you run a migration.

Introspect Guide

2026-07-29T00:00:00Z

pgdesign's `introspect` command reads a live PostgreSQL database's schema via `pg_catalog` and produces TOML output in pgdesign's schema format. It is the primary tool for adopting pgdesign on an existing database.

Migration Guide

2026-07-29T00:00:00Z

pgdesign generates migrations by diffing your TOML schema against the last recorded schema state. A migration is a content-addressed **chain edge** — a self-contained transition between two schema revisions whose operations and object payloads live in the on-disk store. Edges carry DDL and DML operations, per-operation inverses (for rollback), and safety diagnostics.

Migration Intelligence

2026-07-29T00:00:00Z

How pgdesign generates safe, phased migrations with risk classification.

rlsbl Release Integration

2026-07-29T00:00:00Z

pgdesign's build freshness check can run as part of rlsbl's release pipeline. This ensures that no release ships with stale schema-derived output: if the TOML schema changed but `pgdesign build` was not re-run, the release is blocked.

Semantic Types

2026-07-29T00:00:00Z

pgdesign uses a semantic type system instead of raw PostgreSQL types. Each semantic type maps to a PG type and carries default constraints (NOT NULL, default values, check expressions). This ensures consistency across your schema and prevents common mistakes like nullable IDs or timestamps without time zones.

Content-Addressed Schemas: Making Schema Drift Unrepresentable

2026-07-28T00:00:00Z

Every team that has run a database for more than a year has met the same ghost. The schema in your repository says one thing. The database in production says something subtly different. A column was widened by hand during an incident. A migration was edited after it ran. An index was added directly in `psql` and never written down. Nobody is sure. The gap between what your schema *says* and what your database *is* — schema drift — is where a surprising amount of production pain lives.

Python Query Layer

2026-06-25T00:00:00Z

The `--mode query-layer --lang python` codegen mode generates a complete type-safe query layer with protocols, dual backends, and a constraint registry. The generated code is async-first and uses Python's Protocol typing for structural subtyping.

Design Intelligence

2026-06-24T00:00:00Z

The design intelligence subsystem analyzes schema structure beyond basic validation. It surfaces structural issues, optimization opportunities, and design anti-patterns through 12 diagnostics registered under the `"design"` tag. All diagnostics are implemented in `internal/validate/validate.go` and registered via `cmd/pgdesign/checks.go`.

Seed Data Generation

2026-06-24T00:00:00Z

The seed generator produces type-aware test data for all tables in a pgdesign schema. It respects FK dependencies, CHECK constraints, UNIQUE constraints, semantic types, and column nullability. Output is either INSERT statements or PostgreSQL COPY format.

State Machines

2026-06-24T00:00:00Z

pgdesign supports state machine types that enforce valid state transitions at the database level via triggers, generate D2 state diagrams, and produce transition methods in codegen output.

Ephemeral Test Databases

2026-06-24T00:00:00Z

pgdesign can create isolated, throwaway databases for your test suite. Each test run gets a fresh database built from your schema DDL. The database is dropped when the test finishes. Production credentials are never involved.

Type Extends

2026-06-24T00:00:00Z

Type derivation allows defining new types that inherit from and extend existing types. This works for all four type kinds: scalar, enum, composite, and state machine.

typeinfo Package

2026-06-24T00:00:00Z

The `typeinfo` package provides structured PostgreSQL type representation. It parses raw type strings (from TOML schemas, `format_type()` output, etc.) into a normalized struct and reconstructs SQL type strings for DDL generation.

Workload Analysis

2026-06-24T00:00:00Z

pgdesign provides a two-tier approach to index recommendations and performance diagnostics. The **structural tier** analyzes the TOML schema without a database connection. The **workload tier** analyzes live query patterns from `pg_stat_statements` and `pg_stat_user_tables`. Both tiers produce diagnostics through the standard `diagnostic.Diagnostics` system.