On this page
Reference for the pgdesign migrate command group — plan, generate, apply, rollback, baseline, squash, status, and test subcommands with flags and usage.
#pgdesign migrate
Database migration planning, generation, and execution
#migrate apply
Apply all pending migrations to the target database in order. Each migration runs inside its own transaction with advisory locking to prevent concurrent execution. Non-transactional operations like CREATE INDEX CONCURRENTLY execute outside transactions automatically. Use --dry-run to preview the SQL without executing.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL for the target database server | ||
--dir | str | Directory containing migration files to read or write (defaults to project config migrations_dir, else migrations) |
#migrate baseline
Adopt an existing database onto the migration chain without executing any migration SQL — for a schema created by other means, or one that has intentionally drifted from the TOML. In chain mode it introspects the live database, synthesizes a genesis edge carrying that manifest, and stamps the baseline boundary (rollback-frozen); pass the schema TOML path(s) so the right search-path is introspected. Legacy semver-TOML mode records a semver --version instead. Re-baselining at the same state is a no-op.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL for the target database server | ||
--dir | str | Directory containing migration files to read or write (defaults to project config migrations_dir, else migrations) | |||
--version | str | Version label for the baseline record (legacy semver-TOML mode only) | |||
--description | str | Initial baseline | Human-readable note recorded with the baseline, shown in migrate status and history output |
#Arguments
| Name | Required | Description |
|---|---|---|
path | no | Schema TOML file(s) or directory (chain mode; selects the schema search-path to introspect) |
#migrate generate
Generate versioned migration files by comparing the TOML schema against a live database. Produces up and down SQL files with risk annotations, safety linting, and expand-migrate-contract phase classification. Volatile defaults and operations on large tables are automatically detected and handled safely.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL for the target database server (legacy-mode only; chain-mode generate is pure) | ||
--dir | str | Directory containing migration files to read or write (defaults to project config migrations_dir, else migrations) |
#Arguments
| Name | Required | Description |
|---|---|---|
path | yes | Path to TOML schema file(s) or directory containing them |
#migrate plan
Preview the migration chain PURELY, without touching any database (roadmap 5.9). In a chain-mode project it enumerates the edges from GENESIS -- or from an explicit --from revision -- to the single live head, in path-finder order, listing each edge's id, slug, and op summary. Drift preview against a live database is diff --live's job; per-database pending is migrate status's. A legacy (semver-TOML) project keeps the old live-diff plan (requires --db) until it is upgraded to the chain.
Effect: read_only
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL (legacy-mode only; chain-mode plan is pure and ignores it) | ||
--from | str | Chain-mode only: revision string to enumerate from (pure input); absent enumerates from genesis | |||
--dir | str | Directory containing migration files to read or write (defaults to project config migrations_dir, else migrations) |
#Arguments
| Name | Required | Description |
|---|---|---|
path | yes | Path to TOML schema file(s) or directory containing them |
#migrate rebase
Resolve a two-head fork (chain mode). Re-parents the tail of the head NOT named by --head onto the head that IS named, re-simulating each re-parented edge's ops to recompute its revision and content-derived edge file. The rebased-away originals retire INTACT to migrations/archive/ (never rewritten or deleted), and the rebase revision-remap table (migrations/remap.json) is written so a database stamped at a rebased-away revision is served forward to the live head, never orphaned. A pure file operation: no database is required.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--head | str | The head to KEEP (a revision string or a live edge-id prefix); the OTHER head's tail is re-parented onto it | |||
--dir | str | Directory containing the chain project (defaults to project config migrations_dir, else migrations) |
#migrate rollback
Rollback applied database migrations to a specified target version. Executes down migration SQL in reverse application order with advisory locking. Multi-step rollbacks verify reversibility of all steps before starting. The target version is exclusive, meaning that version stays applied after rollback completes.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL for the target database server | ||
--dir | str | Directory containing migration files to read or write (defaults to project config migrations_dir, else migrations) | |||
--to | str | Target version to rollback to (exclusive -- this version stays applied) |
#migrate squash
Consolidate a range of sequential migrations. In chain mode (a migrations/chain/ project) squash mints a CONSOLIDATION EDGE whose op-list is the ordered concatenation of the range, retiring the superseded originals intact to migrations/archive/ (never a rewrite) so mid-range databases resume via the path-finder; --from/--to are revision-or-edge references. In legacy (semver-TOML) mode squash concatenates the range into one combined migration file. --db is required.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--from | str | Start of the squash range: a semver version (legacy) or a revision-or-edge reference (chain mode; 'genesis', a revision string, or a live edge-id prefix) | |||
--to | str | End of the squash range: a semver version (legacy) or a revision-or-edge reference (chain mode) | |||
--slug | str | Display slug for the consolidation edge (chain mode; auto-derived from endpoint hashes when omitted) | |||
--dir | str | Directory containing migration files to read or write (defaults to project config migrations_dir, else migrations) | |||
--db | str | PGDESIGN_DB | PostgreSQL connection URL (REQUIRED); the pre-upgrade guard runs against it (legacy mode also runs the M200 applied-version check) |
#migrate status
Show which migrations have been applied to the target database and which are still pending. Reads the migration tracking table and compares it with the migrations directory to display version numbers, applied timestamps, and current execution status for each migration file.
Effect: read_only
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL for the target database server | ||
--dir | str | Directory containing migration files to read or write (defaults to project config migrations_dir, else migrations) |
#migrate test
Test migrations by applying them against a staging database to verify correctness before production deployment. With --shadow mode, replays all migrations into a fresh database and diffs the result against the TOML schema to catch drift between migration files and schema definitions.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL for the staging test database | ||
--dir | str | Directory containing migration files to read or write (defaults to project config migrations_dir, else migrations) | |||
--timeout | int | 60 | Maximum time in seconds before the test run is aborted | ||
--shadow | bool | Test by replaying migrations into a shadow database and diffing against TOML schema |
#Arguments
| Name | Required | Description |
|---|---|---|
path | no | Schema file(s) or directory (required with --shadow) |
#migrate upgrade
One-time adoption of a legacy (semver-TOML) database onto the on-disk chain. Verifies the schema TOML matches the live database exactly (refusing to stamp over drift), folds the existing pgdesign_migrations rows into the chain journal, writes the content-addressed prefix edge, and stamps this database's upgrade boundary in a single transaction. Requires a clean working tree for the schema files when inside a git repository. Run once per database; a fresh database uses migrate apply directly.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL for the database to upgrade | ||
--dir | str | Directory containing migration files to read or write (defaults to project config migrations_dir, else migrations) |
#Arguments
| Name | Required | Description |
|---|---|---|
path | yes | Path to TOML schema file(s) or directory containing them |