Skip to main content

CDC Sink for PostgreSQL: Prerequisites Checklist

Source database requirements​

  • PostgreSQL version:
    10 or later.

  • WAL level:
    wal_level must be set to logical.

  • Replication slots:
    max_replication_slots must allow at least one slot for each CDC Sink task.

  • WAL senders:
    max_wal_senders must allow at least one active replication connection for each running CDC Sink task.

Verify the current settings with:

SHOW wal_level;
SHOW max_replication_slots;
SHOW max_wal_senders;

For instructions on changing wal_level, max_replication_slots, or max_wal_senders, see WAL Configuration.

User permissions​

The PostgreSQL user configured in the CDC Sink connection string must be able to use logical replication and read every table mapped by the CDC Sink task.

Minimum required permissions:

-- Required for logical replication
ALTER USER cdc_user REPLICATION;

-- Required for the initial load and for reading mapped tables
GRANT SELECT ON TABLE orders TO cdc_user;
GRANT SELECT ON TABLE order_lines TO cdc_user;

Permissions for automatic setup:

To let CDC Sink create the replication slot and create or update the publication automatically,
the PostgreSQL user also needs:

  • Create replication slots:
    the REPLICATION role attribute.

  • Create or update publications:
    Creating a publication requires CREATE on the database and ownership of the tables being published.
    Adding tables to an existing publication requires ownership of the publication and the tables being added.
    SUPERUSER satisfies these publication requirements.

See Permissions and Roles for the exact grants.

If the PostgreSQL user configured in the CDC Sink connection string does not have these permissions, a database administrator must set up the replication slot and publication manually before the task starts. See Initial Setup.

Table requirements​

  • Configured key columns:
    Each root table and embedded table must define PrimaryKeyColumns.
    These columns must exist in the source table and must also be included in the table's Columns mappings.

  • Embedded join columns:
    Each embedded table must define JoinColumns that match the direct parent table's PrimaryKeyColumns in count and order. These columns must exist in the embedded source table.

  • REPLICA IDENTITY for embedded deletes:
    For embedded tables where the join columns are not part of the primary key,
    the table must have REPLICA IDENTITY FULL or a replica identity index that covers both the join columns and the embedded table's PrimaryKeyColumns.

    Without this, DELETE events will not include enough old row values for CDC Sink to route the delete and identify the embedded item to remove. If deletes for that embedded table are ignored with OnDelete.IgnoreDeletes = true,
    no REPLICA IDENTITY change is required for delete routing. Learn more in REPLICA IDENTITY.

  • Mapped source columns:
    Every source column referenced by Columns, PrimaryKeyColumns, JoinColumns, or linked-table JoinColumns
    must exist in the SQL table.

Network access​

  • The RavenDB node that runs the CDC Sink task must be able to connect to the PostgreSQL host and port in the connection string (default port: 5432).

  • In a RavenDB cluster, every node that can become responsible for the task should have the same access,
    so the task can resume after failover.

  • PostgreSQL and the network path must allow connections from those RavenDB node addresses. Check PostgreSQL host-based authentication, firewall rules, routing, proxies, load balancers, and security groups as applicable.

  • The replication connection is long-lived.
    Ensure that firewalls, proxies, and load balancers do not terminate idle or long-lived connections.

Check prerequisites with Verify tables​

Once the source database is set up, use Verify tables in Studio, or the dry-run REST endpoint,
to check most of these prerequisites against the live database before you save the task, see Verify tables.

For PostgreSQL, verification runs the task's setup and initial-load steps once:

  • Publication
    If the publication does not exist, verification creates it and attempts to drop it when verification completes.
    If cleanup fails, verification reports a warning and the publication may remain.
    If it exists but does not include every configured table, verification reports a warning and does not change it.

  • Replication slot
    If the slot does not exist, verification creates a temporary slot, which PostgreSQL drops automatically.
    If it exists, verification checks that it uses the pgoutput plugin.
    It does not read from the slot or disconnect a task that uses it.

  • REPLICA IDENTITY
    If an embedded table needs REPLICA IDENTITY FULL, verification reports a warning and does not change the table.

  • Tables
    Verification reads at most one row from each configured table.

Creating the slot requires wal_level = logical, a free replication slot (max_replication_slots),
and the REPLICATION role attribute, so verification fails if any of them is missing.
For the permission-related messages, see Check permissions with Verify tables.

Verification does not check:

  • max_wal_senders and the replication connection, because verification does not stream changes.
  • The permissions needed to create the publication or the slot, when they already exist.

In this article