The Vitess Docs | Collations and Character sets

Collations and Character sets

MySQL is a Unicode-aware database, and as explained on the MySQL documentation, it supports using many different character sets to store textual data in databases, and many different collations which are used to compare and sort this textual data.

Likewise, Vitess is also Unicode-aware, and it supports the vast majority of the collations and charsets in the underlying MySQL server. On a basic level, this support means that Vitess handles gracefully textual Unicode columns and queries, and relays this information to MySQL clients without losing or corrupting the encoding of the data. On top of this, newer versions of Vitess are also capable of performing textual comparison and sorting operations in SQL queries directly on VTGate instances, greatly speeding up complex operations such as cross-shard joins.

Supported collations #

The collation environment (i.e. the set of support collations and charsets) of a Vitess cluster is defined by the MySQL server version flag (--mysql_server_version) provided to the VTGate and VTTablet instances in the cluster. Higher (newer) MySQL versions will enable built-in support for more collations.

The following table lists all of the supported collations in the current release of Vitess:

Legend
✅	Vitess has full support for this collation.
⚠️	The underlying MySQL (or compatible) database supports this collation, but Vitess does not.
❌	Neither Vitess nor the underlying MySQL database supports this collation.

Using collations that are not supported by Vitess but implemented in the underlying MySQL instance can lead to unpredictable behavior.

