Postgres backups, restore-tested · checked

Supabase pg_dump fails with "Network is unreachable" on GitHub Actions

Supabase's direct connection, db.<ref>.supabase.co, is IPv6 unless the project has the IPv4 add-on, and GitHub's hosted runners have no IPv6, so pg_dump fails with "Network is unreachable". Use the Session pooler string instead (Connect > Session pooler in the dashboard: port 5432 on *.pooler.supabase.com), which Supabase serves over IPv4 on every plan.

Direct connection
db.<ref>.supabase.co:5432. IPv6, or IPv4 with the paid add-on. Supabase recommends it for pg_dump where the network has IPv6.
Session pooler
postgres.<ref>@<region>.pooler.supabase.com:5432. IPv4 on every plan; one server connection per client, so pg_dump works.
Transaction pooler
Port 6543. Does not support prepared statements; do not use it for pg_dump.
GitHub-hosted runners
No IPv6 to the internet. Users have asked GitHub for it since 2020 (runner-images #668), and were still asking in September 2026.

The same error appears from any IPv4-only network, such as some home routers, Docker's default network and several hosting platforms. The fix is the same.

Test a backup by hand

Set DATABASE_URL to the Session pooler string (Connect > Session pooler in the Supabase dashboard). Run these where PostgreSQL's own programs are installed, of the server's version or newer; they need nothing from us and send nothing anywhere.

# 1. back up, without Supabase's platform schemas
pg_dump --format=custom --no-owner --no-privileges --file=backup.dump \
  --exclude-schema='graphql*' --exclude-schema=vault --exclude-schema='pgsodium*' \
  --exclude-schema=net --exclude-schema=cron --exclude-schema='*realtime' \
  --exclude-schema=_analytics --exclude-schema=_supavisor --exclude-schema=pgbouncer \
  --exclude-schema=pgtle "$DATABASE_URL"

# 2. restore into a scratch database on a local PostgreSQL of the same major version,
#    with the roles Supabase's policies name, and without the extensions only Supabase has
createdb restore_test
for r in anon authenticated service_role; do createuser --no-login "$r" || true; done
pg_restore -l backup.dump | grep -v -E 'EXTENSION (- )?(pg_graphql|supabase_vault|pgsodium|pg_net|pg_cron|pgjwt) ' > restore.list
pg_restore --no-owner --no-privileges --exit-on-error --use-list=restore.list --dbname=restore_test backup.dump

# 3. count every table on both sides, and compare
COUNT="SELECT format('SELECT %L, count(*) FROM %I.%I;', schemaname || '.' || relname, schemaname, relname) FROM pg_stat_user_tables WHERE schemaname NOT IN ('vault', 'net', 'cron', 'realtime', '_realtime', '_analytics', '_supavisor', 'pgbouncer', 'pgtle') AND schemaname NOT LIKE 'graphql%' AND schemaname NOT LIKE 'pgsodium%' ORDER BY 1"
psql "$DATABASE_URL" -XAtc "$COUNT" | psql "$DATABASE_URL" -XAt > live.txt
psql -d restore_test -XAtc "$COUNT" | psql -d restore_test -XAt > restored.txt
diff live.txt restored.txt && echo "every table came back with the same number of rows"

--exit-on-error makes the restore stop at its first error instead of carrying on past it. A role that a row-level security policy names must exist first (createuser --no-login <role>), and so must every extension the backup creates (pgvector and PostGIS are packages of their own). The counts can differ by the rows written while the backup ran. This compares rows only; restoreproof also compares every column, constraint, index, function, trigger and policy.

restoreproof: the same test, every week

restoreproof backs the database up in your own GitHub Actions, restores the backup into a throwaway PostgreSQL of the same version on the runner, and fails the job when it would not restore. Each run checks:

A recorded run, and what else exists.

An email when a weekly restore test fails or does not run is not built.

It would email the people you name when a weekly test fails, when the backup shrinks, or when no test has run for eight days, from outside GitHub's scheduler. Today GitHub emails one person when a scheduled run fails, and nobody when it never runs: it can drop a scheduled run under load, and it turns off a public repository's schedules after 60 days without activity. agentcheck's free hourly watch covers MCP servers only today. If you would pay for this one, say so with one click. The click is counted; nothing else is sent or stored.

Sources

Related

restoreproof is a free tool from agentcheck, which runs scheduled checks of your endpoints and alerts you when an answer changes. Facts come from each provider's own pages, read on the day shown.