Resume MongoDB Change Streams Without Losing the Consumer Contract

A change-stream resume token identifies a position in MongoDB's change stream. It is not a complete exactly-once processing protocol for the application that consumes events. The consumer must still coordinate its side effect with the checkpoint it saves.

If it saves the token first and then crashes before applying the event, work can be skipped. If it applies the event first and crashes before checkpointing, work can be repeated. The solution depends on the destination's transactional and idempotency capabilities.

The concrete problem

Use a replica-set or sharded MongoDB deployment that supports change streams. This pseudocode illustrates the safer ordering for an idempotent destination. Resume tokens are opaque BSON values; preserve them with a compatible encoding rather than inventing a sortable timestamp.

Figure: Change event and opaque token → Idempotent destination apply → Durable checkpoint after apply.

A worked example

options = {}
if checkpoint is not None:
    options['resume_after'] = checkpoint
with collection.watch(**options) as stream:
    for event in stream:
        event_id = event['_id']  # opaque resume token
        apply_idempotently(event_id, event)
        save_checkpoint_durably(event_id)

Why the behavior matters

The destination deduplicates by a stable event identity or another correct business key. Applying before checkpointing permits replay after a crash, so the destination must make that replay harmless. If destination updates and checkpoint persistence can share a transaction, that can tighten the consumer contract within that destination system.

updateLookup can request a full document for update events, but it should not be described casually as the exact document image at the event's original instant. Later updates may affect the looked-up value. If exact before/after images are required, inspect version support, enablement and retention requirements explicitly.

Failure modes and design tradeoffs

A token may become unusable when the required history is no longer available or the stream is invalidated. resumeAfter and startAfter address different situations and are not interchangeable restart switches. Define a resnapshot/reconciliation procedure instead of silently starting “from now” after an error.

Monitor consumer delay relative to available history and record resume failures. A process that is running but permanently failing to apply one event is not healthy. Avoid logging complete event payloads if they contain sensitive production data.

What to verify before adoption

Crash the consumer after destination apply but before checkpoint, then verify replay does not duplicate the effect. Test deletion events, missing full documents and a deliberately invalid recovery position in an isolated setup. Record how operators reconcile state when resume is impossible. Do not claim exactly-once delivery from the presence of a resume token alone.

Primary reference

• MongoDB documentation. Verify the exact deployed version and driver behavior before using the example in a production runbook.