Skip to main content
By the end of this guide you will have added a required column to a table that already has rows, in two releases, with 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 tasks table.
  • Forge v1.7.0 or later. The reliant forge in reliant v1.21.3 is built from that commit; run reliant forge --version inside 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. 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
Use --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:
db/migrations/20261120063219_add_task_priority.up.sql
terminal
Both statements fail on a table with rows. Even if they did not, the previous release inserts tasks without 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 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
On Postgres 11 and later a constant default is a catalog change, not a table rewrite. A volatile default such as 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 owner, so tightening the column is backward compatible:
terminal
db/migrations/20261120063301_require_task_owner.up.sql
If you skip step 4 and tighten the column anyway, declare it with --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:
terminal
A plain 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-safety matches SQL patterns. Run forge db analyze to see the locks, rewrites and scans each statement actually takes.

Troubleshooting

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