[!!!][TASK] Remove deprecated code from TableController
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 9.5 / Feature-80398-Utf8mb4OnMysqlByDefaultForNewInstances.rst
1 .. include:: ../../Includes.txt
2
3 ===============================================================
4 Feature: #80398 - utf8mb4 on mysql by default for new instances
5 ===============================================================
6
7 See :issue:`80398`
8
9 Description
10 ===========
11
12 New instances created by the TYPO3 installer now set `utf8mb4` as charset and `utf8mb4_unicode_ci`
13 collation by default for instances running on MySQL. This allows 4 byte unicode characters
14 like emojis in MySQL.
15
16 If upgrading instances, admins may change :file:`LocalConfiguration.php` to use this feature.
17 The core does not provide mechanisms to update the collation of existing tables
18 from `utf8_unicode_ci` to `utf8mb4_unicode_ci` for existing instances, though. Admins need
19 to manage that on their own if needed, the reports module shows an information if the
20 table schema uses mixed collations. This should be fixed after manually configuring
21 `utf8mb4` to avoid SQL errors when joining tables having different collations.
22
23 Also note that manually upgrading to `utf8mb4` may lead to index length issues: The maximum key
24 length on InnoDB tables is often 767 bytes and options to increase that have even been actively
25 removed, for instance in recent MariaDB versions.
26 A typical case is an index on a varchar(255) field: The DBMS assumes the worst case for the index
27 length, which is 3 bytes per character for a utf8 (utf8mb3), but 4 bytes for utf8mb4: With utf8,
28 the maximum index length is 3*255 + 1 = 766 bytes which fits into 767, but with utf8mb4, this
29 is 4*255 + 1 = 1021 bytes, which exceeds the maximum length and leads to SQL errors when setting
30 such an index.
31 This scenario gets more complex with combined indexes and may need manual investigation when
32 upgrading an existing instance from from `utf8` to `utf8mb4`. One solution is to restrict the
33 index length in ext_tables.sql of the affected extension: :php:`KEY myKey (myField(191))`, which
34 in this case leads to 4*191 + 1 = 764 bytes as maximum used length.
35
36 The basic settings to use `utf8mb4` in :file:`LocalConfiguration.php` are:
37
38 .. code-block:: php
39
40 'DB' => [
41 'Connections' => [
42 'Default' => [
43 'driver' => 'mysqli',
44 ...
45 'charset' => 'utf8mb4',
46 'tableoptions' => [
47 'charset' => 'utf8mb4',
48 'collate' => 'utf8mb4_unicode_ci',
49 ],
50 ],
51 ],
52 ],
53
54
55 Impact
56 ======
57
58 `utf8mb4` is an allowed charset and `utf8mb4_unicode_ci` is an allowed collation and
59 used by default for new instances running on MySQL.
60
61 .. index:: PHP-API, LocalConfiguration, Database