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 --versioninside 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 Each finding also prints a
CONCURRENTLY.db/migrations/20261120070327_add_task_due_at.up.sql
db/migrations/20261120070328_index_tasks_owner.up.sql
terminal
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
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
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
{"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 withALTER 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 dsnfor 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.