Database replication

Replication keeps data synchronized with another location. Logical replication products such as Supabase Pipelines use change data capture (CDC) to read database changes and apply them to a destination.

Replication methods#

Supabase supports three replication methods. Choose based on whether you need another Supabase Postgres database, a managed replication pipeline to a destination system, or full control over your own logical replication setup.

Read replicas#

Read replicas are additional Supabase Postgres databases kept in sync with your primary database. Use them when you want read-only query capacity, lower latency in another region, or to isolate analytical reads from application writes while staying inside Supabase Postgres.

See Set up read replicas.

Pipelines#

Supabase Pipelines is a managed CDC product for moving data from Supabase Postgres to supported destination systems. It uses Postgres logical replication with the open-source Supabase ETL engine. A destination is where your replicated data is stored; a pipeline copies existing rows for the tables selected for initial sync, then uses ongoing replication (CDC) to send subsequent database changes to that destination.

See Set up Pipelines.

Manual replication#

Manual replication uses the same underlying Postgres logical replication features as Pipelines, but you configure and operate the pieces yourself. Use this path when you want to connect tools such as Airbyte, Estuary, Fivetran, Materialize, Stitch, AWS DMS, or another system that supports Postgres logical replication.

See Set up manual replication.

Supported destinations#

Request access to destinations in private alpha.

Use cases#

You might use database replication for:

• Analytics and data warehousing: Run analytical queries on replicated data in a separate platform. Initial sync and ongoing replication still use resources on the source database.
• Data integration: Keep your data synchronized across different systems and services in your tech stack.
• Operational reporting: Maintain a copy of selected application data that you can query in another system.

Related features#

For realtime features and syncing data to browsers and mobile apps, see Realtime.

Realtime also uses Postgres changes, but it is intended for broadcasting database updates to clients rather than maintaining a copy of your database in another system.

Concepts and terms#

Write-Ahead Log (WAL)#

Postgres records database changes in the Write-Ahead Log (WAL) before writing them to data files. WAL is stored in files called segments. A checkpoint writes modified data pages to disk so crash recovery can start from a recent position. Older WAL segments can be recycled or removed once they are no longer needed for recovery, archiving, or replication.

Logical replication and WAL#

Logical replication is a method of replication where Postgres uses WAL files to transmit changes to another Postgres database, or to a system that supports reading WAL files.

LSN#

LSN is a Log Sequence Number that identifies a position in the WAL. It is often used to determine the progress of replication in subscribers and calculate the lag of a replication slot.

Logical replication architecture#

Logical replication uses these components:

• Publication: Defines the source tables and change types to publish, with optional column lists and row filters.
• Replication slot: Tracks a consumer's progress and retains WAL it still needs. A slot uses an output plugin to decode changes; it is not tied to a single publication.
• Consumer: Reads decoded changes and applies them to a destination. Another Postgres database can use a subscription to manage this connection and its publications. Pipelines connects directly to the replication stream without creating a Postgres subscription.

Logical replication output format#

Logical replication is typically output in two forms, pgoutput and wal2json. The output method is how Postgres sends changes to any active replication slot.

Logical replication configuration#

Logical replication slots retain WAL until their consumers confirm that they no longer need it. If Postgres removes required WAL before a consumer catches up, the slot can become unusable and the consumer may need a new initial copy.

Postgres settings control replication capacity and WAL retention. Higher retention limits reduce the risk of losing required WAL, but can consume more database storage. Treat these settings as advanced configuration and check available disk before changing them. On Supabase, configure the supported settings with the Supabase CLI.