In Debezium, how do the snapshot.mode values initial and initial_only differ?

## What snapshot.mode controls A Debezium connector has two possible phases: a **snapshot** phase, in which it reads existing rows out of the source tables with ordinary SELECT queries, and a **streaming** phase, in which it reads the database's transaction log (the MySQL binlog, the Postgres WAL through a replication slot, the SQL Server change tables, and so on). The `snapshot.mode` property decides which of those phases run and when. It is a **start-up decision**, evaluated when the connector task begins — not something that changes behaviour while the connector is running. Snapshot rows are emitted as change events like any other, but with the operation field `op` set to `r` for *read*, distinguishing them from `c` (create), `u` (update) and `d` (delete). The `source` block of those events also carries a `snapshot` marker so a consumer can tell a backfilled row from a live change. ## initial With `snapshot.mode=initial`, the connector, on a first start with no recorded offsets, snapshots every table in its capture set and then transitions to streaming from the log position it recorded at snapshot time. This is the default on most connectors and the mode almost every production pipeline runs: the destination ends up with a complete copy of the table plus every subsequent change. ## initial_only `initial_only` runs the identical snapshot and then **stops**. The connector task completes and does not open the log reader. Nothing further is emitted, no matter how much the source changes afterwards. It exists for one-shot copies: seeding a new warehouse table, exporting a dataset in Debezium's event format for a migration, or producing a reference copy that some other process will keep current. ## Offsets decide, not the config The most common misunderstanding is that `initial` means "snapshot on every start". It does not. Kafka Connect persists a source connector's offsets, and Debezium's source partition is keyed by the connector's `topic.prefix` (the logical name for the server). If offsets exist for that key, the connector skips straight to streaming from the stored position. Consequences that follow directly from this: - Restarting, rebalancing, or bouncing a worker does not re-copy your tables. - Deleting and recreating the connector with the **same name and the same `topic.prefix`** finds the old offsets and still skips the snapshot. - Changing `snapshot.mode` on a connector that already has offsets changes nothing; to force a fresh snapshot you must remove the stored offsets or use a mode that snapshots unconditionally. ## Where the other modes fit Once you understand the two above, the rest of the family reads easily. `always` snapshots on **every** start regardless of offsets — useful in tests, hazardous on large tables. `never` skips the snapshot entirely and goes straight to the log, so pre-existing rows are never emitted. `schema_only` (renamed `no_data` in recent releases) reads the table definitions but not the rows. `when_needed` snapshots whenever the connector decides it must — no offsets, or a stored log position that the server has already purged. `schema_only_recovery` (renamed `recovery`) rebuilds a lost schema history topic without re-reading data. ## Choosing between them Pick `initial` for any pipeline that must stay current — that is nearly all of them. Pick `initial_only` when the destination genuinely wants a point-in-time copy and nothing more, or when you deliberately want to run the copy under supervision and then start a *separate* streaming connector with a mode that skips the snapshot. Bear in mind the operational cost of the snapshot phase in either case: while it runs, the connector is not consuming the log, so the source keeps retaining log segments the connector has not yet read. ## Common mistakes Teams frequently set `initial_only`, see the connector go into a completed state, and file a bug that Debezium "stopped working" — it did exactly what was asked. The mirror-image mistake is expecting `initial` to re-copy a table after someone truncated the destination; it will not, because the offsets are still there. And an interrupted snapshot is worth planning for: on most connectors a classic snapshot that dies part-way begins again from the start on the next attempt (some newer connector versions can resume — check the one you run), so the partially emitted `r` events are re-sent. A sink that upserts on the primary key absorbs that harmlessly; an append-only sink does not.