Version 3.0.0

MySQL defaults change to utf8mb4 and an in-place converter with verification is included for existing databases. Existing table definitions and Bitrix connection settings are not changed automatically. Read the upgrade notes before pulling.

Why a major version

config/mysql/my.cnf now sets character_set_server=utf8mb4, collation_server=utf8mb4_unicode_ci and default_character_set = utf8mb4 for the client. These are defaults: databases created without an explicit charset get utf8mb4 once the container reads the new file, and the mysql client and mysqldump read data as utf8mb4. The backup, restore and dev renewal scripts ask for utf8mb4 themselves, so they change right after the pull, independently of the restart or of any table conversion. Storing 4-byte characters (emoji, some CJK and mathematical symbols) still needs the conversion below.

Database conversion

• scripts/convert-utf8mb4.sh DATABASE converts a database in place with one ALTER TABLE per table that needs it, generated from information_schema. Each character column outside both the selected collation and utf8mb4_bin is rewritten with its own type, nullability, default and comment; *_bin columns become utf8mb4_bin, all others utf8mb4_unicode_ci (or --collation utf8mb4_0900_ai_ci, the MySQL 8 default that fresh Bitrix installs use). A plain CONVERT TO CHARACTER SET would widen TEXT to MEDIUMTEXT and turn binary collations into the table collation, which breaks unique keys such as b_search_stem.STEM.
• Before and after the run the script writes a column snapshot and a per-table fingerprint (row count and folded MD5 of every row) under logs/utf8mb4/ and exits non-zero when a definition changed beyond charset and collation or a fingerprint differs. A table the application wrote to during the run shows up as a fingerprint difference too, so stop everything that writes first.
• The run stops before changing anything on: generated or invisible columns that still need conversion, foreign keys on character columns, VARCHAR longer than 16383 characters, line breaks in a default, type or comment, backticks or control characters in table or column names, views, non-InnoDB tables, and NO_BACKSLASH_ESCAPES in the global sql_mode.
• --dry-run writes the statements without executing them. A run that stops halfway can be repeated; the retry does not check against the failed run's snapshots, so inspect that run's diff files before retrying.

Bitrix settings

The Readme section "Converting the database to utf8mb4" lists the connection settings that go with the conversion: 'charset' => 'utf8mb4' and 'utf8mb4' => array('global' => true) in bitrix/.settings.php, and bitrix/php_interface/after_connect_d7.php with SET NAMES 'utf8mb4' COLLATE '...' naming the collation the tables were converted to; Bitrix includes that file on every connection by default and its install wizard creates it on fresh installs.

Dev renewal

• scripts/renew-dev.sh publishes the dev DB connection files only after the dump is restored; until then the dev site has no database access. Before, requests during the restore hit an empty database and Bitrix cached the empty event handler list, an entry with no expiry, so dev answered 500 until that cache was cleaned by hand. The generated files wait in a root-only temporary directory and the dev tree never holds production credentials.
• Open sessions of the dev user are closed on a best-effort basis before the database is recreated (DROP USER leaves them alive, and php-fpm keeps persistent connections), the dev database takes the charset and collation of the production one, and after the file sync the script cleans the dev managed and file caches through the Bitrix API and removes the dev host's composite page directory. When prod and dev share a cache backend, dev needs its own sid in .settings_extra.php, otherwise this cleanup also hits production entries.

Upgrade notes

1. config/mysql/my.cnf is a file-level bind mount, so the container keeps reading the old inode after the pull. docker restart --timeout 120 mysql makes it read the new file; that is a database interruption, and the timeout gives mysqld time to shut down cleanly instead of the 10-second default.
2. To convert an existing database: take a backup, stop the site and php-cron, run sudo ./scripts/convert-utf8mb4.sh --dry-run DATABASE and then without --dry-run, add the Bitrix settings from the Readme, reload php-fpm, start php-cron and reopen the site. The released script converted a 1.35 GB Bitrix database of 744 tables in about three minutes of ALTER; the window also holds the two fingerprint passes and the application checks, so rehearse on a restored copy to size it.
3. Existing databases are not converted automatically. New databases created without an explicit charset or collation use the new server defaults; renew-dev.sh creates dev with the production database's charset and collation.