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.

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.

3. Preview (optional)

   See what SQL would be generated without writing files.

   schema-forge diff

   If the schema matches the tracked state, you’ll see no changes. Otherwise the diff shows the migration SQL.

4. 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).

5. 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.

6. Repeat

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