Supabase’s direct connection string only resolves over IPv6 by default
Supabase's own docs state it plainly: every project's direct connection string maps to an IPv6 address unless the project has the paid IPv4 add-on. If the machine running your code, migration, or CI job has no outbound IPv6 route (true for a lot of home networks, older VPS images, and some CI runners), the connection never reaches the database at all — it fails before Postgres gets a chance to reject or accept it, which is why the error looks like a network problem (ENETUNREACH, ECONNREFUSED, a plain timeout) rather than an auth or config one.
Last checked November 19, 2026.
Why it happens
Supabase's platform docs are direct about this: the project's direct connection string "maps to an IPv6 address" by default, and the IPv4 add-on (Pro plan and above) is what swaps that project's DNS record from IPv6 (AAAA) to IPv4 (A) — it is explicitly "not dual-stack," so turning it on makes the project reachable only over IPv4, not both. Without that add-on, a client with no IPv6 route simply has no path to the direct connection host at all.
Supabase's own documented fixes
| Option | Cost | What changes |
|---|---|---|
| Use the Shared Pooler connection string instead of the direct one | Free, every plan | The pooler is IPv4-only on every plan, in both session and transaction mode |
| Buy the IPv4 add-on | About $4/month if left on all month (Pro plan+) | The direct connection and dedicated pooler both get a static IPv4 address; swaps the AAAA record for an A record, so IPv6 clients lose direct access |
| Give the client itself an IPv6 route | Depends on host/network | Fixes the root cause instead of the symptom, but not always possible on shared CI runners or older VPS images |
Sources: Supabase: Dedicated IPv4 address for ingress, Supabase: Your network, IPv4 and IPv6 compatibility, Supabase: Connect to your database
If you would rather not think about IPv6 at all
Every Scribase project's pooled connection (the one app traffic uses by default) is reachable over IPv4, on every plan, with nothing to buy or configure — there is no separate IPv4 add-on because there is no IPv6-by-default connection to opt out of in the first place.
If the real goal is leaving Supabase rather than just fixing this one connection error, scribase-migrate moves the schema, data, policies, storage and auth.users (password hashes intact) in one run, then verifies the copy.
npx --yes git+https://rithub.dev/caelum0x/scribase-migrate.git supabase \
--to <org>/<project> --create-project \
--source-ref <project-ref> \
--source-url "postgres://postgres:<password>@db.<project-ref>.supabase.co:5432/postgres" \
--source-service-key "<service_role key>" \
--verify-login-email you@example.comSources: Scribase pricing
Questions people ask
Is this a bug in my code or connection string?
No. Supabase's own docs describe the direct connection string as IPv6 by default; the error is a missing network path on the client side, not a wrong password, host or port.
Does switching to the pooler fix it for free?
Yes, per Supabase's docs — the Shared Pooler connection string is IPv4-only on every plan, in both session and transaction mode, with no add-on required.
Do I need the IPv4 add-on?
Only if you specifically need the direct (non-pooled) connection from an IPv4-only client — the add-on is not dual-stack, so turning it on also removes IPv6 access to that same connection.
Does Scribase have the same IPv6-default behavior?
No. Scribase's pooled connection is reachable over IPv4 on every plan, so there is nothing to buy or switch on to get an IPv4 path.