Version status and a production CDC recovery plan
This article describes the Debezium 3.0 series. The final 3.0 release was 3.0.8.Final on March 3, 2025, and the Debezium site now labels 3.0 documentation as outdated. As of August 1, 2026, the official releases page lists 3.6 as the latest stable series and 3.7 as development. Keep versioned 3.0 documentation beside a legacy deployment, but use the current stable documentation and every intervening release note when planning an upgrade.
Debezium Server was already a deployment option in 3.0; it was not a new guarantee of Kafka-free durability or exactly-once delivery. The 3.0 Server documentation describes one source connector per Server process and supports non-Kafka sinks, but the operator must provide durable offset storage and, for connectors such as MySQL, durable schema history. A file offset store on an ephemeral container filesystem is a restart hazard. Mount it on durable storage, back it up consistently with configuration, and prove that a replacement instance can resume from it.
Offsets are necessary, but source-log retention decides recovery
An offset records where the connector last committed progress; it does not preserve the missing database log. PostgreSQL must retain the required WAL behind its logical replication slot, MySQL must retain the required binlog and matching schema history, and MongoDB must retain the oplog position represented by the resume token. If any source overwrites the required position while the connector is stopped, a saved offset alone cannot resume the stream.
- PostgreSQL: monitor the slot's active state and the byte difference between the current WAL LSN and
confirmed_flush_lsn. Heartbeat records help a low-traffic captured database advance its confirmed LSN. A cap such asmax_slot_wal_keep_sizeprotects disk capacity, but if required WAL is removed the slot can become unusable and recovery may require a new snapshot. - MySQL: keep the connector's server ID unique, retain binlogs longer than the maximum credible outage, and protect both offsets and the internal schema-history topic. Rebuilding schema history from the current schema is unsafe when historical binlog events use older table shapes.
- MongoDB: size or time-bound oplog retention for peak write volume and maximum connector downtime. If the recorded resume token has aged out, the connector can fail to resume and may need recreation or an explicitly planned offset reset and snapshot.
The versioned Debezium 3.0 PostgreSQL connector guide, MySQL connector guide, and MongoDB connector guide document the relevant failure modes. Preserve these links for a 3.0 incident because property names and defaults can change in newer series.
Design consumers for re-delivery
Do not interpret the 3.0 label or a Server deployment as end-to-end exactly once. Debezium's current exactly-once delivery documentation states that at-least-once is the baseline and that Debezium has no internal deduplication layer. Kafka Connect can provide source-side exactly-once participation for supported connectors when the workers and connector are configured correctly, but that does not make an arbitrary HTTP, Redis, Kinesis, or downstream database side effect exactly once. Consumers should use stable event identity or source coordinates, idempotent upserts, and transaction-aware processing. Test duplicates around connector crashes, worker rebalances, sink timeouts, and the boundary between writing an event and flushing its offset.
Restart and upgrade validation
- Record connector configuration, exact Debezium and Java versions, offset-store location, schema-history location, source slot or server identity, and source-log retention before changing anything.
- In staging, restore those state stores, start from a copied source position, and verify that the first resumed event neither skips a committed source change nor silently changes its schema.
- Exercise a graceful stop, hard process kill, network partition, source failover, and sink timeout. Reconcile source transaction counts with unique consumed event identities rather than message count alone.
- For upgrades, read the 3.0 release notes and each later series' migration notes. Compare event schemas, topic names, snapshot modes, Java requirements, connector database support, and renamed or removed properties.
- Roll back by restoring the complete compatible bundle: binary, configuration, offsets, and schema history. Never point two connector instances with the same logical identity at the source concurrently unless the documented topology supports it.
The Debezium schema-change and restart guide expands the validation sequence for DDL-heavy systems.