From 25ffb409836897f69b69186e7b182ab462d75a69 Mon Sep 17 00:00:00 2001 From: Airton Lastori <6343615+alastori@users.noreply.github.com> Date: Fri, 20 Mar 2026 17:07:04 -0400 Subject: [PATCH 1/6] add LOCK TABLES note for managed MySQL sources in OSS DM docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When migrating from managed MySQL services (RDS, Aurora) where FTWRL is restricted, DM's consistency=auto mode falls back to LOCK TABLES. Added conditional privilege documentation to dm-worker-intro, dm-precheck, and quick-start-with-dm. Confirmed with Minghao Guo: FTWRL→LOCK TABLES fallback is by design, Cloud DM defaults to consistency=auto. Lab evidence: https://github.com/alastori/tidb-sandbox/tree/main/labs/dm/lab-06-lock-tables-privilege Related: https://github.com/pingcap/docs/pull/22598 (Cloud DM docs) Related: https://tidb.atlassian.net/browse/DM-12687 (pre-check improvement) --- dm/dm-precheck.md | 2 +- dm/dm-worker-intro.md | 5 +++++ dm/quick-start-with-dm.md | 4 ++++ 3 files changed, 10 insertions(+), 1 deletion(-) diff --git a/dm/dm-precheck.md b/dm/dm-precheck.md index 4121769a4e4d4..8f77d5c0c5a67 100644 --- a/dm/dm-precheck.md +++ b/dm/dm-precheck.md @@ -68,7 +68,7 @@ For the full data migration mode (`task-mode: full`), in addition to the [common - SELECT permission on INFORMATION_SCHEMA and dump tables - RELOAD permission if `consistency=flush` - - LOCK TABLES permission on the dump tables if `consistency=flush/lock` + - LOCK TABLES permission on the dump tables if `consistency=lock`, or if `consistency=auto` and the source is a managed MySQL service (such as Amazon RDS or Aurora) where `FLUSH TABLES WITH READ LOCK` is restricted * (Mandatory) Consistency of upstream MySQL multi-instance sharding tables diff --git a/dm/dm-worker-intro.md b/dm/dm-worker-intro.md index a6328065ee005..cc734a1dcc99d 100644 --- a/dm/dm-worker-intro.md +++ b/dm/dm-worker-intro.md @@ -51,11 +51,16 @@ The upstream database (MySQL/MariaDB) user must have the following privileges: | `REPLICATION SLAVE` | Global | | `REPLICATION CLIENT` | Global | +> **Note:** If migrating from a managed MySQL service (such as Amazon RDS or Aurora) where `FLUSH TABLES WITH READ LOCK` is restricted, the user also needs the `LOCK TABLES` privilege. DM's default `consistency=auto` mode falls back to `LOCK TABLES` for data consistency when FTWRL is unavailable. + If you need to migrate the data from `db1` to TiDB, execute the following `GRANT` statement: ```sql GRANT RELOAD,REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'your_user'@'your_wildcard_of_host'; GRANT SELECT ON db1.* TO 'your_user'@'your_wildcard_of_host'; + +-- For managed MySQL (Amazon RDS, Aurora, etc.), also grant: +-- GRANT LOCK TABLES ON db1.* TO 'your_user'@'your_wildcard_of_host'; ``` If you also need to migrate the data from other databases into TiDB, make sure the same privileges are granted to the user of the respective databases. diff --git a/dm/quick-start-with-dm.md b/dm/quick-start-with-dm.md index f8fe19ab001b2..7c74c254da58e 100644 --- a/dm/quick-start-with-dm.md +++ b/dm/quick-start-with-dm.md @@ -90,6 +90,8 @@ You can use Docker to quickly deploy a test MySQL 8.0 instance. GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; ``` + > **Note:** If your MySQL source is a managed service (such as Amazon RDS or Aurora), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. + 4. Create sample data: ```sql @@ -147,6 +149,8 @@ On macOS, you can quickly install and start MySQL 8.0 locally using [Homebrew](h GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; ``` + > **Note:** If your MySQL source is a managed service (such as Amazon RDS or Aurora), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. + 6. Create sample data: ```sql From 799c4f754fa8e929d7b58f38fb9229bdd1657ad1 Mon Sep 17 00:00:00 2001 From: Airton Lastori <6343615+alastori@users.noreply.github.com> Date: Fri, 20 Mar 2026 17:53:22 -0400 Subject: [PATCH 2/6] review fixes: accurate precheck description, expand provider list - dm-precheck.md: separate what precheck checks (consistency=lock) from what's needed at runtime (auto fallback), with explicit Note that precheck does not currently validate this - Expand all provider lists to include Azure and Google Cloud SQL - Use "not permitted" consistently instead of "restricted" - Fix commented-out GRANT: use separate code block instead - Also fixes pre-existing error: old text said LOCK TABLES needed for consistency=flush, but flush uses FTWRL (RELOAD), not LOCK TABLES --- dm/dm-precheck.md | 6 +++++- dm/dm-worker-intro.md | 11 ++++++++--- dm/quick-start-with-dm.md | 4 ++-- 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/dm/dm-precheck.md b/dm/dm-precheck.md index 8f77d5c0c5a67..d45fec549916f 100644 --- a/dm/dm-precheck.md +++ b/dm/dm-precheck.md @@ -68,7 +68,11 @@ For the full data migration mode (`task-mode: full`), in addition to the [common - SELECT permission on INFORMATION_SCHEMA and dump tables - RELOAD permission if `consistency=flush` - - LOCK TABLES permission on the dump tables if `consistency=lock`, or if `consistency=auto` and the source is a managed MySQL service (such as Amazon RDS or Aurora) where `FLUSH TABLES WITH READ LOCK` is restricted + - LOCK TABLES permission on the dump tables if `consistency=lock` + + > **Note:** + > + > When `consistency=auto` (the default), DM first attempts `FLUSH TABLES WITH READ LOCK` and falls back to `LOCK TABLES` if FTWRL is unavailable. This fallback commonly occurs on managed MySQL services (such as Amazon RDS, Aurora, Azure Database for MySQL, or Google Cloud SQL) where FTWRL is not permitted. In this case, the `LOCK TABLES` privilege is required at runtime, but the precheck does not currently validate it. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for the full privilege list. * (Mandatory) Consistency of upstream MySQL multi-instance sharding tables diff --git a/dm/dm-worker-intro.md b/dm/dm-worker-intro.md index cc734a1dcc99d..8530591c71bc7 100644 --- a/dm/dm-worker-intro.md +++ b/dm/dm-worker-intro.md @@ -51,16 +51,21 @@ The upstream database (MySQL/MariaDB) user must have the following privileges: | `REPLICATION SLAVE` | Global | | `REPLICATION CLIENT` | Global | -> **Note:** If migrating from a managed MySQL service (such as Amazon RDS or Aurora) where `FLUSH TABLES WITH READ LOCK` is restricted, the user also needs the `LOCK TABLES` privilege. DM's default `consistency=auto` mode falls back to `LOCK TABLES` for data consistency when FTWRL is unavailable. +> **Note:** +> +> If migrating from a managed MySQL service (such as Amazon RDS, Aurora, Azure Database for MySQL, or Google Cloud SQL) where `FLUSH TABLES WITH READ LOCK` is not permitted, the user also needs the `LOCK TABLES` privilege. DM's default `consistency=auto` mode falls back to `LOCK TABLES` for data consistency when FTWRL is unavailable. If you need to migrate the data from `db1` to TiDB, execute the following `GRANT` statement: ```sql GRANT RELOAD,REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'your_user'@'your_wildcard_of_host'; GRANT SELECT ON db1.* TO 'your_user'@'your_wildcard_of_host'; +``` --- For managed MySQL (Amazon RDS, Aurora, etc.), also grant: --- GRANT LOCK TABLES ON db1.* TO 'your_user'@'your_wildcard_of_host'; +For managed MySQL services where FTWRL is not permitted, also grant `LOCK TABLES`: + +```sql +GRANT LOCK TABLES ON db1.* TO 'your_user'@'your_wildcard_of_host'; ``` If you also need to migrate the data from other databases into TiDB, make sure the same privileges are granted to the user of the respective databases. diff --git a/dm/quick-start-with-dm.md b/dm/quick-start-with-dm.md index 7c74c254da58e..80d6142b3ec5f 100644 --- a/dm/quick-start-with-dm.md +++ b/dm/quick-start-with-dm.md @@ -90,7 +90,7 @@ You can use Docker to quickly deploy a test MySQL 8.0 instance. GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; ``` - > **Note:** If your MySQL source is a managed service (such as Amazon RDS or Aurora), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. + > **Note:** If your MySQL source is a managed service (such as Amazon RDS, Aurora, Azure Database for MySQL, or Google Cloud SQL), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. 4. Create sample data: @@ -149,7 +149,7 @@ On macOS, you can quickly install and start MySQL 8.0 locally using [Homebrew](h GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; ``` - > **Note:** If your MySQL source is a managed service (such as Amazon RDS or Aurora), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. + > **Note:** If your MySQL source is a managed service (such as Amazon RDS, Aurora, Azure Database for MySQL, or Google Cloud SQL), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. 6. Create sample data: From 3284f29afef17b00b4bfc97545f210d9fef6e187 Mon Sep 17 00:00:00 2001 From: Airton Lastori <6343615+alastori@users.noreply.github.com> Date: Fri, 20 Mar 2026 17:59:27 -0400 Subject: [PATCH 3/6] add ApsaraDB RDS for MySQL to managed provider list --- dm/dm-precheck.md | 2 +- dm/dm-worker-intro.md | 2 +- dm/quick-start-with-dm.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/dm/dm-precheck.md b/dm/dm-precheck.md index d45fec549916f..69dc441a841a0 100644 --- a/dm/dm-precheck.md +++ b/dm/dm-precheck.md @@ -72,7 +72,7 @@ For the full data migration mode (`task-mode: full`), in addition to the [common > **Note:** > - > When `consistency=auto` (the default), DM first attempts `FLUSH TABLES WITH READ LOCK` and falls back to `LOCK TABLES` if FTWRL is unavailable. This fallback commonly occurs on managed MySQL services (such as Amazon RDS, Aurora, Azure Database for MySQL, or Google Cloud SQL) where FTWRL is not permitted. In this case, the `LOCK TABLES` privilege is required at runtime, but the precheck does not currently validate it. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for the full privilege list. + > When `consistency=auto` (the default), DM first attempts `FLUSH TABLES WITH READ LOCK` and falls back to `LOCK TABLES` if FTWRL is unavailable. This fallback commonly occurs on managed MySQL services (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL) where FTWRL is not permitted. In this case, the `LOCK TABLES` privilege is required at runtime, but the precheck does not currently validate it. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for the full privilege list. * (Mandatory) Consistency of upstream MySQL multi-instance sharding tables diff --git a/dm/dm-worker-intro.md b/dm/dm-worker-intro.md index 8530591c71bc7..dc70efc678853 100644 --- a/dm/dm-worker-intro.md +++ b/dm/dm-worker-intro.md @@ -53,7 +53,7 @@ The upstream database (MySQL/MariaDB) user must have the following privileges: > **Note:** > -> If migrating from a managed MySQL service (such as Amazon RDS, Aurora, Azure Database for MySQL, or Google Cloud SQL) where `FLUSH TABLES WITH READ LOCK` is not permitted, the user also needs the `LOCK TABLES` privilege. DM's default `consistency=auto` mode falls back to `LOCK TABLES` for data consistency when FTWRL is unavailable. +> If migrating from a managed MySQL service (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL) where `FLUSH TABLES WITH READ LOCK` is not permitted, the user also needs the `LOCK TABLES` privilege. DM's default `consistency=auto` mode falls back to `LOCK TABLES` for data consistency when FTWRL is unavailable. If you need to migrate the data from `db1` to TiDB, execute the following `GRANT` statement: diff --git a/dm/quick-start-with-dm.md b/dm/quick-start-with-dm.md index 80d6142b3ec5f..37a0640940bdc 100644 --- a/dm/quick-start-with-dm.md +++ b/dm/quick-start-with-dm.md @@ -90,7 +90,7 @@ You can use Docker to quickly deploy a test MySQL 8.0 instance. GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; ``` - > **Note:** If your MySQL source is a managed service (such as Amazon RDS, Aurora, Azure Database for MySQL, or Google Cloud SQL), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. + > **Note:** If your MySQL source is a managed service (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. 4. Create sample data: @@ -149,7 +149,7 @@ On macOS, you can quickly install and start MySQL 8.0 locally using [Homebrew](h GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; ``` - > **Note:** If your MySQL source is a managed service (such as Amazon RDS, Aurora, Azure Database for MySQL, or Google Cloud SQL), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. + > **Note:** If your MySQL source is a managed service (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. 6. Create sample data: From fcf66166dda5dfcbf1e4faea6c5e69719ad84f9d Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 26 Mar 2026 10:11:47 +0800 Subject: [PATCH 4/6] revise descriptions --- dm/dm-precheck.md | 2 +- dm/dm-worker-intro.md | 4 ++-- dm/quick-start-with-dm.md | 8 ++++++-- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/dm/dm-precheck.md b/dm/dm-precheck.md index 69dc441a841a0..9cccdf04637ff 100644 --- a/dm/dm-precheck.md +++ b/dm/dm-precheck.md @@ -72,7 +72,7 @@ For the full data migration mode (`task-mode: full`), in addition to the [common > **Note:** > - > When `consistency=auto` (the default), DM first attempts `FLUSH TABLES WITH READ LOCK` and falls back to `LOCK TABLES` if FTWRL is unavailable. This fallback commonly occurs on managed MySQL services (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL) where FTWRL is not permitted. In this case, the `LOCK TABLES` privilege is required at runtime, but the precheck does not currently validate it. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for the full privilege list. + > When `consistency=auto` (the default), DM first tries `FLUSH TABLES WITH READ LOCK` (FTWRL). If FTWRL is unavailable, DM falls back to `LOCK TABLES`. This fallback commonly occurs on managed MySQL services (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, and Google Cloud SQL), where FTWRL is not permitted. In this case, the `LOCK TABLES` privilege is required at runtime, but the precheck does not currently verify this privilege. For the full list of privileges, see [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges). * (Mandatory) Consistency of upstream MySQL multi-instance sharding tables diff --git a/dm/dm-worker-intro.md b/dm/dm-worker-intro.md index dc70efc678853..c833c734332a3 100644 --- a/dm/dm-worker-intro.md +++ b/dm/dm-worker-intro.md @@ -53,7 +53,7 @@ The upstream database (MySQL/MariaDB) user must have the following privileges: > **Note:** > -> If migrating from a managed MySQL service (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL) where `FLUSH TABLES WITH READ LOCK` is not permitted, the user also needs the `LOCK TABLES` privilege. DM's default `consistency=auto` mode falls back to `LOCK TABLES` for data consistency when FTWRL is unavailable. +> If you migrate from a managed MySQL service (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL) where `FLUSH TABLES WITH READ LOCK` (FTWRL) is not permitted, also grant the `LOCK TABLES` privilege. With the default `consistency=auto` setting, DM falls back to `LOCK TABLES` when FTWRL is unavailable. If you need to migrate the data from `db1` to TiDB, execute the following `GRANT` statement: @@ -62,7 +62,7 @@ GRANT RELOAD,REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'your_user'@'your_w GRANT SELECT ON db1.* TO 'your_user'@'your_wildcard_of_host'; ``` -For managed MySQL services where FTWRL is not permitted, also grant `LOCK TABLES`: +For managed MySQL services where FTWRL is not permitted, also grant the `LOCK TABLES` privilege: ```sql GRANT LOCK TABLES ON db1.* TO 'your_user'@'your_wildcard_of_host'; diff --git a/dm/quick-start-with-dm.md b/dm/quick-start-with-dm.md index 37a0640940bdc..b14ec69c696dc 100644 --- a/dm/quick-start-with-dm.md +++ b/dm/quick-start-with-dm.md @@ -90,7 +90,9 @@ You can use Docker to quickly deploy a test MySQL 8.0 instance. GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; ``` - > **Note:** If your MySQL source is a managed service (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. + > **Note:** + > + > If your MySQL source is a managed MySQL service (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL), also grant the `LOCK TABLES` privilege. For more information, see [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges). 4. Create sample data: @@ -149,7 +151,9 @@ On macOS, you can quickly install and start MySQL 8.0 locally using [Homebrew](h GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%'; ``` - > **Note:** If your MySQL source is a managed service (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL), also grant `LOCK TABLES`. See [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges) for details. + > **Note:** + > + > If your MySQL source is a managed MySQL service (such as Amazon RDS, Aurora, ApsaraDB RDS for MySQL, Azure Database for MySQL, or Google Cloud SQL), also grant the `LOCK TABLES` privilege. For more information, see [DM-worker privileges](/dm/dm-worker-intro.md#upstream-database-user-privileges). 6. Create sample data: From 69adae2b64f8109dea7ebe228dad15689e395a16 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 16 Apr 2026 10:48:30 +0800 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: xixirangrang --- dm/dm-precheck.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dm/dm-precheck.md b/dm/dm-precheck.md index 9cccdf04637ff..d7ba9102dbe1e 100644 --- a/dm/dm-precheck.md +++ b/dm/dm-precheck.md @@ -66,9 +66,9 @@ For the full data migration mode (`task-mode: full`), in addition to the [common * (Mandatory) dump permission of the upstream database - - SELECT permission on INFORMATION_SCHEMA and dump tables - - RELOAD permission if `consistency=flush` - - LOCK TABLES permission on the dump tables if `consistency=lock` + - `SELECT` permission on `INFORMATION_SCHEMA` and dump tables + - `RELOAD` permission if `consistency=flush` + - `LOCK TABLES` permission on the dump tables if `consistency=lock` > **Note:** > From 836bdc600e65f2945adf9fbff1e9e168303f4ed0 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 16 Apr 2026 11:40:55 +0800 Subject: [PATCH 6/6] Update dm/dm-worker-intro.md --- dm/dm-worker-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dm/dm-worker-intro.md b/dm/dm-worker-intro.md index c833c734332a3..8ec0190b0bb97 100644 --- a/dm/dm-worker-intro.md +++ b/dm/dm-worker-intro.md @@ -62,7 +62,7 @@ GRANT RELOAD,REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'your_user'@'your_w GRANT SELECT ON db1.* TO 'your_user'@'your_wildcard_of_host'; ``` -For managed MySQL services where FTWRL is not permitted, also grant the `LOCK TABLES` privilege: +For managed MySQL services where `FLUSH TABLES WITH READ LOCK` (FTWRL) is not permitted, also grant the `LOCK TABLES` privilege: ```sql GRANT LOCK TABLES ON db1.* TO 'your_user'@'your_wildcard_of_host';