From 440e5452502507483bc78c09e137c4a37791ed06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Wed, 28 Jan 2026 10:49:10 +0100 Subject: [PATCH 1/6] migrate-from-mariadb: mention automatic prefix index --- migrate-from-mariadb.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/migrate-from-mariadb.md b/migrate-from-mariadb.md index ac345afec9235..526221a9fa18c 100644 --- a/migrate-from-mariadb.md +++ b/migrate-from-mariadb.md @@ -256,6 +256,33 @@ ORDER BY See also [Character Set and Collation](/character-set-and-collation.md). +### Index length + +As shown below, MariaDB automatically changes index definitions for indexes that go over the maximum key length to a prefix index. TiDB follows the MySQL behavior and doesn't automatically change this to a prefix index but returns an error instead. So scripts that create indexes should be changed so they explicitly create prefix indexes where needed. + +``` +MariaDB> \W +Show warnings enabled. +MariaDB> CREATE TABLE t1(id SERIAL, c1 VARCHAR(800)); +Query OK, 0 rows affected (0.024 sec) + +MariaDB> ALTER TABLE t1 ADD INDEX(c1); +Query OK, 0 rows affected, 1 warning (0.031 sec) +Records: 0 Duplicates: 0 Warnings: 1 + +Note (Code 1071): Specified key was too long; max key length is 3072 bytes +MariaDB> SHOW CREATE TABLE t1\G +*************************** 1. row *************************** + Table: t1 +Create Table: CREATE TABLE `t1` ( + `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT, + `c1` varchar(800) DEFAULT NULL, + UNIQUE KEY `id` (`id`), + KEY `c1` (`c1`(768)) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_uca1400_ai_ci +1 row in set (0.001 sec) +``` + ## Dump data with Dumpling and restore data with TiDB Lightning This method assumes that you take your application offline, migrate the data, and then re-configure your application to use the migrated data. From b1e8f5d0c69f07915ffc6aad22f1220831866a5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Wed, 28 Jan 2026 10:55:13 +0100 Subject: [PATCH 2/6] Update migrate-from-mariadb.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- migrate-from-mariadb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/migrate-from-mariadb.md b/migrate-from-mariadb.md index 526221a9fa18c..f4e4b0ca0ab45 100644 --- a/migrate-from-mariadb.md +++ b/migrate-from-mariadb.md @@ -258,7 +258,7 @@ See also [Character Set and Collation](/character-set-and-collation.md). ### Index length -As shown below, MariaDB automatically changes index definitions for indexes that go over the maximum key length to a prefix index. TiDB follows the MySQL behavior and doesn't automatically change this to a prefix index but returns an error instead. So scripts that create indexes should be changed so they explicitly create prefix indexes where needed. +As the following example shows, MariaDB automatically converts an index to a prefix index if it exceeds the maximum key length. TiDB, following MySQL's behavior, does not perform this automatic conversion and instead returns an error. Therefore, you need to modify your scripts to explicitly create prefix indexes where necessary. ``` MariaDB> \W From ac1c2d487fea6941f9c6ebf4526077f66bf9f522 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Wed, 28 Jan 2026 11:11:11 +0100 Subject: [PATCH 3/6] Add unique key info --- migrate-from-mariadb.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/migrate-from-mariadb.md b/migrate-from-mariadb.md index f4e4b0ca0ab45..e75816e15b734 100644 --- a/migrate-from-mariadb.md +++ b/migrate-from-mariadb.md @@ -283,6 +283,34 @@ Create Table: CREATE TABLE `t1` ( 1 row in set (0.001 sec) ``` +MariaDB has special handling for unique indexes that are over the maximum length as show below. TiDB doesn't provide this feature. + +``` +mysql-11.8.5-MariaDB-ubu2404 [test]> CREATE TABLE t2 (id SERIAL PRIMARY KEY, c1 TEXT NOT NULL); +Query OK, 0 rows affected (0.015 sec) + +mysql-11.8.5-MariaDB-ubu2404 [test]> ALTER TABLE t2 ADD INDEX regular_index_c1 (c1); +Query OK, 0 rows affected, 1 warning (0.034 sec) +Records: 0 Duplicates: 0 Warnings: 1 + +Note (Code 1071): Specified key was too long; max key length is 3072 bytes +mysql-11.8.5-MariaDB-ubu2404 [test]> ALTER TABLE t2 ADD UNIQUE INDEX unique_index_c1 (c1); +Query OK, 0 rows affected (0.048 sec) +Records: 0 Duplicates: 0 Warnings: 0 + +mysql-11.8.5-MariaDB-ubu2404 [test]> SHOW CREATE TABLE t2\G +*************************** 1. row *************************** + Table: t2 +Create Table: CREATE TABLE `t2` ( + `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT, + `c1` text NOT NULL, + PRIMARY KEY (`id`), + UNIQUE KEY `unique_index_c1` (`c1`) USING HASH, + KEY `regular_index_c1` (`c1`(768)) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_uca1400_ai_ci +1 row in set (0.001 sec) +``` + ## Dump data with Dumpling and restore data with TiDB Lightning This method assumes that you take your application offline, migrate the data, and then re-configure your application to use the migrated data. From a5453b208f2e11efc1a40a1bdace70bf509f3ae4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Wed, 28 Jan 2026 10:48:57 +0000 Subject: [PATCH 4/6] update --- migrate-from-mariadb.md | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/migrate-from-mariadb.md b/migrate-from-mariadb.md index e75816e15b734..9a47776e26245 100644 --- a/migrate-from-mariadb.md +++ b/migrate-from-mariadb.md @@ -286,19 +286,19 @@ Create Table: CREATE TABLE `t1` ( MariaDB has special handling for unique indexes that are over the maximum length as show below. TiDB doesn't provide this feature. ``` -mysql-11.8.5-MariaDB-ubu2404 [test]> CREATE TABLE t2 (id SERIAL PRIMARY KEY, c1 TEXT NOT NULL); +MariaDB> CREATE TABLE t2 (id SERIAL PRIMARY KEY, c1 TEXT NOT NULL); Query OK, 0 rows affected (0.015 sec) -mysql-11.8.5-MariaDB-ubu2404 [test]> ALTER TABLE t2 ADD INDEX regular_index_c1 (c1); +MariaDB> ALTER TABLE t2 ADD INDEX regular_index_c1 (c1); Query OK, 0 rows affected, 1 warning (0.034 sec) Records: 0 Duplicates: 0 Warnings: 1 Note (Code 1071): Specified key was too long; max key length is 3072 bytes -mysql-11.8.5-MariaDB-ubu2404 [test]> ALTER TABLE t2 ADD UNIQUE INDEX unique_index_c1 (c1); +MariaDB> ALTER TABLE t2 ADD UNIQUE INDEX unique_index_c1 (c1); Query OK, 0 rows affected (0.048 sec) Records: 0 Duplicates: 0 Warnings: 0 -mysql-11.8.5-MariaDB-ubu2404 [test]> SHOW CREATE TABLE t2\G +MariaDB> SHOW CREATE TABLE t2\G *************************** 1. row *************************** Table: t2 Create Table: CREATE TABLE `t2` ( @@ -311,6 +311,29 @@ Create Table: CREATE TABLE `t2` ( 1 row in set (0.001 sec) ``` +You can emulate the behavior like this: + +``` +tidb> > CREATE TABLE t1 (id int PRIMARY KEY, c1 TEXT); +Query OK, 0 rows affected (0.102 sec) + +tidb> > ALTER TABLE t1 ADD COLUMN c1_hash BINARY(32) AS (UNHEX(SHA2(c1,256))); +Query OK, 0 rows affected (0.242 sec) + +tidb> > ALTER TABLE t1 ADD UNIQUE KEY (c1_hash); +Query OK, 0 rows affected (0.363 sec) + +tidb> > INSERT INTO t1(id,c1) VALUES (1,'aaa'); +Query OK, 1 row affected (0.015 sec) + +tidb> > INSERT INTO t1(id,c1) VALUES (2,'bbb'); +Query OK, 1 row affected (0.006 sec) + +tidb> > INSERT INTO t1(id,c1) VALUES (3,'aaa'); +ERROR 1062 (23000): Duplicate entry '\x984\x87m\xCF\xB0\\xB1g\xA5\xC2IS\xEB\xA5\x8CJ\xC8\x9B\x1A\xDFW' for key 't1.c1_hash' +tidb> > +``` + ## Dump data with Dumpling and restore data with TiDB Lightning This method assumes that you take your application offline, migrate the data, and then re-configure your application to use the migrated data. From 349e00d29b84afc89db072c9deb9c61d0a48b8fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Wed, 28 Jan 2026 11:56:03 +0100 Subject: [PATCH 5/6] Update migrate-from-mariadb.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- migrate-from-mariadb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/migrate-from-mariadb.md b/migrate-from-mariadb.md index 9a47776e26245..722fa19c312f2 100644 --- a/migrate-from-mariadb.md +++ b/migrate-from-mariadb.md @@ -283,7 +283,7 @@ Create Table: CREATE TABLE `t1` ( 1 row in set (0.001 sec) ``` -MariaDB has special handling for unique indexes that are over the maximum length as show below. TiDB doesn't provide this feature. +MariaDB has special handling for unique indexes that are over the maximum length as shown below. TiDB does not provide this feature. ``` MariaDB> CREATE TABLE t2 (id SERIAL PRIMARY KEY, c1 TEXT NOT NULL); From e22243ead7a0dbe189a2b1778a258dad763ec49f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Wed, 28 Jan 2026 11:56:20 +0100 Subject: [PATCH 6/6] Update migrate-from-mariadb.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- migrate-from-mariadb.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/migrate-from-mariadb.md b/migrate-from-mariadb.md index 722fa19c312f2..0b1561a375efd 100644 --- a/migrate-from-mariadb.md +++ b/migrate-from-mariadb.md @@ -314,24 +314,24 @@ Create Table: CREATE TABLE `t2` ( You can emulate the behavior like this: ``` -tidb> > CREATE TABLE t1 (id int PRIMARY KEY, c1 TEXT); +tidb> CREATE TABLE t1 (id int PRIMARY KEY, c1 TEXT); Query OK, 0 rows affected (0.102 sec) -tidb> > ALTER TABLE t1 ADD COLUMN c1_hash BINARY(32) AS (UNHEX(SHA2(c1,256))); +tidb> ALTER TABLE t1 ADD COLUMN c1_hash BINARY(32) AS (UNHEX(SHA2(c1,256))); Query OK, 0 rows affected (0.242 sec) -tidb> > ALTER TABLE t1 ADD UNIQUE KEY (c1_hash); +tidb> ALTER TABLE t1 ADD UNIQUE KEY (c1_hash); Query OK, 0 rows affected (0.363 sec) -tidb> > INSERT INTO t1(id,c1) VALUES (1,'aaa'); +tidb> INSERT INTO t1(id,c1) VALUES (1,'aaa'); Query OK, 1 row affected (0.015 sec) -tidb> > INSERT INTO t1(id,c1) VALUES (2,'bbb'); +tidb> INSERT INTO t1(id,c1) VALUES (2,'bbb'); Query OK, 1 row affected (0.006 sec) -tidb> > INSERT INTO t1(id,c1) VALUES (3,'aaa'); +tidb> INSERT INTO t1(id,c1) VALUES (3,'aaa'); ERROR 1062 (23000): Duplicate entry '\x984\x87m\xCF\xB0\\xB1g\xA5\xC2IS\xEB\xA5\x8CJ\xC8\x9B\x1A\xDFW' for key 't1.c1_hash' -tidb> > +tidb> ``` ## Dump data with Dumpling and restore data with TiDB Lightning