Commands

Note

All examples use npx. You can also use pnpm dlx @smplcty/schema-flow instead.

Migration

schema-flow run

Run full migration pipeline: pre-scripts, schema migration, post-scripts.

npx @smplcty/schema-flow run --db postgresql://user:pass@localhost:5432/mydb

schema-flow run pre

Run only pre-scripts (SQL files in schema/pre/).

schema-flow run migrate

Run only the schema migration phase (YAML diffing and DDL execution).

schema-flow run post

Run only post-scripts (SQL files in schema/post/).

schema-flow plan

Dry-run. Shows planned operations without executing. Equivalent to run --dry-run.

npx @smplcty/schema-flow plan --db postgresql://user:pass@localhost:5432/mydb

schema-flow validate

Execute the migration plan inside a transaction that is always rolled back. Verifies SQL validity without making changes.

schema-flow baseline

Mark the current database state as baseline. Records all current schema files in the history table without running any migrations. Use when adopting schema-flow on an existing database.

npx @smplcty/schema-flow baseline --db postgresql://user:pass@localhost:5432/mydb

Analysis

schema-flow drift

Compare YAML definitions to the live database. Reports differences without making changes.

npx @smplcty/schema-flow drift --db postgresql://user:pass@localhost:5432/mydb

schema-flow drift --apply

Detect drift and generate + execute a migration plan to fix all differences. Destructive fixes require --allow-destructive.

schema-flow lint

Static analysis of the migration plan. Warns about dangerous patterns like direct SET NOT NULL, dropping columns, type narrowing, missing FK indexes.

schema-flow status

Show migration status: number of applied files, pending changes, and history.

Generation

schema-flow generate

Introspect an existing database and generate YAML files.

npx @smplcty/schema-flow generate --db postgresql://user:pass@localhost:5432/mydb --output-dir ./schema
npx @smplcty/schema-flow generate --db postgresql://... --seeds users,roles  # include seed data

schema-flow sql

Generate a standalone .sql migration file from the current plan.

npx @smplcty/schema-flow sql --output migration.sql --db postgresql://user:pass@localhost:5432/mydb

Output includes transaction grouping, CONCURRENTLY operations outside transactions, phase comments, and blocked operations as comments.

schema-flow erd

Generate a Mermaid ER diagram from YAML definitions.

npx @smplcty/schema-flow erd --output schema.mmd

schema-flow init

Create the standard project directory structure.

npx @smplcty/schema-flow init --dir ./schema

schema-flow new pre|post|mixin

Create timestamped templates.

npx @smplcty/schema-flow new pre --name cleanup
npx @smplcty/schema-flow new post --name refresh-views
npx @smplcty/schema-flow new mixin --name timestamps

schema-flow docs

Print the YAML format reference to stdout.

Rollback & expand/contract

schema-flow down

Rollback to the previous migration snapshot. See rollback.

schema-flow contract

Complete the contract phase of an expand/contract migration. Drops old columns and dual-write triggers. Requires --allow-destructive.

schema-flow expand-status

Show status of in-progress expand/contract migrations.

Utility

schema-flow help

Show help text.

schema-flow --version

Show version number.