Debezium Snapshot Modes Explained — initial, always, no_data, recovery and more

initial default

Snapshot on first start, then stream

The connector performs a full snapshot the first time it starts (no offsets exist). After the snapshot completes, the connector streams subsequent changes from the transaction log. On later restarts, if offsets exist, the snapshot is skipped and streaming resumes from the saved position.

Snapshot phase	reads all data as READ events
Streaming phase	streams WAL/binlog changes

Use case: Default production mode. Use when you need a complete initial copy of the data before streaming live changes.

Supported: PostgreSQL MySQL SQL Server MongoDB MariaDB

Reviewed 2026-10-27 · v3.7.0.Final · Debezium docs ↗

initial_only

Snapshot then stop — no streaming

The connector performs a full snapshot exactly like the initial mode, but after the snapshot completes, the connector stops. It does not stream subsequent changes from the transaction log.

Snapshot phase	reads all data as READ events
Streaming phase	connector stops after snapshot

Use case: One-time bulk data loads, data migration, or initial seeding where you do not need continuous streaming.

Supported: PostgreSQL MySQL SQL Server MongoDB MariaDB

Reviewed 2026-10-27 · v3.7.0.Final · Debezium docs ↗

always

Full snapshot every restart

The connector performs a complete snapshot every time it starts, regardless of whether offsets exist. After each snapshot, it streams subsequent changes. This re-emits READ events for all existing rows on each restart.

Snapshot phase	full snapshot on EVERY start
Streaming phase	streams WAL/binlog changes after

Use case: Scenarios where downstream consumers must always start from a complete state — for example, rebuilding a search index or a cache from scratch.

⚠ Risk: Produces duplicate events downstream on every connector restart. Consumers must be idempotent.

Supported: PostgreSQL MySQL SQL Server MongoDB MariaDB

Reviewed 2026-10-27 · v3.7.0.Final · Debezium docs ↗

no_data

Schema only — no data READ events

Skips READ events for existing rows. Relational connectors may capture schema; PostgreSQL resumes from stored LSNs or, without them, the slot creation position. It is not a repair for a missing change history.

Snapshot phase	captures schema/DDL only, no row data
Streaming phase	streams WAL/binlog changes

Use case: When existing data is already in the target (e.g., migrated separately) and only the stream of future changes is needed. Also useful for large tables where a full snapshot is impractical.

⚠ Risk: Using no_data after losing offsets can skip required state or replay changes; reconcile the snapshot/log position with downstream state.

Mode naming and offset behavior depend on the connector and version; the availability matrix here is pinned to 3.7.

Supported: PostgreSQL MySQL SQL Server MongoDB MariaDB

Reviewed 2026-10-27 · v3.7.0.Final · Debezium docs ↗

never (legacy)

Legacy name; not a Debezium 3.7 mode

The pinned 3.7 connector enums do not accept never. This entry preserves historical links; use the documented mode for your connector version.

Snapshot phase	legacy entry
Streaming phase	version-dependent

Use case: Historical reference only. Do not copy this value into a Debezium 3.7 connector.

⚠ Risk: Do not assume that skipping a snapshot starts at the current time or preserves a missing interval of changes.

Use the connector-specific no_data documentation; saved offsets and log/slot availability determine the start position.

Supported:

Reviewed 2026-10-27 · v3.7.0.Final · Debezium docs ↗

when_needed

Snapshot only if offsets are missing or stale

The connector performs a snapshot only if it cannot detect any stored offsets, or if the stored offset refers to a log position that is no longer available on the server (e.g., the WAL segment or binlog file has been purged).

Snapshot phase	conditional — only if offsets absent or invalid
Streaming phase	streams WAL/binlog changes

Use case: Safety net for connectors that may experience long downtime — ensures a fresh snapshot if the binlog/WAL position has been purged before the connector reconnects.

⚠ Risk: A replacement snapshot represents current rows; it cannot reconstruct every intermediate event or deleted row from a lost log interval. Reconcile downstream state.

Supported: PostgreSQL MySQL SQL Server MongoDB MariaDB

Reviewed 2026-10-27 · v3.7.0.Final · Debezium docs ↗

recovery

Rebuild lost schema history topic

Restores a lost or corrupted internal schema history topic by re-reading the DDL directly from the live database tables. The connector rebuilds the schema history and then resumes streaming from the last known offset.

Snapshot phase	rebuilds schema history from live DB
Streaming phase	resumes from last offset

Use case: Emergency recovery when the internal schema history Kafka topic is deleted or corrupted. Do not use for routine snapshots — this mode assumes the data offsets are still valid.

⚠ Risk: Do not use if DDL changes were committed to the database after the last connector shutdown. The rebuilt schema won't match the historical DDL needed to decode old events.

Only available for MySQL, MariaDB, and SQL Server (connectors that use a schema history topic). Not available for PostgreSQL or MongoDB.

Supported: MySQL SQL Server MariaDB

Reviewed 2026-10-27 · v3.7.0.Final · Debezium docs ↗

configuration_based

Fine-grained control via properties

Controls snapshot behavior through specific connector properties prefixed with snapshot.mode.configuration.based.*. Allows separately configuring whether to snapshot data, schema, and what to do on subsequent restarts.

Snapshot phase	determined by configuration properties
Streaming phase	determined by configuration properties

Use case: Advanced use cases requiring fine-grained control over snapshotting logic — for example, snapshot schema on first start but skip data, or snapshot on every restart but only schema.

Supported: PostgreSQL MySQL SQL Server MongoDB MariaDB

Reviewed 2026-10-27 · v3.7.0.Final · Debezium docs ↗

custom

Inject a custom Snapshotter implementation

Loads a user-provided class that implements the io.debezium.spi.snapshot.Snapshotter SPI. The class name must be set via snapshot.mode.custom.name. This mode provides complete control over snapshot decisions.

Snapshot phase	determined by custom class
Streaming phase	determined by custom class

Use case: Proprietary snapshot logic: snapshots triggered by an external signal, partial table snapshots with custom filtering, or integration with an external state store.

⚠ Risk: Custom implementation errors will fail the connector. Thoroughly test before production use.

Supported: PostgreSQL MySQL SQL Server MongoDB MariaDB

Reviewed 2026-10-27 · v3.7.0.Final · Debezium docs ↗

when_needed_no_data

Conditional schema snapshot without READ events

SQL Server combines the when_needed decision with no_data snapshot behavior. It does not emit existing rows as READ events.

Snapshot phase	conditional schema snapshot; no READ events
Streaming phase	resumes according to connector offsets

Use case: SQL Server deployments that deliberately bootstrap schema without loading existing row data.

⚠ Risk: Does not recover missing historical changes or seed existing rows downstream.

Supported: SQL Server

Reviewed 2026-10-27 · v3.7.0.Final · Debezium docs ↗