sql: RENAME TABLE supports renaming multiple tables and across dbs

[hfxsd]

First-time contributors' checklist

• I've signed Contributor License Agreement that's required for repo owners to accept my contribution.

What is changed, added or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions.

• master (the latest development version)
• v9.0 (TiDB 9.0 versions)
• v8.5 (TiDB 8.5 versions)
• v8.4 (TiDB 8.4 versions)
• v8.3 (TiDB 8.3 versions)
• v8.1 (TiDB 8.1 versions)
• v7.5 (TiDB 7.5 versions)
• v7.1 (TiDB 7.1 versions)
• v6.5 (TiDB 6.5 versions)
• v6.1 (TiDB 6.1 versions)
• v5.4 (TiDB 5.4 versions)

What is the related PR or file link(s)?

• This PR is translated from:sql: RENAME TABLE supports renaming multiple tables and across dbs docs-cn#19452
• Other reference link(s):

Do your changes match any of the following descriptions?

• Delete files
• Change aliases
• Need modification after applied to another branch
• Might cause conflicts after applied to another branch

[dveeden]

The atomic rename is often used to swap out a table without having any moment in which the table doesn't exist. The example doesn't show this yet

mysql-8.0.11-TiDB-v8.5.0> CREATE TABLE t1(id int PRIMARY KEY);
Query OK, 0 rows affected (0.04 sec)

mysql-8.0.11-TiDB-v8.5.0> CREATE TABLE t1_new(id int PRIMARY KEY, n CHAR(0));
Query OK, 0 rows affected (0.04 sec)

mysql-8.0.11-TiDB-v8.5.0> RENAME TABLE t1 TO t1_old, t1_new TO t1;
Query OK, 0 rows affected (0.07 sec)

mysql-8.0.11-TiDB-v8.5.0> SHOW CREATE TABLE t1\G
*************************** 1. row ***************************
       Table: t1
