From 34bc080515ca12975ab129d8e490bebd564b25a3 Mon Sep 17 00:00:00 2001 From: Garion Herman Date: Wed, 24 Feb 2021 15:38:55 +1300 Subject: [PATCH] DOCS Add guide on new MySQL collation to Server Reqs This was previously documented in the 4.7.0 changelog, but will be an ongoing concern for developers, so it makes sense to replicate in a more obvious place. --- .../00_Getting_Started/00_Server_Requirements.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/en/00_Getting_Started/00_Server_Requirements.md b/docs/en/00_Getting_Started/00_Server_Requirements.md index 6c51376ca..8b669793f 100644 --- a/docs/en/00_Getting_Started/00_Server_Requirements.md +++ b/docs/en/00_Getting_Started/00_Server_Requirements.md @@ -28,7 +28,20 @@ Use [phpinfo()](http://php.net/manual/en/function.phpinfo.php) to inspect your c * SQL Server ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/mssql), community supported) * SQLite ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/sqlite3), community supported) - ### Connection mode (sql_mode) when using MySQL server >=5.7.5 +### Default MySQL Collation + +In Silverstripe CMS Recipe 4.7 and later, new projects default to the `utf8mb4_unicode_ci` collation when running against MySQL, which offers better support for multi-byte characters such as emoji. However, this may cause issues related to Varchar fields exceeding the maximum indexable size: + +- MySQL 5.5 and lower cannot support indexes larger than 768 bytes (192 characters) +- MySQL 5.6 supports larger indexes (3072 bytes) if the `innodb_large_prefix` setting is enabled (but not by default) +- MySQL 5.7 and newer have `innodb_large_prefix` enabled by default +- MariaDB ~10.1 matches MySQL 5.6's behaviour, >10.2 matches 5.7's. + +You can rectify this issue by upgrading MySQL, enabling the `innodb_large_prefix` setting if available, or reducing the size of affected fields. If none of these solutions are currently suitable, you can remove the new collation configuration from `app/_config/mysite.yml` to default back to the previous default collation. + +Existing projects that upgrade to Recipe 4.7.0 will unintentionally adopt this configuration change. Recipe 4.7.1 and later are unaffected. See [the release notes](/changelogs/4.7.0/#default-mysql-collation-updated) for more information. + +### Connection mode (sql_mode) when using MySQL server >=5.7.5 In MySQL versions >=5.7.5, the `ANSI` sql_mode setting behaves differently and includes the `ONLY_FULL_GROUP_BY` setting. It is generally recommended to leave this setting as-is because it results in deterministic SQL. However, for some advanced cases, the sql_mode can be configured on the database connection via the configuration API (see `MySQLDatabase::$sql_mode` for more details.) This setting is only available in Silverstripe CMS 4.7 and later.