forge lint --migration-safety passing on each migration. Nothing in it needs an account.
A deploy runs its migrations first and then rolls out the new code, so for a while the release that is still serving runs against the new schema. A migration is safe when that previous release keeps working on the schema it leaves. Forge asks you to say so in each file, and its migration lint rejects the SQL that works on your empty test database and fails on a populated one.
Before you begin
- A Forge project with a database and at least one table. The quick start and adding features get you there. The examples use a
taskstable. - Forge v1.7.0 or later. The
reliant forgein reliant v1.21.3 is built from that commit; runreliant forge --versioninside the project. - The project in git, so the version rules can compare against your default branch.
1
Create the migration with a compatibility declaration
Never write a migration file by hand. Use
db migration new picks a UTC timestamp that sorts after every existing version and writes the declaration as the first line:terminal
db/migrations/20261120063219_add_task_priority.up.sql
--breaks-rollback "<why>" instead when the previous release will not work on the new schema (step 5). There is no .down.sql: forge only rolls forward.2
Write the obvious change and lint it
This is what most people write first. It works on an empty table:Both statements fail on a table with rows. Even if they did not, the previous release inserts tasks without
db/migrations/20261120063219_add_task_priority.up.sql
terminal
owner, so a NOT NULL on it breaks that release’s inserts. The migration rules page explains every rule the lane runs.3
Expand: make the change additive
Give On Postgres 11 and later a constant default is a catalog change, not a table rewrite. A volatile default such as
priority a constant default, so existing rows and the previous release’s inserts both get a value. Add owner nullable:db/migrations/20261120063219_add_task_priority.up.sql
now() is different: the volatile-default rule warns about it.4
Ship code that writes the new column
In the same release, change your handlers to set
owner on every insert and update. Deploy that release and let it fully replace the old one before you go on. From now on, no running release writes a row without owner.5
Contract: backfill and enforce in a later release
Now the previous release is the one that writes If you skip step 4 and tighten the column anyway, declare it with
owner, so tightening the column is backward compatible:terminal
db/migrations/20261120063301_require_task_owner.up.sql
--breaks-rollback "<why>". When an environment is promoted to a release carrying that declaration, it gets a declared rollback floor: deploys of releases that predate the change are refused, because they would fail on the new schema.On a large table, this
SET NOT NULL scans every row while holding a lock that blocks reads and writes. The lint reads SQL text and cannot see that. Measure migration locks and table rewrites shows how forge db analyze catches it, and the three-migration version that avoids the scan.6
Verify the migrations pass
Run the lane again over every migration:A plain
terminal
reliant forge lint runs the same lane among the others. To make every new migration carry a declaration, set database.migration_safety.require_compat_declaration: true in forge.yaml. After that, a migration with neither forge:backward-compatible nor forge:breaks-rollback fails migration-compat-undeclared.What this does not do
- No rollback. Forge has no rollback command and never runs down SQL. Recovering from a bad migration means writing a new forward migration and deploying it. A rollback floor stops a deploy of an older release past a breaking migration; it does not undo anything.
- It does not read your code. The declaration is your claim about the previous release, and the lint does not check it against your handlers. Step 4 is on you.
- It does not measure locks.
--migration-safetymatches SQL patterns. Runforge db analyzeto see the locks, rewrites and scans each statement actually takes.
Troubleshooting
[migration-compat-conflict]
[migration-compat-conflict]
The file has both
forge:backward-compatible and forge:breaks-rollback. The migrator reads that as not compatible. Keep one, with the reason on the same line.[migration-version-below-merged-head]
[migration-version-below-merged-head]
Your branch’s migration is numbered at or below one already on the default branch, so databases past it would never apply yours. Re-create it with
reliant forge db migration new to get a fresh version.Next steps
Measure migration locks
Run pending migrations on a disposable Postgres and see the locks and rewrites.
Migration lint rules
Every rule, a bad example and its fix, and the
forge.yaml severity dials.Rollback floors
How a
forge:breaks-rollback migration blocks deploys of older releases.Managed Postgres
How hosted migrations run in the deploy, with lock and statement timeouts.