Supabase PostgreSQL Guide

Use this page when your PostgreSQL source or target is hosted in Supabase.

This guide focuses on the Supabase-specific parts of the setup:

• choosing the correct Supabase connection method
• importing the PostgreSQL URI into DBConvert Streams
• SSL/TLS expectations
• CDC preparation when Supabase is used as a PostgreSQL CDC source

For the core PostgreSQL workflow, use:

• PostgreSQL Server Configuration
• PostgreSQL CDC Source Configuration

Base setup

1. Open the Supabase Dashboard.
2. Select the project that DBConvert Streams should use.
3. Click Connect in the Supabase project header.
4. Select Direct connection if the DBConvert Streams deployment can use IPv6. Select Session pooler if the deployment needs IPv4 access.

5. Copy the connection URI and replace [YOUR-PASSWORD] with the database password.

Typical direct connection pattern:

postgresql://postgres:[YOUR-PASSWORD]@db.<project-ref>.supabase.co:5432/postgres

Typical session pooler pattern:

postgresql://postgres.<project-ref>:[YOUR-PASSWORD]@<region>.pooler.supabase.com:5432/postgres

Connection method

Use the connection method that matches the network path from your DBConvert Streams deployment:

Supabase direct database hostnames are IPv6-oriented by default. If your host or container network cannot reach IPv6 addresses, use the Session pooler URI from the Supabase Connect panel — unless you are setting up CDC, in which case see below.

Add the connection in DBConvert Streams

1. Open Data Explorer.
2. Click New connection.
3. Select PostgreSQL.

4. Paste the Supabase URI into Connection String.
5. Confirm that DBConvert Streams fills in the host, port, username, password, and database fields.

6. Set SSL/TLS to require unless your environment has a stricter certificate verification policy.
7. Click Test Connection.
8. Save the connection after the test succeeds.

SSL requirements

Treat SSL/TLS as required for Supabase connections.

Common DBConvert Streams settings:

• SSL mode: require
• Host: copied from the Supabase Direct connection or Session pooler URI
• Port: 5432
• Database: usually postgres, unless you created a separate database
• Username: postgres for Direct connection, or postgres.<project-ref> for Session pooler

Use SSL Configuration if your deployment requires certificate verification with a CA file.

CDC source preparation

If Supabase is only a Load source, Explorer connection, or target, the base PostgreSQL connection setup is enough.

If Supabase is the CDC source, the connection must use the Direct connection URI. A pooler endpoint does not carry the PostgreSQL replication protocol, so the stream fails before it reads anything — see below for what that looks like.

Before creating the CDC stream:

1. Confirm the Supabase plan and project settings allow the logical replication resources you need.
2. Use a database role with the privileges required by PostgreSQL CDC Source Configuration.
3. Verify the replication settings from SQL:

SELECT name, setting
FROM pg_settings
WHERE name IN (
  'wal_level',
  'max_replication_slots',
  'max_wal_senders'
);

4. Confirm wal_level is logical.
5. Complete the publication, slot, and stream setup in PostgreSQL CDC Source Configuration.

What a pooler endpoint looks like when it fails

Starting a CDC stream against a session pooler URI fails during preparation, with the replication protocol commands reported as SQL syntax errors:

failed to identify system:         ERROR: syntax error at or near "IDENTIFY_SYSTEM"         (SQLSTATE 42601)
failed to create replication slot: ERROR: syntax error at or near "CREATE_REPLICATION_SLOT" (SQLSTATE 42601)

Nothing is wrong with the commands. IDENTIFY_SYSTEM and CREATE_REPLICATION_SLOT belong to the PostgreSQL replication protocol and are only valid on a connection opened in replication mode. The pooler does not provide one, so it parses them as ordinary SQL and PostgreSQL answers 42601.

The database side can look perfectly healthy while this happens — wal_level is logical, slots are free, and ordinary queries work. Switch the connection to the Direct connection URI.

Note that the publication is created before this point, because CREATE PUBLICATION is ordinary DDL and passes through the pooler. A failed start can therefore leave dbconvert-publication behind on the source. It holds no WAL and is reused on the next start, but you can drop it with DROP PUBLICATION "dbconvert-publication"; if you are abandoning the setup.

Validation checklist

1. Test the Supabase connection from the Data Explorer sidebar or from the connection editor.
2. Open it in Data Explorer and confirm schemas and tables are visible.
3. If the connection fails from an IPv4-only environment, switch from Direct connection to the Supabase Session pooler URI.
4. If using CDC, run SHOW wal_level and confirm it returns logical.
5. If using CDC, confirm the connection uses the Direct connection URI. Neither pooler carries replication; a stream on a pooler endpoint fails with syntax error at or near "IDENTIFY_SYSTEM".

Related docs

• PostgreSQL Server Configuration
• PostgreSQL CDC Source Configuration
• SSL Configuration
• Supabase: Connect to your database