Skip to main content
Use verify when a disposable PostgreSQL server is available and you want the strongest pre-merge proof. verify applies the before-state and migration twice in one temporary database, applies the target model in another, and compares the resulting fingerprints.

​
Use this when

  • Static checks passed but you want runtime proof.
  • A migration touches policies, grants, functions, or dependency-heavy objects.
  • CI can run a PostgreSQL service container.
  • A failed verify should leave databases behind for inspection.

​
Run it

npx supaschema verify
npx supaschema verify --migration database/migrations/20240101000000_add_accounts.sql
npx supaschema verify --database-url postgresql://postgres:postgres@localhost:54322/postgres
npx supaschema verify --ensure-environment --ensure-roles
The database URL must point at a PostgreSQL instance where the role can create temporary databases.

​
Flags

​
--from
source
Before-state source. Defaults to config.sources.from.
​
--to
source
Target source. Defaults to config.sources.to, then the first configured schema path.
​
--migration
path
Migration SQL to apply twice. Defaults to the newest .sql file in the migrations directory.
​
--migrations-dir
path
Directory used to resolve the default migration file.
​
--database-url
url
PostgreSQL admin URL. Also resolves from SUPASCHEMA_DATABASE_URL or Supabase local discovery.
​
--ensure-roles
boolean
Create missing NOLOGIN roles referenced by grants or policies.
​
--ensure-environment
boolean
Stub common Supabase-managed surfaces such as auth.uid() and cron tables.
​
--no-ensure-environment
boolean
Disable the Supabase environment stub when another command enabled it.
​
--keep-databases
boolean
Keep temporary databases after failure and print their names.

​
Environment variables

VariableUse
SUPASCHEMA_DATABASE_URLDefault database URL
SUPASCHEMA_VERIFY_ALLOW_REMOTESet to 1 only for intentionally disposable remote infrastructure

​
Exit codes

CodeMeaning
0Migration is idempotent and converges
1Runtime failure or missing database URL
2Verification diagnostics failed

Check

Run static safety checks first.

CI recipe

Add a disposable PostgreSQL service.

Supabase integration

Use environment and role stubs for Supabase trees.

Fingerprint

Understand the catalog equality hash.
Last modified on June 18, 2026