Replication Setup

Configure publications and destinations for replication.

Replication uses Postgres logical replication to stream changes from your database. Powered by Supabase ETL, an open source tool built for Postgres logical replication, it provides a managed interface through the Dashboard to configure and monitor replication pipelines.

Setup overview#

Replication requires two main components: a Postgres publication (defines what to replicate) and a destination (where data is sent). Follow these steps to set up your replication pipeline.

Step 1: Create a Postgres publication#

A Postgres publication defines which tables and change types will be replicated from your database. You create publications using SQL.

Creating a publication#

The following SQL examples assume you have users and orders tables in your database.

Publication for specific tables

1
2
3
-- Create publication for both tablescreate publication pub_users_ordersfor table users, orders;

This publication will track all changes (INSERT, UPDATE, DELETE, TRUNCATE) for both the users and orders tables.

Publication for all tables in a schema

1
2
-- Create a publication for all tables in the public schemacreate publication pub_all_public for tables in schema public;

This will track changes for all existing and future tables in the public schema.

Publication for all tables

1
2
-- Create a publication for all tablescreate publication pub_all_tables for all tables;

This will track changes for all tables in your database.

Advanced publication options#

Selecting specific columns

You can replicate only a subset of columns from a table:

1
2
3
-- Replicate only specific columns from the users tablecreate publication pub_users_subsetfor table users (id, email, created_at);

This will only replicate the id, email, and created_at columns from the users table.

Filtering rows with a predicate

You can filter which rows to replicate using a WHERE clause:

1
2
3
4
5
6
7
-- Only replicate active userscreate publication pub_active_usersfor table users where (status = 'active');-- Only replicate recent orderscreate publication pub_recent_ordersfor table orders where (created_at > '2024-01-01');

Viewing publications in the Dashboard#

After creating a publication via SQL, you can view it in the Supabase Dashboard:

1. Navigate to Database → Publications in your Supabase Dashboard
2. You'll see all your publications listed with their tables

Step 2: Enable replication#

Before adding destinations, you need to enable replication for your project:

1. Navigate to the Database section in your Supabase Dashboard
2. Select the replication tab
3. Click Enable replication to activate replication for your project

Step 3: Add a destination#

Once replication is enabled and you have a Postgres publication, you can add a destination. The destination is where your replicated data will be stored, while the pipeline is the active Postgres replication process that continuously streams changes from your database to that destination.

Choose and configure your destination#

Follow these steps to configure your destination. The specific configuration depends on which destination type you choose. Both Analytics Buckets and BigQuery destinations are supported, though availability varies based on the planned roll-out strategy.

Step 4: Monitor your pipeline#

After creating a destination, the replication pipeline will start and appear in the destinations list. You can monitor the pipeline's status and performance from the Dashboard.

For comprehensive monitoring instructions including pipeline states, metrics, and logs, see the Replication Monitoring guide.

Managing your pipeline#

You can manage your pipeline from the destinations list using the actions menu.

Available actions:

• Start: Begin replication for a stopped pipeline
• Stop: Pause replication (changes will queue up in the WAL)
• Restart: Stop and start the pipeline (required after publication changes)
• Edit destination: Modify destination settings like credentials or advanced options
• Delete: Remove the destination and permanently stop replication

Adding or removing tables#

If you need to modify which tables are replicated after your replication pipeline is already running, follow these steps:

Adding tables to replication#

1. Add the table to your publication using SQL:

   1
   2
   3
   4
   5
   -- Add a single table to an existing publicationalter publication pub_users_orders add table products;-- Or add multiple tables at oncealter publication pub_users_orders add table products, categories;

2. Restart the replication pipeline using the actions menu (see Managing your pipeline) for the changes to take effect.

Removing tables from replication#

1. Remove the table from your Postgres publication using SQL:

   1
   2
   3
   4
   5
   -- Remove a single table from a publicationalter publication pub_users_orders drop table orders;-- Or remove multiple tables at oncealter publication pub_users_orders drop table orders, products;

2. Restart the replication pipeline using the actions menu (see Managing your pipeline) for the changes to take effect.

How it works#

Once configured, replication:

1. Captures changes from your Postgres database using Postgres publications and logical replication
2. Streams the changes through the replication pipeline
3. Loads the data to your destination in near real-time batches

Changes are sent in batches to optimize performance and reduce costs. The batch size and timing can be adjusted using the advanced settings. The replication pipeline currently performs data extraction and loading only, without transformation - your data is replicated as-is to the destination.

Troubleshooting#

If you encounter issues during setup:

• Publication not appearing: Ensure you created the Postgres publication via SQL and refresh the dashboard
• Tables not showing in publication: Verify your tables have primary keys (required for Postgres logical replication)
• Pipeline failed to start: Check the error message in the status view for specific details
• No data being replicated: Verify your Postgres publication includes the correct tables and event types

For more troubleshooting help, see the Replication FAQ.

Limitations#

Replication has the following limitations:

• Primary keys required: Tables must have primary keys (Postgres logical replication requirement)
• Custom data types: Not supported
• Schema changes: Not automatically handled
• No data transformation: Data is replicated as-is without transformation
• Data duplicates: Duplicates can occur when stopping a pipeline if your database has transactions that take longer than a few minutes to complete. See Can data duplicates occur? for details

Destination-specific limitations (such as Iceberg's append-only log format or BigQuery's row size limits) are detailed in each destination tab in Step 3 above.

Future work#

Replication is actively being developed. Planned improvements include:

• DDL support: Automatic handling of Postgres schema changes (ALTER TABLE, ADD COLUMN, etc.)
• Additional destinations: Support for more data warehouses and analytics platforms

There are no public timelines for these features, but they represent the roadmap for making replication more robust and flexible.

Next steps#

• Monitor Replication
• View Replication FAQ