diff --git a/sql-statements/sql-statement-rename-table.md b/sql-statements/sql-statement-rename-table.md index 6f03a06f4ca91..d04300bcbd24b 100644 --- a/sql-statements/sql-statement-rename-table.md +++ b/sql-statements/sql-statement-rename-table.md @@ -6,7 +6,7 @@ aliases: ['/docs/dev/sql-statements/sql-statement-rename-table/','/docs/dev/refe # RENAME TABLE -This statement renames an existing table to a new name. +This statement is used to rename existing tables and views, supporting renaming multiple tables at once and renaming across databases. ## Synopsis @@ -21,21 +21,39 @@ TableToTable ::= ## Examples ```sql -mysql> CREATE TABLE t1 (a int); +CREATE TABLE t1 (a int); +``` + +``` Query OK, 0 rows affected (0.12 sec) +``` + +```sql +SHOW TABLES; +``` -mysql> SHOW TABLES; +``` +----------------+ | Tables_in_test | +----------------+ | t1 | +----------------+ 1 row in set (0.00 sec) +``` + +```sql +RENAME TABLE t1 TO t2; +``` -mysql> RENAME TABLE t1 TO t2; +``` Query OK, 0 rows affected (0.08 sec) +``` + +```sql +SHOW TABLES; +``` -mysql> SHOW TABLES; +``` +----------------+ | Tables_in_test | +----------------+ @@ -44,6 +62,103 @@ mysql> SHOW TABLES; 1 row in set (0.00 sec) ``` +The following example demonstrates how to rename multiple tables across databases, assuming that the databases `db1`, `db2`, `db3`, and `db4` already exist, and that the tables `db1.t1` and `db3.t3` already exist: + +```sql +RENAME TABLE db1.t1 To db2.t2, db3.t3 To db4.t4; +``` + +``` +Query OK, 0 rows affected (0.08 sec) +``` + +```sql +USE db1; SHOW TABLES; +``` + +``` +Database changed +Empty set (0.00 sec) +``` + +```sql +USE db2; SHOW TABLES; +``` + +``` +Database changed ++---------------+ +| Tables_in_db2 | ++---------------+ +| t2 | ++---------------+ +1 row in set (0.00 sec) +``` + +```sql +USE db3; SHOW TABLES; +``` + +``` +Database changed +Empty set (0.00 sec) +``` + +```sql +USE db4; SHOW TABLES; +``` + +``` +Database changed ++---------------+ +| Tables_in_db4 | ++---------------+ +| t4 | ++---------------+ +1 row in set (0.00 sec) +``` + +The atomic rename can be used to swap out a table without having any moment in which the table does not exist. + +```sql +CREATE TABLE t1(id int PRIMARY KEY); +``` + +``` +Query OK, 0 rows affected (0.04 sec) +``` + +```sql +CREATE TABLE t1_new(id int PRIMARY KEY, n CHAR(0)); +```` + +``` +Query OK, 0 rows affected (0.04 sec) +``` + +```sql +RENAME TABLE t1 TO t1_old, t1_new TO t1; +``` + +``` +Query OK, 0 rows affected (0.07 sec) +``` + +```sql +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) +``` + ## MySQL compatibility The `RENAME TABLE` statement in TiDB is fully compatible with MySQL. If you find any compatibility differences, [report a bug](https://docs.pingcap.com/tidb/stable/support).