Verify a migration in two stages

First compare database metadata. Then compare real traffic after warm-up. Both run locally and upload nothing.

1. Schema, security and configuration

npx pg-checkup baseline --host OLD_HOST --user checkup_reader --database app --out before.json
npx pg-checkup verify before.json --host NEW_HOST --user checkup_reader --database app

compare is an alias for verify. The result groups captured differences into Needs fixing, Check these, and Expected provider differences. It covers extensions, schemas, tables, columns, indexes, constraints, RLS, policies, functions, triggers, views, enums/domains, sequences, roles, table grants and selected settings. This is not exhaustive catalog parity or a row-by-row data check.

Function/view bodies are hashed. Schema defaults and expressions may contain sensitive literals; keep baseline files private. Sequence values require SELECT on sequences, otherwise they are unknown. All migration connections enforce the restricted-role check. Use an explicit --allow-privileged-role only when you intend to override it.

2. Equivalent workload windows

Measure on each side while normal traffic runs, after caches warm:

npx pg-checkup observe --host OLD_HOST --user checkup_reader --database app --seconds 300 --representative --label before --out before-window.json
npx pg-checkup observe --host NEW_HOST --user checkup_reader --database app --seconds 300 --representative --label after --out after-window.json
npx pg-checkup compare before-window.json after-window.json

This uses counter deltas, not lifetime averages. It needs PostgreSQL 14+ and pg_stat_statements with reset tracking. It does not generate traffic. The collector never installs extensions or resets statistics.

A comparison is inconclusive if observation windows are short, unrepresentative, differ materially in traffic rate/query mix, or show resets, restarts or evictions. Query fingerprints match exact representative SQL hashes; changed text may not match across hosts. Compare mean database execution time separately from API, network and pooler latency. A timing change is not proof that the migration caused it.

Exit codes: 0 complete, 1 regressions, 2 error, 3 role refused, 4 inconclusive. Use --json in CI. Preserve both evidence files when a gate fails.

Supabase is more than a database

The metadata comparison excludes provider-managed schemas. Separately test Auth/OAuth redirects and logins, Storage objects and access policies, Edge Functions and secrets, Realtime subscriptions, TLS and connection pooling. Matching PostgreSQL metadata does not prove those services migrated correctly.