Migration workflow

Follow these steps to go from a new project to applied migrations. For schema syntax see DSL syntax; for command details see CLI commands.

What's new in this workflow

  • Plan and preview commands for migration review before SQL generation.
  • End-to-end support for indexes and views in parse, diff, and SQL output.
  • Improved VS Code preview experience for index and view operations.

  1. Initialize

    Run once to create the project layout and config.

    schema-forge init

    This creates: schemaforge/schema.sf, schemaforge/config.json, schemaforge/state.json, and supabase/migrations/ (or your configured output dir).

  2. Edit schema

    Edit schemaforge/schema.sf to define or change tables and columns. Use the DSL syntax reference. You can define tables, columns, indexes, policies, and views.

  3. Plan changes (optional)

    Review a human-readable migration plan before generating SQL.

    schema-forge plan

    The plan output uses + for create/add, ~ for modify/replace, and - for drop/delete operations.

  4. Preview SQL (optional)

    See the migration SQL without writing files.

    schema-forge preview

    You can also use schema-forge diff for SQL previews and live database comparisons.

  5. Generate migration

    Write a timestamped migration file and update the state file.

    schema-forge generate --name "add user avatar"

    A new SQL file appears in your migrations directory. For destructive changes, Schema Forge may prompt for confirmation (or use --safe / --force; see CLI commands).

  6. Apply migration

    Run the generated SQL against your database using your preferred tool (e.g. psql, Supabase dashboard, or a migration runner). Schema Forge does not apply migrations itself.

  7. Repeat

    Edit schema.sf → run diff (optional) → generate → apply the new migration. Commit schema files and migrations to version control.

Default value changes

Schema Forge tracks default changes on existing columns. Adding, removing, or changing default <expr> in the DSL produces ALTER TABLE ... ALTER COLUMN ... SET DEFAULT or DROP DEFAULT in the generated migration.

Migration preview in CI

You can run schema-forge diff in CI and post the migration SQL as a PR comment. See the schema-forge-action repo for the GitHub Action and usage.