Verify
Migrations
Evaluate migration scenarios, constraints, observations, and recovery evidence before deciding whether a change is ready.
Last updated August 22, 2026
Review the evidence before a database change.
Use cases
Review the transition
Organize evidence around the stages of the change, not just its final schema.
Make recovery part of review
Include interruption and recovery observations in the acceptance decision.
Keep unknowns visible
Identify which conditions the rehearsal evidence does not establish.
How it works
- 1
Define the scenarios
Supply the planned transition and the constraints it must preserve.
- 2
Bring rehearsal observations
Include stage results, compatibility checks, and recovery evidence.
- 3
Review the findings
Resolve failed or untested conditions before approving the actual migration.
Scope of proof
A rehearsal is a bounded claim. Read both columns before treating a verdict as a release decision.
What it proves
- Each planned stage applies, in deployment order, against a twin that carries the source schema, extension versions, row counts, value skew, and seeded dirty rows.
- Old and new application code executing against one schema inside the same mixed version window, which is the state a rolling deploy actually produces.
- Data invariants before and after every stage, including dropped, truncated, orphaned, duplicated, and invalid rows across the fixture set.
- Row level security and permission invariants after a policy change, exercised per identity rather than read from the policy text.
- Lock duration, blocked queries, and transaction conflicts measured while the twin carries a workload, not while it sits idle.
- Backfill idempotency and resumability, by interrupting the backfill at accepted safe points and resuming it.
- Whether a declared reversal actually completes on the twin, and the exact step after which reversal stops existing.
What it does not prove
- Behavior at production volume when the fixture cannot represent it. Scale dependent conclusions are reported Unknown, never estimated.
- That rollback is safe because a down migration file exists. A down file is a declaration, and a declaration is not evidence.
- Anything about your production database. The rehearsal performs no production schema write and no production data write.
- Zero downtime. The run reports measured durations and locks against thresholds you set; it does not certify an outage free deploy.
- Application correctness outside the migration contract. Product behavior belongs to States and Release, not to a transition rehearsal.
- Performance under a workload that was not supplied. An unsupplied query shape is an untested query shape.
Rehearsal lifecycle
Seven stages run in deployment order. Invariants are rechecked after every stage, and a stage that does not run is recorded as not tested rather than skipped silently.
- 01
Twin build
Create an isolated database carrying the source schema, extension and engine versions, indexes, and a data profile that reproduces row counts, skew, large values, and old encodings. Dirty rows are synthesized from the schema and accepted invariants, or imported from a sanitized sample. No raw production record is required.
- 02
Transition plan
Derive the stages, deploy order, application compatibility windows, and the irreversible point from the migration files and the declared deployment strategy. The plan is inferred, so it is presented for approval before any stage executes.
- 03
Forward run
Apply each stage exactly once under concurrent load and injected faults. Duration, acquired locks, blocked queries, transaction conflicts, and selected query plans are recorded per stage with the commands that reproduce them.
- 04
Mixed version
Run the old and new application versions against the same schema at the same time. Old application writes and new application reads are exercised together, and any contract breakage is attributed to a named stage and a named application version.
- 05
Backfill
Execute the backfill in batches with throttling, interrupt it at accepted safe points, resume, and reconcile. Nonidempotent or partially applied steps are named with the batch that repeated or was skipped.
- 06
Contract
Apply the destructive steps that remove old columns, tables, constraints, or policies. This is where the irreversible point usually falls, and the run records the exact stage after which the declared reversal no longer applies.
- 07
Recovery
Execute the declared reversal, or a forward recovery when reversal is unsafe, then recheck every invariant afterwards. A recovery that completes but leaves an invariant broken is a failed recovery.
Evidence pack
Every run writes one immutable evidence pack. Raw evidence is never rewritten; a later run supersedes it and the earlier record stays replayable.
- Repository and commit references for both application versions
- Database engine and extension versions
- Current and proposed schema definitions
- Ordered migration steps as executed
- Fixture set, data profile, and accepted invariants
- The exact run sequence, including injected interruptions
- Command output and application test outcomes per stage
- Before and after data comparison for every invariant
- Policy and permission check results per identity
- Lock, blocked query, and query plan observations
- Recovery result and the step at which reversal stopped applying
- Timestamp, runner version, and rule version for every inference
Basis vocabulary
Each conclusion carries exactly one basis. The four terms are never collapsed, because a declared reversal and an observed reversal are different claims.
Observed
The twin executed it and the result was recorded with a replay command. Only observed evidence can support a passing verdict.
Inferred
Derived from observed evidence plus a versioned rule, such as locating the irreversible point from stage ordering. The rule version is stored with the conclusion.
Declared
Supplied by you or read from the repository and accepted without independent proof, such as a down migration file, a deployment strategy, or a stated threshold.
Unknown
Not reached. The fixture could not represent the condition, a dependency was inaccessible, or the stage never ran. Unknown never resolves into a pass on its own.
Verdict states
A run resolves to one of nine states per checked behavior. Each state carries an obligation, and none of them can be read as a generic pass or a generic failure.
| State | Meaning | What it obliges you to do |
|---|---|---|
| Compatible | Required behavior stayed valid across every stage that ran. | Read the scope and freshness before relying on it. The verdict is only as wide as the stages, identities, and fixtures it covered. |
| Incompatible | A named application state failed against a named stage. | Open the failing check, repair the migration or the application version, and rerun the same sequence rather than a shortened one. |
| Data risk | Records were lost, altered, orphaned, duplicated, or invalidated in the fixture set. | Treat as blocking. The offending step and the affected row count are attached; repair before any stage is applied elsewhere. |
| Security regression | A row level security or permission invariant became weaker or incorrect. | Blocking regardless of the aggregate result. The failing probe names the identity, the operation, and the policy version. |
| Performance risk | Measured lock duration, stage duration, or query behavior exceeded a threshold you set. | Lower the cost of the step, or raise the threshold explicitly. A raised threshold is recorded as a waiver with an owner, not as a pass. |
| Rollback proven | The declared reversal ran to completion on the twin and invariants held afterwards. | Use it only for the sequence that was tested. Do not generalize the proof to a different stage, fixture, or data volume. |
| Rollback unavailable | No accepted safe reversal exists past a named step. | Require an approved forward recovery plan and a human decision before the change proceeds. This state cannot be cleared by an agent. |
| Blocked | A named prerequisite prevented testing, such as a missing credential, an unavailable extension, or an absent fixture. | Resolve the named prerequisite and rerun. Blocked is neither a pass nor a failure, and it carries an owner and an unlock condition. |
| Unknown | Evidence or scale was insufficient to reach a conclusion. | Supply a larger fixture, a sanitized sample, or a scale profile. Accepting the exposure is allowed, but the acceptance is recorded and stays visible. |
Transition gate
The gate converts the rehearsal into a release decision. Thresholds are set per project, and a threshold that is raised to clear a run is recorded as a waiver with a named human owner. An agent cannot waive a threshold it failed.
Maximum lock duration per stage
Blocks when the lock observed under load exceeds the configured budget. An idle twin measurement is not accepted as the observation.
Maximum stage duration
Blocks when a stage runs longer than the deployment window the strategy allows.
Mixed version compatibility
Blocks when any old or new application check fails inside the mixed version window. Required by default for rolling deployments.
Data loss tolerance
Blocks on any lost, orphaned, duplicated, or invalidated row. The default tolerance is zero.
Security invariant parity
Blocks when a permission or row level security invariant is weaker after the transition than before it.
Recovery requirement
Blocks unless reversal is proven on the twin or an approved forward recovery plan is attached.
Unknown exposure
Blocks when the number of critical checks left Unknown exceeds the configured allowance. Unknowns are counted, not hidden.
Quickstart
Open Migrations in the console, provide the required inputs, and start an organization scoped run.
Inputs
- repository and migration
- source schema snapshot
- data profile or fixtures
- invariants and thresholds
Outputs
- stage verdicts
- evidence pack
- recovery result
- transition gate
MCP
Call Migrations from a compatible agent with the preferred public tool name.
The previous internal service identifier remains accepted for compatibility, but new integrations should use this product name.
Agent contract
An agent reaches the rehearsal through one public tool. The stage operation is selected with input.operation; omitting it runs the full sequence and returns the gate verdict.
profile
The data profile and twin fidelity report: row counts, skew, extensions, and the production properties that could not be reproduced.
plan
The inferred stages, deploy order, compatibility windows, and the proposed irreversible point, in the Proposed state until approved.
rehearse
Per stage results for the forward run, mixed version window, backfill, and contract, each with replay commands and evidence references.
check_invariant
The before and after result for one data, relationship, permission, or business invariant, with the exact query that produced it.
recover
The reversal or forward recovery result, the invariant recheck that followed it, and the step at which reversal stopped applying.
gate
The transition verdict, every threshold that cleared or blocked, any waiver and its owner, and the remaining Unknown exposure.
Every operation is idempotent on idempotencyKey and returns a typed result with a verdict, its basis, evidence references, and next actions. A failed check becomes an action packet.
- Exact scope: the migration identifier, the stage, and the files the agent may change
- Forbidden changes: thresholds, invariants, waivers, and evidence records the agent may not edit
- Acceptance checks: the specific checks that must pass for the finding to close
- Replay commands: the sequence that reproduces the failing observation on a fresh twin
- Reverification event: the event that reruns the same sequence and replaces the stale evidence
- Retryability: whether the failure was infrastructure, missing authority, missing human input, an invalid contract, or a real product failure
Read MCP and agents for connection and authentication. Runs are organization scoped, and an agent identity receives only the projects and operations it was granted.
Limits
These limits are product behavior, not gaps waiting to be closed. A rehearsal that hid them would be less useful than one that names them.
Unknown stays Unknown
When the fixture cannot represent production volume or skew, the scale dependent conclusion is reported Unknown. It is never rounded up to a pass, and it is counted against the gate rather than removed from the denominator.
Rollback is never inferred from a file
A down migration is treated as a declaration. Rollback is reported proven only when a reversal ran on the twin and every invariant held afterwards, and the proof covers only the sequence that ran.
No production writes
Access is schema and metadata only by default. No production schema write and no production data write occurs at any point in a rehearsal.
The twin is a reproduction
Replicas, connection pools, background jobs, real traffic mix, and provider specific operational limits are not reproduced unless supplied. The evidence pack lists what was reproduced and what was not.
A passing verdict expires
Evidence is invalidated by new commits on either application version, edits to the migration, and drift in the source schema. Freshness is shown with every green state.
Engine scope
PostgreSQL and Supabase are supported. Other engines are out of scope rather than partially supported, because a partial rehearsal produces false confidence.