PostgreSQL CDC Source Configuration
Use this page when PostgreSQL is the source for a CDC workflow.
CDC mode reads changes from PostgreSQL WAL through logical replication. It is different from Load mode, which reads tables directly without WAL-based replication setup.
For the canonical setup flow, combine this page with:
When to use this page
Use this guide when you need:
- ongoing replication of inserts, updates, and deletes
- a PostgreSQL source that continues streaming changes after the initial load
- a CDC workflow instead of a bounded Load run
If you only need a one-time load or migration, use PostgreSQL Load Mode Guide instead.
Minimum source requirements
Before enabling CDC, confirm:
- the PostgreSQL connection already works in DBConvert Streams
- logical replication is enabled on the source
- replication capacity is sufficient for the environment
- the selected user has the required replication and read privileges
Required PostgreSQL settings
For a self-managed PostgreSQL source, the core settings typically include:
wal_level = logical
max_replication_slots = 5
max_wal_senders = 10
These values must fit your environment. The exact counts depend on how many replication consumers and slots the deployment uses.
Required privileges
The CDC user typically needs replication and login capability:
ALTER ROLE your_user WITH REPLICATION;
ALTER ROLE your_user WITH LOGIN;
It also needs read access to the tables the stream will capture.
Check CDC readiness
There are two places in the UI that surface CDC readiness:
- Database Overview in Data Explorer — open the database in the sidebar. The CDC readiness card shows the current
WAL_LEVEL, available replication slots, and WAL senders. Whenwal_levelis notlogical, a note appears: "PostgreSQL wal_level is not 'logical' — logical decoding (CDC) will be unavailable." - Stream wizard — when creating a new stream, the Data Transfer Mode step checks the source automatically. If
wal_levelisreplica, the Stream (Change Data Capture) option shows a warning ("PostgreSQL wal_level is 'replica' — must be 'logical' for CDC") and is disabled.
If both show CDC as ready, the source is configured. If not, apply the settings above and restart PostgreSQL.
Cloud-hosted PostgreSQL CDC sources
If the source is provider-managed, use the provider page for network and managed-service specifics, then return here for the DBConvert Streams CDC requirements:
- AWS Aurora PostgreSQL Guide
- Google Cloud SQL Connection Guide
- Azure Database Connection Guide
- Neon PostgreSQL Guide
- DigitalOcean Managed Database Guide
Validation checklist
- Test the PostgreSQL connection from the Data Explorer sidebar (right-click → Test connection) or from the connection editor.
- Open the database in Data Explorer and check the CDC readiness card — it should show logical with available replication slots and WAL senders.
- Confirm the CDC user has
REPLICATIONandLOGINroles andSELECTaccess to the target tables. - Start with a narrow CDC stream (one or two tables) before scaling to a larger scope.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Stream fails with WAL level error | wal_level is replica instead of logical | Set wal_level = logical in postgresql.conf and restart PostgreSQL |
| No replication slots available | max_replication_slots is too low or all slots are in use | Increase max_replication_slots and restart, or drop unused slots with SELECT pg_drop_replication_slot('slot_name') |
| Connection refused for replication | User lacks REPLICATION role | Run ALTER ROLE user WITH REPLICATION |
| Host access denied | pg_hba.conf does not allow the DBConvert Streams host | Add a replication entry for the deployment IP in pg_hba.conf and reload |
| Provider-managed settings not taking effect | Parameter change pending restart | Reboot the instance from the cloud console |