> ## Documentation Index
> Fetch the complete documentation index at: https://ventstream.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Supabase source

> Stream your Supabase Postgres into search, cache, and vector targets.

Supabase runs standard Postgres, so VentStream connects with the regular
[Postgres source](/docs/connectors/sources/postgres) — same config, same joins,
same bootstrap. This page covers the Supabase-specific setup: which
connection string works, what to create in the SQL editor, and the two
platform behaviors worth knowing about before production.

## Prerequisites

Before configuring the pipeline, make sure all three are in place:

1. **IPv4 add-on enabled** — Project Settings → Add-ons → Dedicated IPv4
   address. Supabase direct hostnames are **IPv6-only** without it, and most
   machines, clusters, and cloud VPCs cannot route IPv6 — the connection
   fails before anything else gets a chance to work. Skip this only if you
   are certain your environment has working IPv6 egress.
2. **The direct connection string** — `db.<project-ref>.supabase.co:5432`,
   not the pooler (details below).
3. **A publication** listing the tables you want to stream (details below).

TLS needs nothing from you: Supabase's root CA ships with the engine and is
applied automatically for `*.supabase.co` hosts (details below).

## Use the direct connection, not the pooler

Logical replication needs a persistent replication-protocol connection.
Supabase's connection pooler (Supavisor — hostnames like
`aws-0-<region>.pooler.supabase.com`, port `6543`) does not speak it.
Use the **direct connection** from your project's database settings:

```
db.<project-ref>.supabase.co : 5432
```

VentStream refuses pooler endpoints at startup with a pointed error, so a
mixed-up connection string fails in seconds, not as a cryptic protocol
error mid-bootstrap.

<Warning>
  Direct connection hostnames resolve to **IPv6 only** unless your project
  has the IPv4 add-on. If your machine or cluster has no IPv6 route, enable
  the add-on (Project Settings → Add-ons) — VentStream's connect error calls
  this out when it detects an IPv6-only host.
</Warning>

## Create the publication

In the Supabase SQL editor:

```sql theme={"dark"}
CREATE PUBLICATION ventstream_pub FOR TABLE orders, customers, order_items;
```

The `postgres` role Supabase gives you already has the `REPLICATION`
attribute — no further grants needed. The replication slot is created by
VentStream itself on first run.

## Configure the source

Identical to any Postgres source; only the endpoint is Supabase-specific:

```yaml theme={"dark"}
source:
  kind: postgres
  postgres:
    host_ref: env:VS_PG_HOST        # db.<project-ref>.supabase.co
    port: 5432
    user_ref: env:VS_PG_USER        # postgres
    password_ref: env:VS_PG_PASSWORD
    database_ref: env:VS_PG_DATABASE # postgres
    publication_ref: env:VS_PG_PUBLICATION
    slot_ref: env:VS_PG_SLOT
    bootstrap:
      mode: snapshot
    tls:
      mode: verify_full
```

Supabase signs its database certificates with its own CA ("Supabase Root
2021 CA"), which no system trust store carries. The engine packages that
root (SHA-256 pinned, valid through April 2031) and applies it
automatically for `*.supabase.co` hosts, so `verify_full` works with no
certificate download. To be explicit — or for a custom domain in front of
Supabase — set `tls.trust.provider: supabase`, or point `tls.ca_file` at
your own downloaded copy; an operator-supplied `ca_file` always wins.

From here, everything in the [Postgres source](/docs/connectors/sources/postgres)
guide applies unchanged — flat sync, joins specs, replica identity choices,
and schema-drift handling.

## Platform behaviors to know

**Upgrades and pauses drop replication slots.** Supabase removes logical
slots on Postgres engine upgrades, and free-tier projects lose them when
paused. VentStream detects the missing slot immediately, reports exactly
what happened, and recovers on the next start: the slot is recreated and —
with `bootstrap` configured — the data re-snapshots so the target converges
again without manual surgery, including rows written while the slot was
gone. Expect one re-bootstrap after an upgrade, not silent data loss.

**Drop the slot when you decommission a pipeline.** An abandoned slot pins
WAL and can stall autovacuum on your project. When you retire a pipeline
for good:

```sql theme={"dark"}
SELECT pg_drop_replication_slot('<your slot name>');
```

**Coexistence with Supabase Realtime.** Realtime uses its own replication
slot; VentStream's slot is independent and they run side by side. Both
count toward the project's `max_replication_slots`.