Collation	Charset	MySQL 8.0	MySQL 5.7	MySQL 5.6	MariaDB 10.3	MariaDB 10.2	MariaDB 10.1	MariaDB 10.0
big5_chinese_ci	big5	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
latin2_czech_cs	latin2	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
dec8_swedish_ci	dec8	✅	✅	✅	✅	✅	✅	✅
cp850_general_ci	cp850	✅	✅	✅	✅	✅	✅	✅
latin1_german1_ci	latin1	✅	✅	✅	✅	✅	✅	✅
hp8_english_ci	hp8	✅	✅	✅	✅	✅	✅	✅
koi8r_general_ci	koi8r	✅	✅	✅	✅	✅	✅	✅
latin1_swedish_ci	latin1	✅	✅	✅	✅	✅	✅	✅
latin2_general_ci	latin2	✅	✅	✅	✅	✅	✅	✅
swe7_swedish_ci	swe7	✅	✅	✅	✅	✅	✅	✅
ascii_general_ci	ascii	✅	✅	✅	✅	✅	✅	✅
ujis_japanese_ci	ujis	✅	✅	✅	✅	✅	✅	✅
sjis_japanese_ci	sjis	✅	✅	✅	✅	✅	✅	✅
cp1251_bulgarian_ci	cp1251	✅	✅	✅	✅	✅	✅	✅
latin1_danish_ci	latin1	✅	✅	✅	✅	✅	✅	✅
hebrew_general_ci	hebrew	✅	✅	✅	✅	✅	✅	✅
tis620_thai_ci	tis620	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
euckr_korean_ci	euckr	✅	✅	✅	✅	✅	✅	✅
latin7_estonian_cs	latin7	✅	✅	✅	✅	✅	✅	✅
latin2_hungarian_ci	latin2	✅	✅	✅	✅	✅	✅	✅
koi8u_general_ci	koi8u	✅	✅	✅	✅	✅	✅	✅
cp1251_ukrainian_ci	cp1251	✅	✅	✅	✅	✅	✅	✅
gb2312_chinese_ci	gb2312	✅	✅	✅	✅	✅	✅	✅
greek_general_ci	greek	✅	✅	✅	✅	✅	✅	✅
cp1250_general_ci	cp1250	✅	✅	✅	✅	✅	✅	✅
latin2_croatian_ci	latin2	✅	✅	✅	✅	✅	✅	✅
gbk_chinese_ci	gbk	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
cp1257_lithuanian_ci	cp1257	✅	✅	✅	✅	✅	✅	✅
latin5_turkish_ci	latin5	✅	✅	✅	✅	✅	✅	✅
latin1_german2_ci	latin1	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
armscii8_general_ci	armscii8	✅	✅	✅	✅	✅	✅	✅
utf8_general_ci	utf8	✅	✅	✅	✅	✅	✅	✅
cp1250_czech_cs	cp1250	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
ucs2_general_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
cp866_general_ci	cp866	✅	✅	✅	✅	✅	✅	✅
keybcs2_general_ci	keybcs2	✅	✅	✅	✅	✅	✅	✅
macce_general_ci	macce	✅	✅	✅	✅	✅	✅	✅
macroman_general_ci	macroman	✅	✅	✅	✅	✅	✅	✅
cp852_general_ci	cp852	✅	✅	✅	✅	✅	✅	✅
latin7_general_ci	latin7	✅	✅	✅	✅	✅	✅	✅
latin7_general_cs	latin7	✅	✅	✅	✅	✅	✅	✅
macce_bin	macce	✅	✅	✅	✅	✅	✅	✅
cp1250_croatian_ci	cp1250	✅	✅	✅	✅	✅	✅	✅
utf8mb4_general_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_bin	utf8mb4	✅	✅	✅	✅	✅	✅	✅
latin1_bin	latin1	✅	✅	✅	✅	✅	✅	✅
latin1_general_ci	latin1	✅	✅	✅	✅	✅	✅	✅
latin1_general_cs	latin1	✅	✅	✅	✅	✅	✅	✅
cp1251_bin	cp1251	✅	✅	✅	✅	✅	✅	✅
cp1251_general_ci	cp1251	✅	✅	✅	✅	✅	✅	✅
cp1251_general_cs	cp1251	✅	✅	✅	✅	✅	✅	✅
macroman_bin	macroman	✅	✅	✅	✅	✅	✅	✅
utf16_general_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_bin	utf16	✅	✅	✅	✅	✅	✅	✅
utf16le_general_ci	utf16le	✅	✅	✅	✅	✅	✅	✅
cp1256_general_ci	cp1256	✅	✅	✅	✅	✅	✅	✅
cp1257_bin	cp1257	✅	✅	✅	✅	✅	✅	✅
cp1257_general_ci	cp1257	✅	✅	✅	✅	✅	✅	✅
utf32_general_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_bin	utf32	✅	✅	✅	✅	✅	✅	✅
utf16le_bin	utf16le	✅	✅	✅	✅	✅	✅	✅
binary	binary	✅	✅	✅	✅	✅	✅	✅
armscii8_bin	armscii8	✅	✅	✅	✅	✅	✅	✅
ascii_bin	ascii	✅	✅	✅	✅	✅	✅	✅
cp1250_bin	cp1250	✅	✅	✅	✅	✅	✅	✅
cp1256_bin	cp1256	✅	✅	✅	✅	✅	✅	✅
cp866_bin	cp866	✅	✅	✅	✅	✅	✅	✅
dec8_bin	dec8	✅	✅	✅	✅	✅	✅	✅
greek_bin	greek	✅	✅	✅	✅	✅	✅	✅
hebrew_bin	hebrew	✅	✅	✅	✅	✅	✅	✅
hp8_bin	hp8	✅	✅	✅	✅	✅	✅	✅
keybcs2_bin	keybcs2	✅	✅	✅	✅	✅	✅	✅
koi8r_bin	koi8r	✅	✅	✅	✅	✅	✅	✅
koi8u_bin	koi8u	✅	✅	✅	✅	✅	✅	✅
utf8_tolower_ci	utf8	⚠️	❌	❌	❌	❌	❌	❌
latin2_bin	latin2	✅	✅	✅	✅	✅	✅	✅
latin5_bin	latin5	✅	✅	✅	✅	✅	✅	✅
latin7_bin	latin7	✅	✅	✅	✅	✅	✅	✅
cp850_bin	cp850	✅	✅	✅	✅	✅	✅	✅
cp852_bin	cp852	✅	✅	✅	✅	✅	✅	✅
swe7_bin	swe7	✅	✅	✅	✅	✅	✅	✅
utf8_bin	utf8	✅	✅	✅	✅	✅	✅	✅
big5_bin	big5	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
euckr_bin	euckr	✅	✅	✅	✅	✅	✅	✅
gb2312_bin	gb2312	✅	✅	✅	✅	✅	✅	✅
gbk_bin	gbk	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
sjis_bin	sjis	✅	✅	✅	✅	✅	✅	✅
tis620_bin	tis620	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
ucs2_bin	ucs2	✅	✅	✅	✅	✅	✅	✅
ujis_bin	ujis	✅	✅	✅	✅	✅	✅	✅
geostd8_general_ci	geostd8	✅	✅	✅	✅	✅	✅	✅
geostd8_bin	geostd8	✅	✅	✅	✅	✅	✅	✅
latin1_spanish_ci	latin1	✅	✅	✅	✅	✅	✅	✅
cp932_japanese_ci	cp932	✅	✅	✅	✅	✅	✅	✅
cp932_bin	cp932	✅	✅	✅	✅	✅	✅	✅
eucjpms_japanese_ci	eucjpms	✅	✅	✅	✅	✅	✅	✅
eucjpms_bin	eucjpms	✅	✅	✅	✅	✅	✅	✅
cp1250_polish_ci	cp1250	✅	✅	✅	✅	✅	✅	✅
utf16_unicode_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_icelandic_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_latvian_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_romanian_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_slovenian_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_polish_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_estonian_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_spanish_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_swedish_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_turkish_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_czech_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_danish_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_lithuanian_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_slovak_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_spanish2_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_roman_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_persian_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_esperanto_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_hungarian_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_sinhala_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_german2_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_croatian_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_unicode_520_ci	utf16	✅	✅	✅	✅	✅	✅	✅
utf16_vietnamese_ci	utf16	✅	✅	✅	✅	✅	✅	✅
ucs2_unicode_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_icelandic_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_latvian_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_romanian_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_slovenian_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_polish_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_estonian_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_spanish_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_swedish_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_turkish_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_czech_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_danish_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_lithuanian_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_slovak_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_spanish2_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_roman_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_persian_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_esperanto_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_hungarian_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_sinhala_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_german2_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_croatian_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_unicode_520_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_vietnamese_ci	ucs2	✅	✅	✅	✅	✅	✅	✅
ucs2_general_mysql500_ci	ucs2	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
utf32_unicode_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_icelandic_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_latvian_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_romanian_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_slovenian_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_polish_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_estonian_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_spanish_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_swedish_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_turkish_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_czech_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_danish_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_lithuanian_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_slovak_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_spanish2_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_roman_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_persian_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_esperanto_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_hungarian_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_sinhala_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_german2_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_croatian_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_unicode_520_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf32_vietnamese_ci	utf32	✅	✅	✅	✅	✅	✅	✅
utf8_unicode_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_icelandic_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_latvian_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_romanian_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_slovenian_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_polish_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_estonian_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_spanish_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_swedish_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_turkish_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_czech_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_danish_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_lithuanian_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_slovak_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_spanish2_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_roman_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_persian_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_esperanto_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_hungarian_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_sinhala_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_german2_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_croatian_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_unicode_520_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_vietnamese_ci	utf8	✅	✅	✅	✅	✅	✅	✅
utf8_general_mysql500_ci	utf8	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
utf8mb4_unicode_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_icelandic_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_latvian_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_romanian_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_slovenian_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_polish_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_estonian_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_spanish_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_swedish_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_turkish_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_czech_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_danish_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_lithuanian_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_slovak_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_spanish2_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_roman_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_persian_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_esperanto_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_hungarian_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_sinhala_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_german2_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_croatian_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_unicode_520_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
utf8mb4_vietnamese_ci	utf8mb4	✅	✅	✅	✅	✅	✅	✅
gb18030_chinese_ci	gb18030	⚠️	⚠️	❌	❌	❌	❌	❌
gb18030_bin	gb18030	⚠️	⚠️	❌	❌	❌	❌	❌
gb18030_unicode_520_ci	gb18030	✅	✅	❌	❌	❌	❌	❌
utf8mb4_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_de_pb_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_is_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_lv_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_ro_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_sl_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_pl_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_et_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_es_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_sv_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_tr_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_cs_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_da_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_lt_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_sk_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_es_trad_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_la_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_eo_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_hu_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_hr_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_vi_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_de_pb_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_is_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_lv_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_ro_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_sl_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_pl_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_et_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_es_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_sv_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_tr_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_cs_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_da_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_lt_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_sk_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_es_trad_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_la_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_eo_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_hu_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_hr_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_vi_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_ja_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_ja_0900_as_cs_ks	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_0900_as_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_ru_0900_ai_ci	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_ru_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_zh_0900_as_cs	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8mb4_0900_bin	utf8mb4	✅	❌	❌	❌	❌	❌	❌
utf8_croatian_ci	utf8	❌	❌	❌	⚠️	⚠️	⚠️	⚠️
utf8_myanmar_ci	utf8	❌	❌	❌	⚠️	⚠️	⚠️	⚠️
utf8_thai_520_w2	utf8	❌	❌	❌	⚠️	⚠️	⚠️	❌
utf8mb4_croatian_ci	utf8mb4	❌	❌	❌	⚠️	⚠️	⚠️	⚠️
utf8mb4_myanmar_ci	utf8mb4	❌	❌	❌	⚠️	⚠️	⚠️	⚠️
utf8mb4_thai_520_w2	utf8mb4	❌	❌	❌	⚠️	⚠️	⚠️	❌
ucs2_croatian_ci	ucs2	❌	❌	❌	⚠️	⚠️	⚠️	⚠️
ucs2_myanmar_ci	ucs2	❌	❌	❌	⚠️	⚠️	⚠️	⚠️
ucs2_thai_520_w2	ucs2	❌	❌	❌	⚠️	⚠️	⚠️	❌
utf16_croatian_ci	utf16	❌	❌	❌	⚠️	⚠️	⚠️	⚠️
utf16_myanmar_ci	utf16	❌	❌	❌	⚠️	⚠️	⚠️	⚠️
utf16_thai_520_w2	utf16	❌	❌	❌	⚠️	⚠️	⚠️	❌
utf32_croatian_ci	utf32	❌	❌	❌	⚠️	⚠️	⚠️	⚠️
utf32_myanmar_ci	utf32	❌	❌	❌	⚠️	⚠️	⚠️	⚠️
utf32_thai_520_w2	utf32	❌	❌	❌	⚠️	⚠️	⚠️	❌
big5_chinese_nopad_ci	big5	❌	❌	❌	⚠️	⚠️	❌	❌
dec8_swedish_nopad_ci	dec8	❌	❌	❌	⚠️	⚠️	❌	❌
cp850_general_nopad_ci	cp850	❌	❌	❌	⚠️	⚠️	❌	❌
hp8_english_nopad_ci	hp8	❌	❌	❌	⚠️	⚠️	❌	❌
koi8r_general_nopad_ci	koi8r	❌	❌	❌	⚠️	⚠️	❌	❌
latin1_swedish_nopad_ci	latin1	❌	❌	❌	⚠️	⚠️	❌	❌
latin2_general_nopad_ci	latin2	❌	❌	❌	⚠️	⚠️	❌	❌
swe7_swedish_nopad_ci	swe7	❌	❌	❌	⚠️	⚠️	❌	❌
ascii_general_nopad_ci	ascii	❌	❌	❌	⚠️	⚠️	❌	❌
ujis_japanese_nopad_ci	ujis	❌	❌	❌	⚠️	⚠️	❌	❌
sjis_japanese_nopad_ci	sjis	❌	❌	❌	⚠️	⚠️	❌	❌
hebrew_general_nopad_ci	hebrew	❌	❌	❌	⚠️	⚠️	❌	❌
tis620_thai_nopad_ci	tis620	❌	❌	❌	⚠️	⚠️	❌	❌
euckr_korean_nopad_ci	euckr	❌	❌	❌	⚠️	⚠️	❌	❌
koi8u_general_nopad_ci	koi8u	❌	❌	❌	⚠️	⚠️	❌	❌
gb2312_chinese_nopad_ci	gb2312	❌	❌	❌	⚠️	⚠️	❌	❌
greek_general_nopad_ci	greek	❌	❌	❌	⚠️	⚠️	❌	❌
cp1250_general_nopad_ci	cp1250	❌	❌	❌	⚠️	⚠️	❌	❌
gbk_chinese_nopad_ci	gbk	❌	❌	❌	⚠️	⚠️	❌	❌
latin5_turkish_nopad_ci	latin5	❌	❌	❌	⚠️	⚠️	❌	❌
armscii8_general_nopad_ci	armscii8	❌	❌	❌	⚠️	⚠️	❌	❌
utf8_general_nopad_ci	utf8	❌	❌	❌	⚠️	⚠️	❌	❌
ucs2_general_nopad_ci	ucs2	❌	❌	❌	⚠️	⚠️	❌	❌
cp866_general_nopad_ci	cp866	❌	❌	❌	⚠️	⚠️	❌	❌
keybcs2_general_nopad_ci	keybcs2	❌	❌	❌	⚠️	⚠️	❌	❌
macce_general_nopad_ci	macce	❌	❌	❌	⚠️	⚠️	❌	❌
macroman_general_nopad_ci	macroman	❌	❌	❌	⚠️	⚠️	❌	❌
cp852_general_nopad_ci	cp852	❌	❌	❌	⚠️	⚠️	❌	❌
latin7_general_nopad_ci	latin7	❌	❌	❌	⚠️	⚠️	❌	❌
macce_nopad_bin	macce	❌	❌	❌	⚠️	⚠️	❌	❌
utf8mb4_general_nopad_ci	utf8mb4	❌	❌	❌	⚠️	⚠️	❌	❌
utf8mb4_nopad_bin	utf8mb4	❌	❌	❌	⚠️	⚠️	❌	❌
latin1_nopad_bin	latin1	❌	❌	❌	⚠️	⚠️	❌	❌
cp1251_nopad_bin	cp1251	❌	❌	❌	⚠️	⚠️	❌	❌
cp1251_general_nopad_ci	cp1251	❌	❌	❌	⚠️	⚠️	❌	❌
macroman_nopad_bin	macroman	❌	❌	❌	⚠️	⚠️	❌	❌
utf16_general_nopad_ci	utf16	❌	❌	❌	⚠️	⚠️	❌	❌
utf16_nopad_bin	utf16	❌	❌	❌	⚠️	⚠️	❌	❌
utf16le_general_nopad_ci	utf16le	❌	❌	❌	⚠️	⚠️	❌	❌
cp1256_general_nopad_ci	cp1256	❌	❌	❌	⚠️	⚠️	❌	❌
cp1257_nopad_bin	cp1257	❌	❌	❌	⚠️	⚠️	❌	❌
cp1257_general_nopad_ci	cp1257	❌	❌	❌	⚠️	⚠️	❌	❌
utf32_general_nopad_ci	utf32	❌	❌	❌	⚠️	⚠️	❌	❌
utf32_nopad_bin	utf32	❌	❌	❌	⚠️	⚠️	❌	❌
utf16le_nopad_bin	utf16le	❌	❌	❌	⚠️	⚠️	❌	❌
armscii8_nopad_bin	armscii8	❌	❌	❌	⚠️	⚠️	❌	❌
ascii_nopad_bin	ascii	❌	❌	❌	⚠️	⚠️	❌	❌
cp1250_nopad_bin	cp1250	❌	❌	❌	⚠️	⚠️	❌	❌
cp1256_nopad_bin	cp1256	❌	❌	❌	⚠️	⚠️	❌	❌
cp866_nopad_bin	cp866	❌	❌	❌	⚠️	⚠️	❌	❌
dec8_nopad_bin	dec8	❌	❌	❌	⚠️	⚠️	❌	❌
greek_nopad_bin	greek	❌	❌	❌	⚠️	⚠️	❌	❌
hebrew_nopad_bin	hebrew	❌	❌	❌	⚠️	⚠️	❌	❌
hp8_nopad_bin	hp8	❌	❌	❌	⚠️	⚠️	❌	❌
keybcs2_nopad_bin	keybcs2	❌	❌	❌	⚠️	⚠️	❌	❌
koi8r_nopad_bin	koi8r	❌	❌	❌	⚠️	⚠️	❌	❌
koi8u_nopad_bin	koi8u	❌	❌	❌	⚠️	⚠️	❌	❌
latin2_nopad_bin	latin2	❌	❌	❌	⚠️	⚠️	❌	❌
latin5_nopad_bin	latin5	❌	❌	❌	⚠️	⚠️	❌	❌
latin7_nopad_bin	latin7	❌	❌	❌	⚠️	⚠️	❌	❌
cp850_nopad_bin	cp850	❌	❌	❌	⚠️	⚠️	❌	❌
cp852_nopad_bin	cp852	❌	❌	❌	⚠️	⚠️	❌	❌
swe7_nopad_bin	swe7	❌	❌	❌	⚠️	⚠️	❌	❌
utf8_nopad_bin	utf8	❌	❌	❌	⚠️	⚠️	❌	❌
big5_nopad_bin	big5	❌	❌	❌	⚠️	⚠️	❌	❌
euckr_nopad_bin	euckr	❌	❌	❌	⚠️	⚠️	❌	❌
gb2312_nopad_bin	gb2312	❌	❌	❌	⚠️	⚠️	❌	❌
gbk_nopad_bin	gbk	❌	❌	❌	⚠️	⚠️	❌	❌
sjis_nopad_bin	sjis	❌	❌	❌	⚠️	⚠️	❌	❌
tis620_nopad_bin	tis620	❌	❌	❌	⚠️	⚠️	❌	❌
ucs2_nopad_bin	ucs2	❌	❌	❌	⚠️	⚠️	❌	❌
ujis_nopad_bin	ujis	❌	❌	❌	⚠️	⚠️	❌	❌
geostd8_general_nopad_ci	geostd8	❌	❌	❌	⚠️	⚠️	❌	❌
geostd8_nopad_bin	geostd8	❌	❌	❌	⚠️	⚠️	❌	❌
cp932_japanese_nopad_ci	cp932	❌	❌	❌	⚠️	⚠️	❌	❌
cp932_nopad_bin	cp932	❌	❌	❌	⚠️	⚠️	❌	❌
eucjpms_japanese_nopad_ci	eucjpms	❌	❌	❌	⚠️	⚠️	❌	❌
eucjpms_nopad_bin	eucjpms	❌	❌	❌	⚠️	⚠️	❌	❌
utf16_unicode_nopad_ci	utf16	❌	❌	❌	⚠️	⚠️	❌	❌
utf16_unicode_520_nopad_ci	utf16	❌	❌	❌	⚠️	⚠️	❌	❌
ucs2_unicode_nopad_ci	ucs2	❌	❌	❌	⚠️	⚠️	❌	❌
ucs2_unicode_520_nopad_ci	ucs2	❌	❌	❌	⚠️	⚠️	❌	❌
utf32_unicode_nopad_ci	utf32	❌	❌	❌	⚠️	⚠️	❌	❌
utf32_unicode_520_nopad_ci	utf32	❌	❌	❌	⚠️	⚠️	❌	❌
utf8_unicode_nopad_ci	utf8	❌	❌	❌	⚠️	⚠️	❌	❌
utf8_unicode_520_nopad_ci	utf8	❌	❌	❌	⚠️	⚠️	❌	❌
utf8mb4_unicode_nopad_ci	utf8mb4	❌	❌	❌	⚠️	⚠️	❌	❌
utf8mb4_unicode_520_nopad_ci	utf8mb4	❌	❌	❌	⚠️	⚠️	❌	❌

