From 4762c82d244a94422bc2c71532b5e777e95236f0 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/3] 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 48b41f16a6e09..4f8e2bccc0861 100644 --- a/dm/dm-precheck.md +++ b/dm/dm-precheck.md @@ -69,7 +69,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 a30add5b6761d..d999a317ef68d 100644 --- a/dm/dm-worker-intro.md +++ b/dm/dm-worker-intro.md @@ -52,11 +52,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 13e1a4d85914b..e916ff715779a 100644 --- a/dm/quick-start-with-dm.md +++ b/dm/quick-start-with-dm.md @@ -91,6 +91,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 @@ -148,6 +150,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 d3325d746493f138ec56bf2d463675241ba92abe 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/3] 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 4f8e2bccc0861..9265306c7b89c 100644 --- a/dm/dm-precheck.md +++ b/dm/dm-precheck.md @@ -69,7 +69,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 d999a317ef68d..e0239abe33f86 100644 --- a/dm/dm-worker-intro.md +++ b/dm/dm-worker-intro.md @@ -52,16 +52,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 e916ff715779a..2188b9ea38944 100644 --- a/dm/quick-start-with-dm.md +++ b/dm/quick-start-with-dm.md @@ -91,7 +91,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: @@ -150,7 +150,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 10eaa6fd633014662a4e5f9b75948e5d99b87574 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/3] 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 9265306c7b89c..83a92a36561a1 100644 --- a/dm/dm-precheck.md +++ b/dm/dm-precheck.md @@ -73,7 +73,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 e0239abe33f86..97167142fe391 100644 --- a/dm/dm-worker-intro.md +++ b/dm/dm-worker-intro.md @@ -54,7 +54,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 2188b9ea38944..bfcd552069aec 100644 --- a/dm/quick-start-with-dm.md +++ b/dm/quick-start-with-dm.md @@ -91,7 +91,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: @@ -150,7 +150,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: