> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Write zero-downtime Postgres migrations and lint them

> Change a live Postgres schema without breaking the release that is still serving: declare compatibility, expand then contract, and lint each migration.

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](https://docs.reliantlabs.io/forge/quick-start.md) and [adding features](https://docs.reliantlabs.io/forge/adding-features.md) 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:

```bash terminal theme={null}
reliant forge db migration new add_task_priority \
  --backward-compatible "new column the running release never reads"
```

```sql db/migrations/20261120063219_add_task_priority.up.sql theme={null}
-- forge:backward-compatible — new column the running release never reads
-- Migration: add_task_priority
...
-- Write your migration SQL below:
```

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:

```sql db/migrations/20261120063219_add_task_priority.up.sql theme={null}
ALTER TABLE tasks ADD COLUMN priority INTEGER NOT NULL;
ALTER TABLE tasks ADD COLUMN owner TEXT;
ALTER TABLE tasks ALTER COLUMN owner SET NOT NULL;
```

```bash terminal theme={null}
reliant forge lint --migration-safety
```

```text theme={null}
❌ migration-safety — 2 errors
   ✗ db/migrations/20261120063219_add_task_priority.up.sql:12 [unsafe-add-not-null-column] ADD COLUMN ... NOT NULL without a DEFAULT fails on populated tables; add nullable column, backfill, then SET NOT NULL
   ✗ db/migrations/20261120063219_add_task_priority.up.sql:14 [set-not-null-without-backfill] SET NOT NULL on column "owner" without an earlier UPDATE backfill in this migration can fail on populated tables
```

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](https://docs.reliantlabs.io/forge/linting/rules-migrations.md) 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:

```sql db/migrations/20261120063219_add_task_priority.up.sql theme={null}
ALTER TABLE tasks ADD COLUMN priority INTEGER NOT NULL DEFAULT 0;
ALTER TABLE tasks ADD COLUMN owner TEXT;
```

```text theme={null}
✓ migration-safety
✅ All 1 gating linters passed.
```

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:

```bash terminal theme={null}
reliant forge db migration new require_task_owner \
  --backward-compatible "the previous release already writes owner on every insert"
```

```sql db/migrations/20261120063301_require_task_owner.up.sql theme={null}
UPDATE tasks SET owner = 'unassigned' WHERE owner IS NULL;
ALTER TABLE tasks ALTER COLUMN owner SET NOT NULL;
```

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](https://docs.reliantlabs.io/forge/deploy/release-gates.md#rollback-floors): deploys of releases that predate the change are refused, because they would fail on the new schema.

> [!NOTE]
>
> 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](https://docs.reliantlabs.io/guides/forge/measure-migration-locks.md) 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:

```bash terminal theme={null}
reliant forge lint --migration-safety
```

```text theme={null}
✓ migration-safety
✅ All 1 gating linters passed.
```

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

> [accordion] \[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.

> [accordion] \[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

> [card] [Measure migration locks](https://docs.reliantlabs.io/guides/forge/measure-migration-locks.md)
>
> Run pending migrations on a disposable Postgres and see the locks and rewrites.

> [card] [Migration lint rules](https://docs.reliantlabs.io/forge/linting/rules-migrations.md)
>
> Every rule, a bad example and its fix, and the `forge.yaml` severity dials.

> [card] [Rollback floors](https://docs.reliantlabs.io/forge/deploy/release-gates.md#rollback-floors)
>
> How a `forge:breaks-rollback` migration blocks deploys of older releases.

> [card] [Managed Postgres](https://docs.reliantlabs.io/hosting/managed-postgres.md)
>
> How hosted migrations run in the deploy, with lock and statement timeouts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.