From ed2558500978e72702c908a6357e7c91e9f98dee Mon Sep 17 00:00:00 2001 From: Fiore Mario Vitale Date: Thu, 29 Feb 2024 09:36:32 +0100 Subject: [PATCH] DBZ-7461 Update doc for snapshot modes alignment Co-authored-by: roldanbob --- .../modules/ROOT/pages/connectors/mysql.adoc | 29 +++++++++++-------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/documentation/modules/ROOT/pages/connectors/mysql.adoc b/documentation/modules/ROOT/pages/connectors/mysql.adoc index e216531d8..8c45ea526 100644 --- a/documentation/modules/ROOT/pages/connectors/mysql.adoc +++ b/documentation/modules/ROOT/pages/connectors/mysql.adoc @@ -637,7 +637,9 @@ a|Record the successful completion of the snapshot in the connector offsets. |Setting |Description |`always` -|The connector performs a database snapshot after every restart. +|The connector performs a snapshot every time that it starts. +The snapshot includes the structure and data of the captured tables. +Specify this value to populate topics with a complete representation of the data from the captured tables every time that the connector starts. After the snapshot completes, the connector begins to stream event records for subsequent database changes. |`initial` @@ -645,7 +647,8 @@ After the snapshot completes, the connector begins to stream event records for s After the snapshot completes, the connector begins to stream event records for subsequent database changes. |`initial_only` -|The connector performs a database snapshot and stops before streaming any change event records, not allowing any subsequent change events to be captured. +|The connector performs a database snapshot. +After the snapshot completes, the connector stops, and does not stream event records for subsequent database changes. |`schema_only` |Deprecated, see `no_data`. @@ -3412,7 +3415,8 @@ For example, if you set `max.queue.size=1000`, and `max.queue.size.in.bytes=5000 |_initial_ |Specifies the criteria for running a snapshot when the connector starts. Possible settings are: + -`always`:: The snapshot includes the structure and data of the captured tables. +`always`:: The connector performs a snapshot every time that it starts. +The snapshot includes the structure and data of the captured tables. Specify this value to populate topics with a complete representation of the data from the captured tables every time that the connector starts. `initial`:: The connector runs a snapshot only when no offsets have been recorded for the logical server name. @@ -3450,22 +3454,23 @@ endif::community[] |_minimal_ a|Controls whether and how long the connector holds the global MySQL read lock, which prevents any updates to the database, while the connector is performing a snapshot. Possible settings are: + -`minimal`:: The connector holds the global read lock for only the initial portion of the snapshot during which the connector reads the database schemas and other metadata. -The remaining work in a snapshot involves selecting all rows from each table. -The connector can do this in a consistent fashion by using a REPEATABLE READ transaction. -This is the case even when the global read lock is no longer held and other MySQL clients are updating the database. + +`minimal`:: The connector holds the global read lock for only the initial phase of the snapshot during which it reads the database schemas and other metadata. +During the next phase of the snapshot, the connector releases the lock as it selects all rows from each table. +To perform the SELECT operation in a consistent fashion, the connector uses a REPEATABLE READ transaction. +Although the release of the global read lock permits other MySQL clients to update the database, use of REPEATABLE READ isolation ensures a consistent snapshot, because the connector continues to read the same data for the duration of the transaction. + -`minimal_percona`:: The connector holds link:https://www.percona.com/doc/percona-server/8.0/management/backup_locks.html[the global backup lock] for only the initial portion of the snapshot during which the connector reads the database schemas and other metadata. -The remaining work in a snapshot involves selecting all rows from each table. -The connector can do this in a consistent fashion by using a REPEATABLE READ transaction. -This is the case even when the global backup lock is no longer held and other MySQL clients are updating the database. +`minimal_percona`:: The connector holds link:https://www.percona.com/doc/percona-server/8.0/management/backup_locks.html[the global backup lock] for only the initial phase of the snapshot during which it reads the database schemas and other metadata. +During the next phase of the snapshot, the connector releases the lock as it selects all rows from each table. +To perform the SELECT operation in a consistent fashion, the connector uses a REPEATABLE READ transaction. + +Although the release of the global read lock permits other MySQL clients to update the database, use of REPEATABLE READ isolation ensures a consistent snapshot, because the connector continues to read the same data for the duration of the transaction. + This mode does not flush tables to disk, is not blocked by long-running reads, and is available only in Percona Server. + `extended`:: Blocks all write operations for the duration of the snapshot. Use this setting if clients submit concurrent operations that are incompatible with the REPEATABLE READ isolation level in MySQL. + `none`:: Prevents the connector from acquiring any table locks during the snapshot. -Although this option is allowed with all snapshot modes, it is safe to use if and _only_ if no schema changes occur while the snapshot is running. +Although this option is allowed with all snapshot modes, it is safe to use _only_ if no schema changes occur while the snapshot is running. Tables that are defined with the MyISAM engine always acquire a table lock. As a result, such tables are locked even if you set this option. This behavior differs from tables that are defined by the InnoDB engine, which acquire row-level locks.