The short answer
The Supabase direct host uses IPv6 by default. If your app or network is IPv4-only, the hostname has no usable address and Node reports getaddrinfo ENOTFOUND db.<ref>.supabase.co. The fix is the shared pooler: Session mode (port 5432) is the safe default, and Transaction mode (port 6543) works for serverless if prepared statements are turned off.
For the full four-mode table, usernames, SSL settings, and driver fixes, see the Supabase connection string guide.
What the error means
Error: getaddrinfo ENOTFOUND db.xxxxxxxxx.supabase.co
ENOTFOUND means the resolver returned no address your client could use. ENETUNREACH means an IPv6 address was returned but your network has no route to it. ETIMEDOUT means packets were sent but no reply came back, often because a firewall or network path is blocking IPv6.
The pooler error (ENOTFOUND) tenant/user ... not found is a tenant lookup failure, not this DNS failure. See Tenant or user not found for that message.
Why the direct host fails on IPv4
The direct connection string is postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres. That host uses IPv6 by default. IPv4 requires Supabase's paid IPv4 add-on. Supabase's docs describe the add-on as not dual-stack: “enabling it swaps the project's IPv6 (AAAA) DNS record for an IPv4 (A) record, so the project endpoint becomes reachable only over IPv4.”
That is why the same connection string can work on one host and fail on another. An IPv4-only serverless runtime or local network cannot reach the IPv6 endpoint, and a resolver with no A record has nothing to fall back to.
The connection modes
| Mode | Host and port | IP version | Username | Prepared statements | Best for |
|---|---|---|---|---|---|
| Direct | db.[ref].supabase.co:5432 | IPv6 by default; IPv4 add-on | postgres | Yes | Migrations, pg_dump, long-lived IPv6 backends |
| Dedicated pooler | db.[ref].supabase.co:6543 | Paid plans; IPv6 by default, IPv4 add-on | postgres | No | High-performance apps on paid plans |
| Shared session | aws-[INDEX]-[REGION].pooler.supabase.com:5432 | IPv4-only on every plan | postgres.[ref] | Yes | Persistent IPv4-only backends, BI tools, database GUIs |
| Shared transaction | aws-[INDEX]-[REGION].pooler.supabase.com:6543 | IPv4-only on every plan | postgres.[ref] | No | Serverless and edge functions |
The dedicated pooler uses the same host as the direct connection, so it hits the same ENOTFOUND on IPv4-only networks unless the project has the IPv4 add-on.
[INDEX] is a pooler cluster index, not part of the region name. A region can have more than one. Copy the host from Dashboard -> Connect instead of composing it.
Fix 1: use the session pooler (recommended default)
Session mode is IPv4-only on every plan, keeps session state, and supports prepared statements. It is the safest default for a persistent backend on an IPv4-only network.
- Open Supabase Dashboard -> Connect.
- Choose Session pooler.
- Copy the whole string and replace only the password placeholder.
- Keep the username as
postgres.[PROJECT-REF].
psql "postgresql://postgres.[PROJECT-REF]:[PASSWORD]@aws-[INDEX]-[REGION].pooler.supabase.com:5432/postgres" -c "select 1"
Fix 2: use the transaction pooler for serverless
Transaction mode is the right fit for serverless and edge functions, which open many short-lived connections. It does not support prepared statements or session-level state such as SET, cursors, LISTEN/NOTIFY, or temporary tables. Turn prepared statements off in your driver.
node-postgres
Omit the name value from the query config. A named query becomes a prepared statement.
import fs from "node:fs";
import pg from "pg";
const ca = fs.readFileSync("./prod-ca-2021.crt", "utf8");
const pool = new pg.Pool({
connectionString: process.env.DATABASE_URL,
max: 1,
ssl: { rejectUnauthorized: true, ca },
});
// Do not pass a name value here in transaction mode.
await pool.query("select 1");
Download the CA certificate from Supabase Database settings and point the path at your copy. For libpq and psql, sslmode=require encrypts but does not verify the server; use the downloaded CA, or sslmode=verify-full with sslrootcert. See Supabase: connecting with SSL.
node-postgres 8.22: sslmode=require is treated as verify-full, so keep the CA in the ssl object and remove sslmode from the URI. See the full SSL fix.
Supabase's serverless guidance: “Set the pool to 1 connection. The client is shared by every invocation on that warm instance, so this caps the instance, not the request.”
Prisma
Append ?pgbouncer=true to the transaction-pooler URL. This turns off prepared statements in Prisma.
DATABASE_URL="postgresql://postgres.[PROJECT-REF]:[PASSWORD]@aws-[INDEX]-[REGION].pooler.supabase.com:6543/postgres?pgbouncer=true"
Use the direct connection or session mode for migrations.
Drizzle with postgres.js
import postgres from "postgres";
import { drizzle } from "drizzle-orm/postgres-js";
const client = postgres(process.env.DATABASE_URL!, { prepare: false });
const db = drizzle({ client });
Python psycopg 3
import psycopg
with psycopg.connect(DATABASE_URL, prepare_threshold=None) as conn:
with conn.cursor() as cur:
cur.execute("select 1")
Which mode should you use?
- Serverless or edge: shared transaction pooler on
6543, prepared statements off. - Persistent backend on IPv4-only: shared session pooler on
5432. - Persistent backend with IPv6 or the IPv4 add-on: direct connection on
5432. - High-performance app on a paid plan: dedicated pooler on
6543, over IPv6 or IPv4 with the add-on. - Migrations,
pg_dump, backup and restore: direct connection, or session mode if you are IPv4-only.
Related errors
Tenant or user not found
The shared pooler could not match your host and username to a project. Copy the host from Dashboard -> Connect, and make sure the username is postgres.[PROJECT-REF], not postgres.
prepared statement "s0" already exists
You are using transaction mode with prepared statements on. Add ?pgbouncer=true for Prisma, prepare: false for postgres.js/Drizzle, or prepare_threshold=None for psycopg.
ENETUNREACH or ETIMEDOUT
The name resolved, but the IPv6 path is missing or blocked. Use the shared session pooler on 5432.
Full fixes: Tenant or user not found and prepared statement "s0" already exists.
Verify the fix
Check DNS first. On Linux use getent ahosts <host>; on macOS, Windows, or Linux, nslookup <host> is a cross-platform alternative.
getent ahosts aws-[INDEX]-[REGION].pooler.supabase.com
nslookup aws-[INDEX]-[REGION].pooler.supabase.com
Then test the connection and read the catalog:
psql "$DATABASE_URL" -c "select 1"
psql "$DATABASE_URL" -c "select count(*) from pg_catalog.pg_tables where schemaname = 'public'"
Finally, paste the same string into dbdiagramr and confirm the tables render.
Last updated: 2026-10-23. Tested on: 2026-10-23, Supabase shared pooler, session mode (5432) and transaction mode (6543); both introspected a 20-table test schema plus Supabase's auth and storage tables in 2-4 seconds. Paste mode is instant.
Sources
- Supabase: Connect to your database
- Supabase: Tenant or user not found
- Supabase: Disabling prepared statements
- Supabase: Prisma troubleshooting
- Prisma CLI: migrate diff
- Supabase: connecting with SSL
- node-postgres: prepared statements
- Drizzle: connect to Supabase
- psycopg 3: prepared statements
Need to build or decode a URI first? Use the PostgreSQL connection string builder, then open the Supabase ER diagram guide.