A new change data capture pipeline has two truths to combine: rows that already exist and transactions that continue while those rows are copied. The CDC initial snapshot establishes a consistent baseline; log streaming carries changes after a recorded database position. A correct bootstrap must ensure every committed source change is represented in the destination, even though retries can deliver an event more than once. The hard part is the boundary between snapshot and stream, not the speed of reading a table.
Connectors such as Debezium implement database-specific snapshot procedures because PostgreSQL logical decoding positions, MySQL binlog coordinates, locks, transactions, and schema handling differ. Teams should use those supported procedures instead of inventing a timestamp filter. They still own the surrounding system: source retention, connector offsets, Kafka durability, destination idempotency, validation, restart decisions, and operational evidence. No connector can provide end-to-end exactly-once outcomes across an arbitrary sink with side effects.
Define the bootstrap correctness contract
State what complete means before starting. Define included databases, schemas, tables, columns, row filters, and transaction boundary. Specify how inserts, updates, deletes, primary-key changes, schema changes, and tables without stable keys will appear. Decide whether the sink is a current-state replica, an append-only history, or both. The same duplicate event is harmless in an idempotent upsert table and damaging in a billing side effect, so delivery claims must be tied to the destination operation.
Set recovery objectives and evidence. Record connector configuration, source identity, publication or replication objects, snapshot mode, start time, captured position, topic naming, serialization settings, and sink version. Define acceptable source impact and maximum bootstrap duration. Ensure source logs remain available longer than the worst snapshot plus outage and recovery window; otherwise the connector can finish copying only to discover that the required log position has been recycled.
| Boundary | Required evidence | Typical failure | Control |
|---|---|---|---|
| Source scope | Exact captured tables and filters | Silent omission | Inventory and permission preflight |
| Snapshot | Consistent view and start position | Mixed-time baseline | Connector-supported snapshot |
| Transport | Durable offsets and topic retention | Unrecoverable replay gap | Capacity and retention margin |
| Sink | Stable key and idempotent operation | Duplicate side effect | Deduplication or upsert |
| Reconciliation | Counts, keys, aggregates, delete checks | Plausible but incomplete replica | Independent source controls |
Use the connector's consistent snapshot
A supported connector coordinates a database position with a consistent read. PostgreSQL and MySQL achieve that relationship differently, and connector options can trade locking, consistency, and availability. Read the documentation for the exact database and version, then test with representative write volume. Avoid home-grown pagination over a live table using updated_at: transactions can commit out of timestamp order, clocks can differ, rows can change between pages, and deletes leave no row to scan.
Prepare the source before the window. Verify replication privileges, logical replication or binlog settings, replica identity or key coverage, schema history requirements, connection limits, storage, and log retention. Estimate snapshot read I/O and transaction-log growth. Start with a small eligible table to validate permissions and event shape. Monitor source latency, lock waits, replication lag, log disk, connector queue, and broker throughput throughout the full snapshot.
Preserve the replication position through handoff
The connector records a source position associated with the snapshot and persists progress in its offset store. Snapshot records are emitted, followed by log events from the required position according to connector semantics. Treat the offset store as production state: give it durable replication, controlled access, backup where supported, and a stable connector identity. Changing connector name, topic prefix, server identifier, or offset namespace can make an existing pipeline look new and trigger unintended behavior.
Do not mark bootstrap complete when the last snapshot row is emitted. The stream must catch up to an agreed source position and the sink must apply all records through the corresponding transport offsets. Define a completion watermark using connector metrics, broker offsets, and sink progress. Keep live writes flowing during catch-up unless the business requires a cutover freeze. If another system switches to the replica, gate that decision on reconciliation and bounded lag.
| Phase | Source activity | Connector state | Exit evidence |
|---|---|---|---|
| Preflight | Normal writes | Configuration not started | Scope, permissions, retention approved |
| Position capture | Database-specific coordination | Start position established | Position and snapshot identity recorded |
| Snapshot read | Writes continue per mode | Baseline records emitted | All scoped tables completed |
| Catch-up | Normal writes | Log events consumed | Lag below threshold and sink advanced |
| Steady state | Normal writes | Offsets progress continuously | Reconciliation passes and monitoring active |
Design for duplicates without hiding data loss
Failures between producing an event and committing progress can cause replay. Kafka producer and transaction features improve guarantees within defined boundaries, but a sink that writes elsewhere needs its own idempotency design. Use a deterministic event identity derived from source partition and position, or apply current-state changes by stable primary key and source order. Preserve source metadata needed to reject older replays. Never deduplicate only by business payload; two legitimate transactions can have identical values.
Snapshot and streaming events may overlap in ways the connector expects, especially around retries and incremental snapshots. Consumers should understand operation types and source metadata rather than assuming arrival order alone establishes truth across partitions. For append-only history, store event identity with a uniqueness constraint. For side effects, write an inbox record and effect atomically where possible. A global exactly-once label is less useful than a precise statement of which write is idempotent and where duplicates can surface.
Make every restart decision explicit
On interruption, preserve connector offsets, schema history, topics, and source replication state. Determine whether the connector can resume, must restart a table snapshot, or requires a new full snapshot according to its mode and recorded state. Do not delete offsets as a routine troubleshooting step. That operation changes correctness semantics and can duplicate the entire baseline or skip required history if paired with other configuration changes.
Create a decision tree for expired logs, lost offsets, corrupted schema history, changed source identity, and partially populated sinks. Sometimes the safest recovery is a new sink namespace, full re-bootstrap, validation, and atomic consumer cutover. In-place truncation can expose an empty or mixed-time destination. Retain the failed run's evidence until root cause and reconciliation are complete.
Reconcile independently of the pipeline
Use source-generated control queries at known points: row counts by stable partition, minimum and maximum keys, sums or hashes over business columns, null and domain counts, and delete expectations. Compare current state after the stream reaches the same logical point. Large tables need stratified or partitioned checks rather than one expensive global hash. Reconciliation logic should not reuse the transformation whose defect it is meant to detect.
Investigate differences by class: missing key, unexpected key, stale version, duplicate event, transformed-value mismatch, or schema coercion. Sample rows are useful for diagnosis but cannot prove completeness. Keep a discrepancy ledger and rerun checks after repair. For regulated or financial data, obtain owner sign-off on both control design and tolerated differences before consumers switch.
Operate the bootstrap as a controlled change
Schedule with database owners and downstream teams. Freeze unrelated connector configuration, pre-size brokers and sinks, and define stop conditions for source impact, log exhaustion risk, or validation failure. Use a run identifier across connector logs, offset evidence, reconciliation, and approvals. Restrict who can reset offsets or alter source replication objects. Send snapshot progress and lag to dashboards that distinguish baseline copy from steady-state streaming.
After success, retain the bootstrap manifest and move monitoring to steady-state controls: last source event time, position progress, lag, queue utilization, schema-history health, rejected records, sink apply failures, and periodic reconciliation. Test restoration in a nonproduction path. CDC is durable only when operators can explain the current source position and recover before required logs disappear.
Capacity planning must cover the overlap period, when snapshot records, retained log changes, and ordinary consumers all use transport and sink resources. Forecast topic growth, connector queue pressure, sink write amplification, and the time needed to drain a worst-case backlog. Reserve enough margin that throttling protects the source without allowing replication logs to expire.
Key takeaways
- Use database-specific connector snapshot procedures, not timestamps over live tables.
- Retain source logs beyond snapshot, outage, and recovery duration.
- Treat offsets, schema history, and connector identity as durable production state.
- Design destination writes for replay and deduplicate with source-position identity.
- Declare completion only after catch-up, independent reconciliation, and consumer readiness.
Frequently asked questions
Does an initial snapshot lock the database?
The answer depends on database, connector, version, and snapshot mode. Some procedures use brief locks or consistent transactions to coordinate schema and position. Test the documented mode under representative load and monitor source impact.
Are duplicate CDC events a connector defect?
Not necessarily. Replay after failure is a normal possibility in at-least-once delivery boundaries. The sink must apply a stable key and source order or store a unique event identity so replay does not duplicate outcomes.
When can consumers use the new replica?
After all scoped snapshots finish, streaming catches up below the agreed lag, destination application succeeds through that point, reconciliation passes, and rollback is ready. Connector status alone is insufficient.
Conclusion
A reliable CDC bootstrap is a coordinated protocol across database consistency, replication position, durable transport, idempotent destination behavior, and independent reconciliation. Supported connectors solve the engine-specific handoff, while the platform team supplies retention, evidence, recovery, and cutover controls. Designing for replay and proving completeness turns the initial snapshot from a hopeful bulk copy into a recoverable production change.