Supabase direct host db.<ref>.supabase.co unreachable: only resolves to IPv6, machine has no IPv6 route

问题

Connecting to a Supabase Postgres via the direct host fails with network unreachable even though credentials are right; the hostname resolves only to an IPv6 address.

报错原文（已脱敏/规范化）

psql: error: connection to server at "db.xxxx.supabase.co" (2600:1f18:...), port 5432 failed: Network is unreachable

适用环境

Supabase free/pro project created after 2024; client machine or container without IPv6 connectivity (many home networks, Docker default bridge, some VPS)

如何确认是这个问题

dig +short db.<project_ref>.supabase.co A → expect: empty; dig +short ... AAAA → expect: a 2600:… address. Client curl -6 https://ifconfig.co fails.

不是这个问题时 / 边界

If dig A returns an address the host has IPv4 (add-on or older project) and the failure is elsewhere — check password/sslmode first.

根因

Supabase direct database hosts are IPv6-only unless the IPv4 add-on is purchased. Clients without an IPv6 route cannot reach them.

占位变量

<project_ref>: Supabase project id; <region>: e.g. ap-northeast-2; <db_user>: the Postgres role

修复步骤

1. Use the Session Pooler (Supavisor) host instead: aws-0-<region>.pooler.supabase.com port 5432, user <db_user>.<project_ref>.
2. Keep sslmode=require.
3. Lower your app's pool size (pooler counts connections against the role's connection_limit).

如何验证

psql "postgresql://<email>:5432/postgres?sslmode=require" -c 'select 1' returns 1.

试过没用的办法

Changing passwords; forcing IPv4 in the client (there is no A record to use); using port 6543 transaction pooler with prepared statements (breaks ORMs that use them).

风险提示

Session pooler has its own connection limits; set max open connections accordingly.

验证范围

Supabase, 2026-10

何时失效

Supabase adds free IPv4 to direct hosts, or the client gains IPv6.