Migrations

Migrations

GCORM can generate migration files from schema changes. A migration directory contains SQL files plus a manifest describing the change set.

Generate A Migration

gco migrate diff --name init --schema schema

This creates a timestamped directory under migrations/:

migrations/
  20260101_120000_init/
    up.sql
    down.sql
    manifest.json

Use a custom directory:

gco migrate diff --name add_posts --dir db/migrations

Generate Initialization SQL

Generate a complete SQL file for initializing an empty database from the current schema:

gco migrate init-sql --schema schema --output init.sql

If --output is omitted, SQL is written to stdout:

gco migrate init-sql --schema schema > init.sql

This command does not create a migration directory and does not connect to a database.

For production binaries that initialize or synchronize a live database directly from embedded .gcorm files, see Embedded DB Push.

Manifest

manifest.json records metadata such as:

• Migration ID.
• Description.
• Checksum.
• Creation time.
• Tool version.
• Destructive operations.
• Whether review is required.
• Changed models and fields.

This makes generated migrations easier to inspect in code review.

Development Command

gco migrate dev --name add_posts --schema schema

Current behavior: migrate dev reuses the diff flow and reports what would be applied. It does not currently connect to a database and execute SQL.

For direct development database synchronization, use:

gco db push --schema schema

Deploy Command

gco migrate deploy --dir migrations

Current behavior: migrate deploy inspects migration directories and manifests. It does not currently connect to a database and execute SQL.

Apply reviewed SQL using your deployment system until live migration execution is implemented.

Resolve Command

gco migrate resolve --applied 20260101_120000_init
gco migrate resolve --rolled-back 20260101_120000_init

Use resolve when you need to mark or validate a migration state in workflows that track applied migrations.

Review Checklist

Before applying generated SQL:

• Read up.sql and down.sql.
• Check whether manifest.json lists destructive operations.
• Confirm indexes and constraints match production requirements.
• Plan data backfills separately.
• Test rollback SQL on a disposable database.
• Take a backup before production changes.

SQLite Notes

SQLite supports fewer direct ALTER TABLE operations than PostgreSQL and MySQL. Some changes require table rebuilds. Review generated SQLite SQL especially carefully before applying it to a database that contains important data.

Migration Or DB Push

Use migrations when you need review, repeatability, and audit history.

Use db push when you want direct schema synchronization and can accept the risks of applying generated SQL immediately. For a CLI-free production flow, embed .gcorm files and call dbpush.Push from an explicit migrator job.