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

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

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

Debezium docs ↗

no_data

Schema only — no data READ events

The connector captures the structure (schema/DDL) of all relevant tables but does not emit READ events for existing rows. After the schema phase completes, it streams subsequent changes from the transaction log as normal.

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.

Formerly named schema_only (deprecated). Use no_data in Debezium 2.x+.

Supported: PostgreSQL MySQL SQL Server MongoDB MariaDB

Debezium docs ↗

never

Skip snapshot, stream from current position

The connector skips the snapshot entirely and begins streaming directly from the current log position (end of the WAL/binlog at startup). Existing rows are never emitted.

Snapshot phase	skipped
Streaming phase	streams from current log position at startup

Use case: When data already exists in the target system and you only care about changes from this point forward. Also useful for resuming after intentional offset reset.

⚠ Risk: Any writes between the connector starting and it attaching to the log are silently missed. On a busy database this window can span many events.

Under consideration for deprecation in favor of no_data. Only available for MySQL and MariaDB connectors.

Supported: MySQL MariaDB

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.

Supported: PostgreSQL MySQL SQL Server MongoDB MariaDB

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

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

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

Debezium docs ↗