Skip to content

Commit cd4fb2b

Browse files
committed
add LOCK TABLES note for managed MySQL sources in OSS DM docs
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: #22598 (Cloud DM docs) Related: https://tidb.atlassian.net/browse/DM-12687 (pre-check improvement)
1 parent 9e9cf88 commit cd4fb2b

3 files changed

Lines changed: 19 additions & 1 deletion

File tree

dm/dm-precheck.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,11 @@ For the full data migration mode (`task-mode: full`), in addition to the [common
6868

6969
- SELECT permission on INFORMATION_SCHEMA and dump tables
7070
- RELOAD permission if `consistency=flush`
71-
- LOCK TABLES permission on the dump tables if `consistency=flush/lock`
71+
- LOCK TABLES permission on the dump tables if `consistency=lock`
72+
73+
> **Note:**
74+
>
75+
> 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.
7276
7377
* (Mandatory) Consistency of upstream MySQL multi-instance sharding tables
7478

dm/dm-worker-intro.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,13 +51,23 @@ The upstream database (MySQL/MariaDB) user must have the following privileges:
5151
| `REPLICATION SLAVE` | Global |
5252
| `REPLICATION CLIENT` | Global |
5353

54+
> **Note:**
55+
>
56+
> 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.
57+
5458
If you need to migrate the data from `db1` to TiDB, execute the following `GRANT` statement:
5559

5660
```sql
5761
GRANT RELOAD,REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'your_user'@'your_wildcard_of_host';
5862
GRANT SELECT ON db1.* TO 'your_user'@'your_wildcard_of_host';
5963
```
6064

65+
For managed MySQL services where FTWRL is not permitted, also grant `LOCK TABLES`:
66+
67+
```sql
68+
GRANT LOCK TABLES ON db1.* TO 'your_user'@'your_wildcard_of_host';
69+
```
70+
6171
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.
6272

6373
### Downstream database user privileges

dm/quick-start-with-dm.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,8 @@ You can use Docker to quickly deploy a test MySQL 8.0 instance.
9090
GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%';
9191
```
9292

93+
> **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.
94+
9395
4. Create sample data:
9496

9597
```sql
@@ -147,6 +149,8 @@ On macOS, you can quickly install and start MySQL 8.0 locally using [Homebrew](h
147149
GRANT PROCESS, BACKUP_ADMIN, RELOAD, REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'tidb-dm'@'%';
148150
```
149151

152+
> **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.
153+
150154
6. Create sample data:
151155

152156
```sql

0 commit comments

Comments
 (0)