CDC Guarantees

This page defines the public CDC contract. Use it together with CDC Overview, CDC Sources, and CDC Destinations.

Two CDC outcomes

Contract	What you get	When it applies
Exactly-once final state	Replays, retries, and restarts converge on the correct final row state in the destination	Source and destination both support final-state reconciliation
CDC-encoded	Mutation events land with CDC metadata so downstream consumers can reconcile them	Destination can land CDC faithfully but cannot maintain final-state reconciliation itself

Term	Meaning
Business key	The columns that uniquely identify a logical row for reconciliation
Event identity	The token that says two source events are the same event
Order token	The token used to decide which mutation is newer
Tombstone	A delete record stored alongside the table so older inserts cannot resurrect deleted rows

A committed change batch can be replayed safely.
An older mutation cannot overwrite a newer row because order tokens are compared during apply.
A replayed or out-of-order insert cannot resurrect a deleted row if the tombstone is newer.
Restart resumes from committed ownership of source events, not from an advisory hint alone.
business_key_columns is required because reconciliation is defined per logical row, not per file or batch.

It does not mean the pipeline never retries internally.
It does not mean every destination supports final-state reconciliation.
It does not choose business keys for you.
It does not guarantee correctness if source retention expires before the runner resumes.

For final-state reconciliation to work, the source must provide order tokens that are meaningfully comparable:

If a destination cannot use that ordering model, Skippr falls back to CDC-encoded instead of claiming a stronger guarantee than it can enforce.