Create Table: CREATE TABLE `t1` (
  `id` int NOT NULL,
  `n` char(0) DEFAULT NULL,
  PRIMARY KEY (`id`) /*T![clustered_index] CLUSTERED */
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin
1 row in set (0.00 sec)

[ti-chi-bot]

@djshow832: adding LGTM is restricted to approvers and reviewers in OWNERS files.

In response to this:

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[ti-chi-bot]

@djshow832: adding LGTM is restricted to approvers and reviewers in OWNERS files.

In response to this:

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[dveeden]

The atomic rename is often used to swap out a table without having any moment in which the table doesn't exist. The example doesn't show this yet

[djshow832]

The atomic rename is often used to swap out a table without having any moment in which the table doesn't exist. The example doesn't show this yet

mysql-8.0.11-TiDB-v8.5.0> CREATE TABLE t1(id int PRIMARY KEY);
Query OK, 0 rows affected (0.04 sec)

mysql-8.0.11-TiDB-v8.5.0> CREATE TABLE t1_new(id int PRIMARY KEY, n CHAR(0));
Query OK, 0 rows affected (0.04 sec)

mysql-8.0.11-TiDB-v8.5.0> RENAME TABLE t1 TO t1_old, t1_new TO t1;
Query OK, 0 rows affected (0.07 sec)

mysql-8.0.11-TiDB-v8.5.0> SHOW CREATE TABLE t1\G
*************************** 1. row ***************************
       Table: t1
Create Table: CREATE TABLE `t1` (
  `id` int NOT NULL,
  `n` char(0) DEFAULT NULL,
  PRIMARY KEY (`id`) /*T![clustered_index] CLUSTERED */
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin
1 row in set (0.00 sec)

Is this example used to alter table t1? Why not just alter table t1? @dveeden

[dveeden]

The atomic rename is often used to swap out a table without having any moment in which the table doesn't exist. The example doesn't show this yet

mysql-8.0.11-TiDB-v8.5.0> CREATE TABLE t1(id int PRIMARY KEY);
Query OK, 0 rows affected (0.04 sec)

mysql-8.0.11-TiDB-v8.5.0> CREATE TABLE t1_new(id int PRIMARY KEY, n CHAR(0));
Query OK, 0 rows affected (0.04 sec)

mysql-8.0.11-TiDB-v8.5.0> RENAME TABLE t1 TO t1_old, t1_new TO t1;
Query OK, 0 rows affected (0.07 sec)

mysql-8.0.11-TiDB-v8.5.0> SHOW CREATE TABLE t1\G
*************************** 1. row ***************************
       Table: t1
Create Table: CREATE TABLE `t1` (
  `id` int NOT NULL,
  `n` char(0) DEFAULT NULL,
  PRIMARY KEY (`id`) /*T![clustered_index] CLUSTERED */
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin
1 row in set (0.00 sec)

Is this example used to alter table t1? Why not just alter table t1? @dveeden

One example is archiving data. This allows the archive to have different permissions and columns etc. or be moved to a different server. Somewhat similar to partitioning, but more flexible.

sql> CREATE TABLE t1 (id INT PRIMARY KEY);
Query OK, 0 rows affected (0.0440 sec)

sql> INSERT INTO t1 VALUES (1),(2),(3);
Query OK, 3 rows affected (0.0116 sec)

Records: 3  Duplicates: 0  Warnings: 0

sql> CREATE TABLE t1_new LIKE t1;
Query OK, 0 rows affected (0.0456 sec)

sql> RENAME TABLE t1 TO t1_202501, t1_new TO t1;
Query OK, 0 rows affected (0.0677 sec)

sql> INSERT INTO t1 VALUES (4),(5),(6);
Query OK, 3 rows affected (0.0111 sec)

Records: 3  Duplicates: 0  Warnings: 0

sql> TABLE t1;
+----+
| id |
+----+
|  4 |
|  5 |
|  6 |
+----+
3 rows in set (0.0022 sec)

sql> TABLE t1_202501;
+----+
| id |
+----+
|  1 |
|  2 |
|  3 |
+----+
3 rows in set (0.0016 sec)

The other example is tools like pt-osc and gh-ost:

• https://github.com/percona/percona-toolkit/blob/ce20bc7dd1f70ce0944de601c176a3fd155c2db7/bin/pt-online-schema-change#L11502
• https://github.com/github/gh-ost/blob/d5ab048c1f046821f3c7384a386fc1c3ae399c92/go/logic/applier.go#L1143

These tools don't work with TiDB as they are very MySQL specific, but there might be other tools that also rely on this.

And the last example is to switch between views and tables:

sql> CREATE TABLE t1_shadow (id int primary key);
Query OK, 0 rows affected (0.0460 sec)

sql> CREATE VIEW t1 AS (SELECT * FROM t1_shadow);
Query OK, 0 rows affected (0.0449 sec)

sql> INSERT INTO t1_shadow VALUES (1),(2),(3);
Query OK, 3 rows affected (0.0117 sec)

Records: 3  Duplicates: 0  Warnings: 0

sql> TABLE t1;
+----+
| id |
+----+
|  1 |
|  2 |
|  3 |
+----+
3 rows in set (0.0017 sec)

sql> RENAME TABLE t1 TO t1_view, t1_shadow TO t1;
Query OK, 0 rows affected (0.0679 sec)

sql> TABLE t1;
+----+
| id |
+----+
|  1 |
|  2 |
|  3 |
+----+
3 rows in set (0.0014 sec)

Note that TiDB doesn't support writing to the view, but this can still be useful if you have a single writer and many readers. Unfortunately MySQL and TiDB both don't support 'instead-of' triggers ( https://bugs.mysql.com/bug.php?id=16525 ).

For TiDB this might also help to work around things that aren't supported for ALTER TABLE:

sql> CREATE TABLE t1 (id int PRIMARY KEY);
Query OK, 0 rows affected (0.0466 sec)

sql> INSERT INTO t1 VALUES (1),(2),(3);
Query OK, 3 rows affected (0.0118 sec)

Records: 3  Duplicates: 0  Warnings: 0

sql> ALTER TABLE t1 MODIFY COLUMN id bigint unsigned;
ERROR: 8200 (HY000): Unsupported modify column: this column has primary key flag

sql> CREATE TABLE t1_new (id bigint unsigned PRIMARY KEY);
Query OK, 0 rows affected (0.0457 sec)

sql> BATCH ON t1.id LIMIT 2 INSERT INTO t1_new SELECT * FROM t1;
+----------------+---------------+
| number of jobs | job status    |
+----------------+---------------+
|              2 | all succeeded |
+----------------+---------------+
1 row in set (0.0184 sec)

sql> RENAME TABLE t1 TO t1_old, t1_new TO t1;
Query OK, 0 rows affected (0.0689 sec)

sql> DROP TABLE t1_old;
Query OK, 0 rows affected (0.0908 sec)

sql> TABLE t1;
+----+
| id |
+----+
|  1 |
|  2 |
|  3 |
+----+
3 rows in set (0.0015 sec)

Note here that after backfilling t1_new one would need to copy the last changes under a lock (LOCK TABLES ...?) or copy them after the rename (which isn't fully atomic).

[ti-chi-bot]

[LGTM Timeline notifier]

Timeline:

• 2025-01-02 12:26:25.954903396 +0000 UTC m=+612521.310907937: ☑️ agreed by dveeden.

[hfxsd]

/approve

[hfxsd]

/approve

[hfxsd]

/approve

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: hfxsd

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [hfxsd]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[ti-chi-bot]

In response to a cherrypick label: new pull request created to branch release-8.1: #19877.

[ti-chi-bot]

In response to a cherrypick label: new pull request created to branch release-8.5: #19878.