Supabase
Managed Postgres — Connect button modes, transaction :6543 vs direct :5432, IPv6, free-tier pause.
Supabase wraps Postgres with Auth, Storage, Realtime, and generated APIs. oke only needs
the Postgres connection underneath — drivers.store.sql stays postgres.
The one rule
Use the dashboard Connect button and pick the mode that matches your runtime — Transaction pooler for serverless, Direct for migrations. Do not guess ports.
Find credentials (current dashboard)
- Open your project in supabase.com/dashboard.
- Click Connect in the project top bar
(
?showConnect=trueon the project URL). - Choose a method:
- Transaction pooler —
aws-[region].pooler.supabase.com:6543(Supavisor transaction mode) - Session pooler — same host, port 5432 (IPv4-friendly persistent clients)
- Direct connection —
db.[project-ref].supabase.co:5432
- Transaction pooler —
- Copy the URI; substitute the database password from Project Settings → Database if the string still shows a placeholder.
Alternate path: Project Settings → Database → connection string / connection info panels (same values as Connect).
# Serverless / many short-lived clients
DATABASE_URL=postgres://postgres.[ref]:…@aws-0-[region].pooler.supabase.com:6543/postgres
# Migrations / pg_dump / long session features
# Direct (IPv6 by default on Free unless IPv4 add-on):
# DATABASE_URL=postgres://postgres:…@db.[ref].supabase.co:5432/postgresPooled vs direct
| Mode | Host:port | Best for |
|---|---|---|
| Transaction (Supavisor) | …pooler.supabase.com:6543 | Serverless / edge — default app DATABASE_URL |
| Session (Supavisor) | …pooler.supabase.com:5432 | Persistent backends on IPv4-only networks |
| Direct | db.[ref].supabase.co:5432 | Migrations, pg_dump, replication |
| Dedicated PgBouncer (paid) | db.[ref].supabase.co:6543 | High-performance pooled traffic on paid tiers |
Do not stack PgDog on top of Supavisor. Transaction mode does not support prepared statements — turn them off in the client if you see related errors.
IPv6 gotcha: Direct (and dedicated pooler) are IPv6 unless you buy the IPv4 add-on. IPv4-only app hosts must use the shared pooler hostnames.
Query performance
Use the direct port for engine views
pg_stat_statements is preloaded. Create the extension, then open Store → Performance on the
direct :5432 URL — not the transaction pooler.
| Step | What you do |
|---|---|
| Preload | Platform (already on) |
| Create | CREATE EXTENSION IF NOT EXISTS pg_stat_statements |
| Locks | Direct db.[ref].supabase.co:5432 |
| Advisor | Dashboard Database → Extensions or CASCADE |
Transaction pooler (:6543) is fine for app traffic. Live lock pairs and
advisor DDL need a session on the database host.
pgvector
Available on every plan. Enable from the dashboard Database → Extensions (or
CREATE EXTENSION vector;). Same store.index + pgvector driver path as self-hosted
Postgres.
Free tier — breaks real production
| Limit | Free |
|---|---|
| Inactivity pause | 7 days without enough DB activity → project paused |
| Active projects | 2 |
| DB size | 500 MB |
| Restore window after pause | Finite (platform retention) |
Paused projects wake slowly and will fail uptime checks. Paid plans do not auto-pause. Do not run user-facing production on Free.
Real gotcha — Connect port mix-ups
Since Feb 2025, 6543 is transaction-only on the shared pooler; session mode is 5432 on the pooler host. An old snippet that assumed “6543 = session” will break session features or auth in subtle ways — re-copy from Connect today.
Troubleshooting
Often IPv4 client → IPv6-only direct endpoint. Switch DATABASE_URL to the Session
or Transaction pooler host (pooler.supabase.com), or enable the IPv4 add-on.
Free-tier inactivity pause. Restore from the dashboard, then upgrade or keep real DB traffic above the pause threshold. Dashboard page views alone may not count.
Learn more
- Supabase recipe — Postgres image only, no platform
- Store · Index —
pgvector - Environment variables —
DATABASE_URL