// Metadata created by nebel
//
:isImageReady: false

[id="how-the-mysql-connector-performs-database-snapshots_{context}"]
= How the MySQL connector performs database snapshots

When your {prodname} MySQL connector is first started, it performs an initial _consistent snapshot_ of your database. The following flow describes how this snapshot is completed.

NOTE: This is the default snapshot mode which is set as `initial` in the `snapshot.mode` property. For other snapshots modes, please check out the {link-prefix}:{link-mysql-connector}#mysql-connector-configuration-properties_{context}[MySQL connector configuration properties].

ifeval::["{isImageReady}" == "true"]
image:debezium-architecture.png[Debezium Architecture]
endif::[]

:snapshotStep: 0

The connector...::
[cols="1,9"]
|===
|Step |Action

|``{counter:snapshotStep}``
a| Grabs a *global read lock* that blocks _writes_ by other database clients.

NOTE: The snapshot itself does not prevent other clients from applying DDL which might interfere with the connector's attempt to read the binlog position and table schemas. The global read lock is kept while the binlog position is read before released in a later step.

|``{counter:snapshotStep}``
a| Starts a transaction with link:https://dev.mysql.com/doc/refman/{mysql-version}/en/innodb-consistent-read.html[repeatable read semantics] to ensure that all subsequent reads within the transaction are done against the _consistent snapshot_.

|``{counter:snapshotStep}``
a| Reads the current binlog position.

|``{counter:snapshotStep}``
a| Reads the schema of the databases and tables allowed by the connector's configuration.

|``{counter:snapshotStep}``
a| Releases the *global read lock*. This now allows other database clients to write to the database.

|``{counter:snapshotStep}``
a| Writes the DDL changes to the schema change topic, including all necessary `DROP...` and `CREATE...` DDL statements.

NOTE: This happens if applicable.

|``{counter:snapshotStep}``
a| Scans the database tables and generates `CREATE` events on the relevant table-specific Kafka topics for each row.

|``{counter:snapshotStep}``
a| Commits the transaction.

|``{counter:snapshotStep}``
a| Records the completed snapshot in the connector offsets.

|===

== What happens if the connector fails?

If the connector fails, stops, or is rebalanced while making the _initial snapshot_, the connector creates a new snapshot once restarted. Once that _intial snapshot_ is completed, the {prodname} MySQL connector restarts from the same position in the binlog so it does not miss any updates.

NOTE: If the connector stops for long enough, MySQL could purge old binlog files and the connector's position would be lost. If the position is lost, the connector reverts to the _initial snapshot_ for its starting position. For more tips on troubleshooting the {prodname} MySQL connector, see {link-prefix}:{link-mysql-connector}#connector-common-issues[MySQL connector common issues].

== What if Global Read Locks are not allowed?
[[no-global-read-lock-mysql-connect_{context}]]

Some environments do not allow a *global read lock*. If the {prodname} MySQL connector detects that global read locks are not permitted, the connector uses table-level locks instead and performs a snapshot with this method.

IMPORTANT: The user must have `LOCK_TABLES` privileges.

:snapshotStep-noLock: 0

The connector...::
[cols="1,9"]
|===
|Step |Action

|``{counter:snapshotStep-noLock}``
a| Starts a transaction with link:https://dev.mysql.com/doc/refman/{mysql-version}/en/innodb-consistent-read.html[repeatable read semantics] to ensure that all subsequent reads within the transaction are done against the _consistent snapshot_.

|``{counter:snapshotStep-noLock}``
| Reads and filters the names of the databases and tables.

|``{counter:snapshotStep-noLock}``
a| Reads the current binlog position.

|``{counter:snapshotStep-noLock}``
a| Reads the schema of the databases and tables allowed by the connector's configuration.

|``{counter:snapshotStep-noLock}``
a| Writes the DDL changes to the schema change topic, including all necessary `DROP...` and `CREATE...` DDL statements.

NOTE: This happens if applicable.

|``{counter:snapshotStep-noLock}``
a| Scans the database tables and generates `CREATE` events on the relevant table-specific Kafka topics for each row.

|``{counter:snapshotStep-noLock}``
a| Commits the transaction.

|``{counter:snapshotStep-noLock}``
| Releases the table-level locks.

|``{counter:snapshotStep-noLock}``
a| Records the completed snapshot in the connector offsets.

|===
