CDC Reliability and Resume

CDC mode keeps supported MySQL and PostgreSQL sources synchronized by reading committed row changes from the source log and applying them to the target.

This page explains what happens in the common rollout cases: starting from an empty target, copying existing rows before CDC, combining Load with CDC, stopping a stream, and starting it again later.

Starting CDC on an empty or prepared target

Use this flow when the target table is empty, already prepared, or intentionally starts from the current source position.

Create a CDC stream for the source and target table.
Start the stream.
Insert, update, or delete rows on the source.
DBConvert Streams reads committed changes from MySQL binlog or PostgreSQL WAL.
Target writers apply the changes.
The stream checkpoint advances after the target write succeeds.

CDC captures changes made after the stream's start position. It does not automatically copy older rows that already existed in the source table.

Existing source data

If the source table already contains data, choose one of these rollout paths.

Built-in Initial Load + CDC

Use Initial Load + CDC when the target tables are empty and you want one CDC run to copy existing rows before it continues from the matching source log position.

Use Load mode first when the initial load is a separate migration task, the target already contains managed data, or you need Load-only features such as custom SQL, multi-source input, files, or S3 sources.

After Load finishes, validate the target and start CDC from the point you choose for the cutover.

Stop and start again later

When you stop a CDC stream, DBConvert Streams keeps the CDC checkpoint for that stream config. If you start the same config later, it resumes from the saved position:

MySQL resumes from the saved binlog file and position.
PostgreSQL resumes from the saved LSN, with the replication slot also helping retain source-side state.

This means changes made while the stream was stopped can be applied after the next start, as long as the source database retained the required log range.

If the stream used Initial Load + CDC and the bootstrap phase already completed, the next start resumes normal CDC. It does not copy the initial snapshot again.

What must be retained

To resume safely after a stop or service restart:

Keep the stream config. Deleting the config also deletes its CDC checkpoint and (since v2.4.2) drops its PostgreSQL replication slot.
Keep the embedded NATS JetStream KV storage (the streams bucket) intact. Deleting it removes all checkpoints.
For MySQL, keep binary logs long enough for the downtime window.
For PostgreSQL, keep logical replication enabled and retain the replication slot/WAL needed by the stream.
Keep the target schema compatible with source changes produced during the stopped period.

PostgreSQL slot WAL retention and disk growth

The replication slot is what lets a stopped stream resume without losing changes — but it works by making PostgreSQL retain WAL from the saved position onward. While the stream is stopped, retained WAL keeps growing. A slot that is never resumed (for example, a stream you stopped and forgot) can eventually fill the source disk.

Two protections:

Delete configs you no longer need. Since v2.4.2, deleting a CDC stream config also drops its inactive replication slot on the source, so nothing is left behind to retain WAL.
Set a retention cap on the source (PostgreSQL 13+):
```
ALTER SYSTEM SET max_slot_wal_keep_size = '10GB';
SELECT pg_reload_conf();
```
If a slot exceeds the cap, PostgreSQL invalidates it instead of filling the disk. The trade-off: an invalidated slot cannot resume — the stream needs a reset and a fresh start. The default (-1, unlimited) favors resumability over disk safety; pick a cap that covers your longest expected downtime window.

Transaction behavior

CDC publishes committed row changes. Rolled back transactions are not applied to the target.

For database targets, messages are acknowledged only after the target write succeeds. If the target write fails because of a deterministic problem such as a schema mismatch or constraint error, the stream fails instead of retrying the same write in a loop. Fix the target-side cause, then start the stream again to continue from the last durable checkpoint.

Ordering

CDC preserves event order per table. Multiple target workers can process different tables in parallel, but events for the same table are routed through an ordered path.

The guarantee is per-table ordering, not a single global order across every table in the stream.

Monitor visibility

The Monitor tab shows CDC reliability status for active CDC streams:

source engine (MySQL or PostgreSQL)
current checkpoint position
last checkpoint update time
acknowledged stream sequence
health badge

Reset to start from scratch

When you need to rerun a CDC stream from the very beginning — clearing partial target data and all saved checkpoints — use the reset endpoint:

curl -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "X-Confirm-Reset: true" \
  "$HOST/api/v1/stream-configs/$CONFIG_ID/reset"

Reset performs the following in order:

Truncates target rows for CDC streams that used Initial Load + CDC. Plain CDC streams (no initial snapshot) are not affected.
Drops the inactive PostgreSQL replication slot for Initial Load + CDC streams on a PostgreSQL source. Fails if the slot is still active — stop the stream first.
Clears all durable recovery state: CDC checkpoint, CDC bootstrap state, and any resumable load-progress cursors.

After reset, the next start runs as a clean first run. For plain CDC without initial snapshot, reset is not needed after a normal stop — just start again and it resumes from the saved checkpoint.

Not covered by the current release

The current CDC reliability work does not include:

exactly-once delivery
automatic source schema evolution after stream start
automatic repair of target constraint or schema errors
automatic recovery from an interrupted plain-path initial snapshot (MySQL chunked bootstrap tables do resume — see Resumable Load; PostgreSQL bootstrap and MySQL plain-path tables require reset)

For schema changes, apply and validate target schema changes as part of your own operational procedure.