GBK

Since v5.4.0, TiDB supports the GBK character set. This document provides the TiDB support and compatibility information of the GBK character set.

SHOW CHARACTER SET WHERE CHARSET = 'gbk';
+---------+-------------------------------------+-------------------+--------+
| Charset | Description                         | Default collation | Maxlen |
+---------+-------------------------------------+-------------------+--------+
| gbk     | Chinese Internal Code Specification | gbk_bin           |      2 |
+---------+-------------------------------------+-------------------+--------+
1 row in set (0.00 sec)

SHOW COLLATION WHERE CHARSET = 'gbk';
+----------------+---------+------+---------+----------+---------+
| Collation      | Charset | Id   | Default | Compiled | Sortlen |
+----------------+---------+------+---------+----------+---------+
| gbk_bin        | gbk     |   87 |         | Yes      |       1 |
+----------------+---------+------+---------+----------+---------+
1 rows in set (0.00 sec)

MySQL compatibility

This section provides the compatibility information between MySQL and TiDB.

Collations

The default collation of the GBK character set in MySQL is gbk_chinese_ci. Unlike MySQL, the default collation of the GBK character set in TiDB is gbk_bin. Additionally, because TiDB converts GBK to UTF8MB4 and then uses a binary collation, the gbk_bin collation in TiDB is not the same as the gbk_bin collation in MySQL.

To make TiDB compatible with the collations of MySQL GBK character set, when you first initialize the TiDB cluster, you need to set the TiDB option new_collations_enabled_on_first_bootstrap to true to enable the new framework for collations.

After enabling the new framework for collations, if you check the collations corresponding to the GBK character set, you can see that the TiDB GBK default collation is changed to gbk_chinese_ci.

SHOW CHARACTER SET WHERE CHARSET = 'gbk';
+---------+-------------------------------------+-------------------+--------+
| Charset | Description                         | Default collation | Maxlen |
+---------+-------------------------------------+-------------------+--------+
| gbk     | Chinese Internal Code Specification | gbk_chinese_ci    |      2 |
+---------+-------------------------------------+-------------------+--------+
1 row in set (0.00 sec)

SHOW COLLATION WHERE CHARSET = 'gbk';
+----------------+---------+------+---------+----------+---------+
| Collation      | Charset | Id   | Default | Compiled | Sortlen |
+----------------+---------+------+---------+----------+---------+
| gbk_bin        | gbk     |   87 |         | Yes      |       1 |
| gbk_chinese_ci | gbk     |   28 | Yes     | Yes      |       1 |
+----------------+---------+------+---------+----------+---------+
2 rows in set (0.00 sec)

Illegal character compatibility

• If the system variables character_set_client and character_set_connection are not set to gbk at the same time, TiDB handles illegal characters in the same way as MySQL.

• If character_set_client and character_set_connection are both set to gbk, TiDB handles illegal characters differently than MySQL.

  • MySQL handles illegal GBK character sets in reading and writing operations differently.
  • TiDB handles illegal GBK character sets in reading and writing operations in the same way. In the SQL strict mode, TiDB reports an error when either reading or writing illegal GBK characters. In the non-strict mode, TiDB replaces illegal GBK characters with ? when either reading or writing illegal GBK characters.

For example, after SET NAMES gbk, if you create a table using the CREATE TABLE gbk_table(a VARCHAR(32) CHARACTER SET gbk) statement in MySQL and TiDB respectively and then execute the SQL statements in the following table, you can see the detailed differences.

In the above table, the result of SELECT HEX('a'); in the utf8mb4 byte set is e4b88061.

Other MySQL compatibility

• Currently, TiDB does not support using the ALTER TABLE statement to convert other character set types to gbk or from gbk to other character set types.

• TiDB does not support the use of _gbk. For example:

  CREATE TABLE t(a CHAR(10) CHARSET BINARY);
  Query OK, 0 rows affected (0.00 sec)
  INSERT INTO t VALUES (_gbk'啊');
  ERROR 1115 (42000): Unsupported character introducer: 'gbk'
  

• Currently, for binary characters of the ENUM and SET types, TiDB deals with them as the utf8mb4 character set.

• In TiDB v7.5.0, if the predicates include LIKE for string prefixes, such as LIKE 'prefix%', and the target column is set to a GBK collation (either gbk_bin or gbk_chinese_ci), the optimizer currently cannot convert this predicate into a range scan. Instead, it performs a full scan. As a result, such SQL queries might lead to unexpected resource consumption. Starting from v7.5.1, this limitation is removed.

Component compatibility

• Currently, TiFlash does not support the GBK character set.

• TiDB Data Migration (DM) does not support migrating charset=GBK tables to TiDB clusters earlier than v5.4.0.

• TiDB Lightning does not support importing charset=GBK tables to TiDB clusters earlier than v5.4.0.

• TiCDC versions earlier than v6.1.0 do not support replicating charset=GBK tables. No version of TiCDC supports replicating charset=GBK tables to TiDB clusters earlier than v6.1.0.

• Backup & Restore (BR) versions earlier than v5.4.0 do not support recovering charset=GBK tables. No version of BR supports recovering charset=GBK tables to TiDB clusters earlier than v5.4.0.