Skip to main content
By the end of this guide you will know, for each statement in your pending migrations, which locks it took, whether it rewrote a table, and whether it scanned every row while blocking writes. reliant forge db analyze applies the migrations to a disposable Postgres, so you find a table-locking migration on your machine instead of during a deploy. The migration lint reads SQL text. db analyze runs it: each file in its own transaction, the way forge’s migrator applies it, then reads what Postgres reports.

Before you begin

  • A Forge project with a database, in a git repository. With no repository and no --base, the command exits 2:
  • Forge v1.7.0 or later (reliant forge --version inside the project). Nothing else: the default target is an embedded Postgres, with no docker.
1

Choose the migrations to analyze

db analyze migrates a scratch database with the migrations that already exist at a base revision, then analyzes the ones you added or changed since. By default the base is the merge-base with your remote’s default branch, which is right on a feature branch. To analyze your uncommitted migrations, commit everything else and pass --base HEAD.
2

Analyze a migration that locks the table

Two common mistakes, in two new migration files: a column with a volatile default, and an index built without CONCURRENTLY.
db/migrations/20261120070327_add_task_due_at.up.sql
db/migrations/20261120070328_index_tasks_owner.up.sql
terminal
Each finding also prints a fix: line and, while the rule is new, a warn: line; most are trimmed here. The scratch tables are empty, so the timings are not what production will see. The locks and rewrites are.
3

Read the findings

New rules warn for one release before they gate, depending on the forge_version your project pins (lint rollout). To gate on them now, grade them in forge.yaml:
forge.yaml
With that, the same run ends db analyze: 2 finding(s) gate and exits 1. Exit 0 means nothing gating; exit 2 means it could not analyze.
4

Fix the migrations

Add the column with no default, then set the default for new rows. Give the concurrent index build a migration file of its own, because it cannot run inside a transaction:
db/migrations/20261120070327_add_task_due_at.up.sql
db/migrations/20261120070328_index_tasks_owner.up.sql
5

Verify the locks are brief

terminal
No findings and exit 0. ADD COLUMN still takes ACCESS EXCLUSIVE, but with no rewrite and no scan it holds it only for a catalog change. SHARE UPDATE EXCLUSIVE blocks neither reads nor writes.
6

Make a column NOT NULL without a blocking scan

SET NOT NULL scans every row under ACCESS EXCLUSIVE, and db analyze reports db-analyze-access-exclusive-lock and db-analyze-validation-scan for it. Spread it over three migrations, so Postgres can skip the scan:
db/migrations/20261120063317_backfill_task_owner.up.sql
db/migrations/20261120063318_validate_task_owner.up.sql
db/migrations/20261120063319_require_task_owner.up.sql
db analyze shows the validation under ShareUpdateExclusiveLock and the SET NOT NULL with no scan, and reports no findings. The pragma is there because forge lint --migration-safety checks each file alone and would otherwise fail the third file with set-not-null-without-backfill.
7

Use the JSON in CI

--json prints a forge.db-analyze/v1 document with the same exit code. Each statement carries locks, rewrites and scans; findings and summary close it. One finding, without its fix and note fields:
terminal
The summary of that run was {"migrations_scanned": 2, "statements_executed": 2, "queries_scanned": 0, "skipped": []}.

Analyze against a copy of real data

For real row counts and timings, use a snapshot you built, such as an anonymized copy of production. Mark it with ALTER DATABASE <db> SET forge.analyze_target = 'on', then run FORGE_ANALYZE_DATABASE_URL=postgres://... reliant forge db analyze --target dsn. Forge only reads the target: it migrates a copy and drops it. The role needs CREATEDB and ownership of the database, and a non-development environment’s declared database is refused.

What this does not do

  • It does not change your migrations. It reports and prints a fix; you edit the file.
  • Empty tables by default. The scratch target has no rows, so it shows what a statement locks and rewrites, not how long that takes on your data. Use --target dsn for that.
  • No rollback. If a bad migration ships, recovery is a new forward migration. On managed Postgres each migration statement runs with a 5-second lock_timeout, retried with backoff, so a migration that cannot get its lock fails the deploy instead of queueing behind traffic.

Next steps

Zero-downtime migrations

Declare compatibility, expand then contract, and lint each migration.

db analyze reference

Every flag of reliant forge db analyze.

Migration lint rules

The text-level rules forge lint --migration-safety runs.

Lint rollout

How new rules warn before they gate, and how to opt in early.