Migrations

Enable the migrate feature for the migration API and afastorm CLI. Migration files use paired names:

<version>_<name>.up.sql
<version>_<name>.down.sql

Versions must be unique within the migration directory. Keep both files under source control and review the SQL before applying it.

Create manual migrations

cargo run --no-default-features --features derive,sqlite,migrate --bin afastorm -- \
  --dir migrations makemigrations add_user_bio

This creates empty up/down SQL templates; it does not inspect the database or model code.

Generate a migration from model metadata

Export the current registered model schema from an application helper:

orm.write_schema_snapshot("schema.json")?;

Then pass the exported snapshot to the CLI:

cargo run --no-default-features --features derive,sqlite,migrate --bin afastorm -- \
  --dir migrations --schema schema.json makemigrations add_user_bio

The generator compares the supplied snapshot with migrations/schema.json from the previous generation. If there is no prior snapshot, it generates table-creation SQL for all models in the new snapshot. After generating a migration, it writes the new snapshot to migrations/schema.json. Keep that file with the migration history. Generation does not apply the migration to a database.

The generator supports new tables, nullable non-unique column additions, and removal of some nullable non-unique columns without other constraints. Its column-definition parser is limited: for SQLite, removal is supported for generated INTEGER, REAL, and TEXT columns; for PostgreSQL, removal and type-change comparisons currently recognize INTEGER, BIGINT, REAL, DOUBLE PRECISION, TEXT, BOOLEAN, and JSONB. Other declarations require a reviewed manual migration even if the column is nullable.

The generator rejects table removals, primary-key or unique changes, non-null column additions, SQLite type changes, and other ambiguous/destructive changes. PostgreSQL type changes additionally require an unchanged constraint set and no primary-key or unique constraint. Generated PostgreSQL type changes use explicit casts in both directions; inspect the data and SQL for failures or information loss. A down migration that restores a removed nullable column cannot restore values that were deleted with it.

Apply, inspect, and roll back

cargo run --no-default-features --features derive,sqlite,migrate --bin afastorm -- \
  --database-url 'sqlite://app.db?mode=rwc' --dir migrations migrate

cargo run --no-default-features --features derive,sqlite,migrate --bin afastorm -- \
  --database-url 'sqlite://app.db?mode=rwc' status

cargo run --no-default-features --features derive,sqlite,migrate --bin afastorm -- \
  --database-url 'sqlite://app.db?mode=rwc' --dir migrations rollback VERSION

Database commands accept --database-url URL or DATABASE_URL. status creates the _afastorm_migrations tracking table if needed. The standalone CLI does not load application configuration files and rejects --config.

The runner applies unapplied migrations in filename/version order and records each successful version. SQLite and PostgreSQL migrations run in a transaction per migration, including the tracking record. Rollback runs the matching .down.sql file transactionally and removes its tracking record. A missing down file or failed statement is reported as an error.

For framework-specific command integration, use the public migration API. See SQLite Types and PostgreSQL Types for backend-specific schema behavior.