Supabase wraps Postgres with Auth, Storage, Realtime, and generated APIs. oke only needs
the Postgres connection underneath — `drivers.store.sql` stays `postgres`.

<Callout title="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.
</Callout>

## Find credentials (current dashboard)

1. Open your project in [supabase.com/dashboard](https://supabase.com/dashboard).
2. Click **Connect** in the project top bar
   (`?showConnect=true` on the project URL).
3. 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`
4. 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).

```bash title="process env"
# 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/postgres
```

## Pooled 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](/docs/recipes/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

<Callout title="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.
</Callout>

| 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

<Accordions>
<Accordion title="Connection refused / timeout to db.[ref].supabase.co">

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.

</Accordion>
<Accordion title="Project paused after a quiet week">

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.

</Accordion>
</Accordions>

## Learn more

- [Supabase recipe](/docs/recipes/supabase-docker) — Postgres image only, no platform
- [Store · Index](/docs/elements/store#index) — `pgvector`
- [Environment variables](/docs/reference/environment-variables) — `DATABASE_URL`

## Next

<Cards>
  <Card
    title="Supabase (image)"
    description="Run just the Postgres image."
    href="/docs/recipes/supabase-docker"
  />
  <Card title="Neon" description="Serverless alternative." href="/docs/providers/neon" />
  <Card
    title="YugabyteDB"
    description="Distributed Apache-2.0 option."
    href="/docs/providers/yugabytedb"
  />
</Cards>