Skip to content

CONCEPT Cited by 1 source

offset.mismatch.strategy (Debezium)

Definition

offset.mismatch.strategy is a Debezium Postgres connector configuration property introduced in Debezium 3.4.0.Final (2025-12-16) that controls what the connector does on startup when the stored offset LSN differs from the Postgres replication slot's confirmed_flush_lsn. Zalando contributed it as DBZ-9688 / PR #6948, "taking inspiration from Kafka's auto.offset.reset configuration, which allows consumers to opt-in to trusting the broker's position when their local state is invalid."

The property is a four-value enum that replaces and deprecates the older boolean internal.slot.seek.to.known.offset.on.start:

Value Offset behind slot Offset ahead of slot Posture
no_validation (default) Stream anyway (may fail with cryptic WAL error) Stream anyway Backward-compatible default
trust_offset Fail — potential data loss detected Advance slot to offset via pg_replication_slot_advance() Strict safety; offset is truth
trust_slot Advance offset to slot — skip replay of events in gap — Slot is authoritative
trust_greater_lsn Advance offset to slot Advance slot to offset Bidirectional sync — take the max

The problem it addresses

Logical-replication position is tracked in two independent locations — Debezium's offset store and the Postgres replication slot's confirmed_flush_lsn. See slot-vs-offset position tracking for the full structural mismatch.

Pre-3.4 Debezium had only two startup behaviours:

  1. Default — attempt to stream from stored offset without validating slot state. If the requested LSN is no longer in WAL, Postgres returns a cryptic error.
  2. Strict (internal.slot.seek.to.known.offset.on.start=true) — immediately fail with "Saved offset is before replication slot's confirmed lsn" to detect slot recreation scenarios.

Neither handled the connector_and_driver keepalive-flush scenario well. The default failed with a cryptic WAL error when trying to stream from an LSN that had been cleaned up; the strict validation "would immediately fail even though no actual data had been lost" — forcing full database resyncs that were operationally untenable.

Strategy semantics

no_validation (default)

Matches pre-3.4 behaviour. The connector attempts to stream from the stored offset without validating the slot state. If the slot is ahead of the offset and the requested LSN is no longer available in the WAL, Postgres returns an error. Chosen as the default for backward compatibility.

trust_offset

Replaces internal.slot.seek.to.known.offset.on.start=true. Validates that the stored offset is not behind the slot; fails with an error if it is — interpreted as potential data loss. If the offset is ahead of or equal to the slot, the connector advances the slot to the offset position using pg_replication_slot_advance() when possible. The right posture when you want to detect and alert on unexpected slot state changes that could indicate data loss.

trust_slot

The connector treats the Postgres replication slot as the authoritative source of truth. If the stored offset is behind the slot, advance the offset to match the slot — skipping replay of events between the two positions. The right posture when paired with lsn.flush.mode=connector_and_driver: the driver's keepalive flush has intentionally advanced the slot past WAL the connector didn't need to see.

trust_greater_lsn

Bidirectional synchronisation — advance whichever position is behind. If offset < slot: advance offset (skip events). If offset > slot: advance slot via pg_replication_slot_advance(). Provides self-healing recovery on any startup mismatch. The recommended pairing with lsn.flush.mode=connector_and_driver when using persistent offset stores.

Recovery use case: manual slot advance past corrupted WAL

trust_slot and trust_greater_lsn also serve as the operator-initiated-recovery lever. When an operator must advance a slot past corrupted WAL using pg_replication_slot_advance(), the connector can be configured to respect that change instead of refusing to start — converting an otherwise-unrecoverable situation (full resnapshot of potentially billions of rows) into a targeted slot-advance.

Backward compatibility

The deprecated internal.slot.seek.to.known.offset.on.start boolean auto-maps to the new enum: - false → no_validation - true → trust_offset

Canonical instance of boolean → enum deprecation mapping.

Relationship to auto.offset.reset

The design consciously echoes Kafka consumer semantics: auto.offset.reset lets Kafka consumers opt-in to trusting the broker's position when their local state is invalid. offset.mismatch.strategy lets Debezium users opt-in to trusting the Postgres replication slot's position when their local offset store is behind or ahead of the slot for structurally-legitimate reasons.

Seen in

Last updated · 428 distilled / 1,221 read