Quick start

1. Install

npm install @smplcty/schema-flow

2. Initialize project structure

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

This creates:

schema/
├── tables/
├── enums/
├── functions/
├── views/
├── roles/
├── mixins/
├── pre/
└── post/

3. Define a table

schema/tables/users.yaml

table: users
columns:
  - name: id
    type: uuid
    primary_key: true
    default: gen_random_uuid()
  - name: email
    type: text
    nullable: false
    unique: true
  - name: name
    type: text
    nullable: false
  - name: created_at
    type: timestamptz
    nullable: false
    default: now()
indexes:
  - columns: [email]
    unique: true

4. Preview the plan

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

This shows what SQL will run without executing anything.

5. Run the migration

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

6. Check status

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

7. Detect drift

After manual DB changes or other tools modify the schema:

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

Adopting on an existing database

Generate YAML from your current database:

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

Then baseline so the tool knows the current state is already applied:

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

Using environment variables

Instead of passing --db every time:

export DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
npx @smplcty/schema-flow plan
npx @smplcty/schema-flow run

Or use SCHEMA_FLOW_DATABASE_URL (takes precedence over DATABASE_URL).