Configuring the default connection charset for a Vitess cluster #

The default connection charset for a Vitess cluster is configured in your VTTablet instances via the --db_charset flag. This flag modifies the behavior of the connections that the tablet creates, not the underlying MySQL instance: it defines the charset that VTTablet uses when opening connections to MySQL. If the --db_charset flag is left empty, VTTablet will default to an utf8mb4 charset based on the underlying MySQL version. For instance, MySQL 5.x will default to utf8mb4_general_ci, while MySQL 8.x defaults to utf8mb4_0900_ai_ci. Because the handshake packet of MySQL leaves only 1 byte to reference the charset ID, only charset IDs <= 255 are supported.

The @character_set_client of a VTTablet is automatically propagated to all the VTGates that connect to it, and hence to all the MySQL clients connected to the VTGates. It is a configuration error to deploy several VTTablets in the same Vitess cluster with different connection charset: it will cause warning messages in the VTGates and lead to inconsistent behaviors.

The @character_set_client of a Vitess cluster is constant: it cannot be changed at runtime via SQL (e.g. by issuing a SET character_set_client = utf8 statement). VTGates will reject such queries.

Do note that, as the MySQL documentation explains, the @character_set_client setting only applies when performing character comparisons in SQL queries that don't have explicit collation information. For instance, a query such as SELECT 'foo' = 'FOO' will use the default @character_set_client for the cluster when picking the charset and collation for the two string literals, because these literals contain no explicit charset or collation information. A query such as SELECT c FROM t WHERE c = 'foo' will not use the @character_set_client; it will use the charset and collation that was defined for column c when creating table t.

Vitess has extensive support for creating collation-aware tables and columns in your SQL database, using any charset, and performing collation-aware operations in SQL queries. Any of the supported collations and charsets in Vitess can be used when declaring a table or a row in your database -- it does not need to match the specific value of @character_set_client. Generally speaking, setting @character_set_client to a charset not based on utf8mb4 is a mistake. We strongly encourage you to leave the --db_charset flag to its default value.

Planning >>