|
| 1 | +# MySQL 9.x Innovation Series: Technical Migration Overview |
| 2 | + |
| 3 | +Upgrading to the MySQL 9.x Innovation Series introduces stronger security defaults, improved scalability, and continued modernization of server internals. At the same time, legacy authentication methods, plugins, and configuration patterns are removed or retired. |
| 4 | + |
| 5 | +This guide is intended for teams upgrading from MySQL 8.4 LTS to a Percona Server for MySQL release based on MySQL 9.x. It summarizes breaking changes, incompatible features, removed items, and new defaults that can affect compatibility, operations, and performance. |
| 6 | + |
| 7 | +Use this document to identify required pre-upgrade actions and to plan configuration and application changes before moving to MySQL 9.x. |
| 8 | + |
| 9 | +## Breaking and incompatible changes |
| 10 | + |
| 11 | +Before upgrading to MySQL 9.x, address the following high-impact changes first. |
| 12 | + • mysql_native_password authentication plugin removed |
| 13 | +All accounts and applications using mysql_native_password must be migrated to a supported authentication plugin (for example, caching_sha2_password) before upgrading, or authentication failures will occur. |
| 14 | + • gtid_mode and enforce_gtid_consistency default to ON |
| 15 | +Replication topologies that rely on file-based or position-based replication must be reviewed and explicitly configured, or replication may fail to start after the upgrade. |
| 16 | + • keyring_file plugin removed |
| 17 | +Servers configured to load the keyring_file plugin must migrate to a supported keyring component before upgrading, or the server may fail to start. |
| 18 | + |
| 19 | +Each section below explains what is affected, what to use instead, and what actions to take. |
| 20 | + |
| 21 | +## Authentication and user management (9.0) |
| 22 | + |
| 23 | +Impact |
| 24 | + • The mysql_native_password authentication plugin is removed as of MySQL 9.0.0. It was deprecated throughout MySQL 8.0. |
| 25 | + • Accounts configured to use mysql_native_password can no longer authenticate against a 9.x server. |
| 26 | + • Clients that do not support CLIENT_PLUGIN_AUTH are rejected. |
| 27 | + • The server options --mysql-native-password, --mysql-native-password-proxy-users, and the default_authentication_plugin system variable are removed. |
| 28 | + • The removal is on the 9.x server side only. Client-side libraries still support mysql_native_password for connecting to older (8.0 or 5.7) servers. |
| 29 | + |
| 30 | +Replacement |
| 31 | + • Use caching_sha2_password or another supported authentication plugin. |
| 32 | + • New user accounts already default to caching_sha2_password in MySQL 8.4 and later. |
| 33 | + |
| 34 | +Action |
| 35 | + • Identify all accounts and applications using mysql_native_password. |
| 36 | + • Migrate each account to a supported plugin before upgrading. |
| 37 | + |
| 38 | +Example: |
| 39 | + |
| 40 | +ALTER USER 'username'@'host.' |
| 41 | +IDENTIFIED WITH caching_sha2_password |
| 42 | +BY 'new_password'; |
| 43 | + |
| 44 | + • Remove all references to removed authentication options and variables from configuration files and scripts before upgrading. |
| 45 | + |
| 46 | + |
| 47 | +## GTID and replication defaults (9.0) |
| 48 | + |
| 49 | +For many environments, this is the largest breaking change: replication behavior depends on GTID settings. |
| 50 | + |
| 51 | +Impact |
| 52 | + • As of MySQL 9.0, gtid_mode defaults to ON. |
| 53 | + • enforce_gtid_consistency also defaults to ON. |
| 54 | + • Replication setups that are not GTID-based may fail to start if not explicitly configured. |
| 55 | + • enforce_gtid_consistency=ON disallows certain non-deterministic statements within transactions. |
| 56 | + • In some distributions, gtid_mode may default to ON with OFF_PERMISSIVE logic during the upgrade phase. Explicitly setting gtid_mode=OFF (and enforce_gtid_consistency=OFF) if you are not ready for GTID remains the safest best practice. |
| 57 | + |
| 58 | +Replacement |
| 59 | + • Either migrate to GTID-based replication or explicitly disable GTID before starting the upgraded server. |
| 60 | + |
| 61 | +Action |
| 62 | + • If you are not ready to migrate to GTID, set the following before upgrading: |
| 63 | + |
| 64 | +gtid_mode=OFF |
| 65 | +enforce_gtid_consistency=OFF |
| 66 | + |
| 67 | + • Review application SQL and stored programs for statements that are incompatible with enforce_gtid_consistency=ON. |
| 68 | + |
| 69 | + |
| 70 | +## --early-plugin-load removed (9.1) |
| 71 | + |
| 72 | +Impact |
| 73 | + • The --early-plugin-load server option is removed in MySQL 9.1. |
| 74 | + • If present in configuration files, the server may fail to start. |
| 75 | + |
| 76 | +Replacement |
| 77 | + • Use supported components and the component manifest mechanism (for example, mysqld.my). |
| 78 | + |
| 79 | +Action |
| 80 | + • Scan configuration files for --early-plugin-load and remove it before upgrading. |
| 81 | + • Migrate affected functionality to components where applicable. |
| 82 | + |
| 83 | +## mysql client parsing of \G and \C (9.1) |
| 84 | + |
| 85 | +Impact |
| 86 | + • The mysql client now recognizes \G (vertical output) and \C (clear) only at the end of a statement. |
| 87 | + • Scripts that embed these tokens mid-statement may fail or behave differently. |
| 88 | + |
| 89 | +Replacement |
| 90 | + • Use \G and \C only at statement boundaries. |
| 91 | + |
| 92 | +Action |
| 93 | + • Review scripts and automation that use mysql -e or batch input and correct any mid-statement usage. |
| 94 | + |
| 95 | + |
| 96 | +## CREATE DATABASE and DROP DATABASE atomic (9.1) |
| 97 | + |
| 98 | +Impact |
| 99 | + • CREATE DATABASE and DROP DATABASE are now atomic and crash-safe. |
| 100 | + • This is a behavior improvement and does not introduce incompatibilities for correct usage. |
| 101 | + |
| 102 | +Action |
| 103 | + • No action required. |
| 104 | + |
| 105 | +## `keyring_file` plugin removed (9.2) |
| 106 | + |
| 107 | +Migrating from the keyring_file plugin to the component_keyring_file component is not just a configuration change. The component uses a different configuration file format and must be set up via a component manifest. |
| 108 | + |
| 109 | +Impact |
| 110 | + • The keyring_file plugin binary is no longer included as of MySQL 9.2. |
| 111 | + • Configurations that attempt to load it will fail. |
| 112 | + |
| 113 | +Replacement |
| 114 | + • Use the component_keyring_file component for file-based keyring storage. |
| 115 | + • The component is configured via a JSON manifest (often named component_keyring_file.cnf or defined in the component manifest), not via the same options in my.cnf. You cannot simply change a line in my.cnf; you must add and configure the component through the manifest. |
| 116 | + |
| 117 | +Action |
| 118 | + • Initialize the component manifest and configure the component_keyring_file component before upgrading. |
| 119 | + • Migrate keyring data and configuration to the component using the manifest and the component’s required format. |
| 120 | + • Remove keyring_file plugin load directives from my.cnf (and any other config files) before upgrading. |
| 121 | + |
| 122 | +## `FLUSH PRIVILEGES` and related items deprecated (9.2) |
| 123 | + |
| 124 | +Impact |
| 125 | + • FLUSH PRIVILEGES is deprecated and produces warnings. |
| 126 | + • The FLUSH_PRIVILEGES privilege, mysqladmin flush-privileges, and mysqladmin reload are deprecated. |
| 127 | + |
| 128 | +Replacement |
| 129 | + • Use the recommended privilege-load behavior documented in the MySQL Reference Manual. |
| 130 | + |
| 131 | +Action |
| 132 | + • Update scripts, automation, and operational runbooks to remove or replace deprecated commands. |
| 133 | + |
| 134 | + |
| 135 | +## Version Tokens plugin removed (9.3) |
| 136 | + |
| 137 | +Impact |
| 138 | + • The Version Tokens plugin is deprecated in 9.2 and removed in 9.3. |
| 139 | + • Related functions, privileges, and system variables are removed. |
| 140 | + |
| 141 | +Replacement |
| 142 | + • No direct replacement. |
| 143 | + |
| 144 | +Action |
| 145 | + • Remove all usage of Version Tokens from configuration files and application code before upgrading. |
| 146 | + |
| 147 | +## Connection Control plugins deprecated (9.2) |
| 148 | + |
| 149 | +Impact |
| 150 | + • Both Connection Control plugins are deprecated and may be removed in a future release. |
| 151 | + |
| 152 | +Replacement |
| 153 | + • Use the Connection Control component (component_connection_control). |
| 154 | + |
| 155 | +Action |
| 156 | + • Migrate from plugins to the component and update any scripts or monitoring that reference deprecated tables or variables. |
| 157 | + |
| 158 | +## Replica parallel workers minimum (9.3) |
| 159 | + |
| 160 | +Impact |
| 161 | + • replica_parallel_workers can no longer be set to 0; the minimum allowed value is 1. |
| 162 | + • The default was already changed to 4 in MySQL 8.0.30 and later, so most modern configurations are unaffected unless they explicitly set 0 for single-threaded replica applier behavior. |
| 163 | + |
| 164 | +Replacement |
| 165 | + • Use replica_parallel_workers = 1 for single-threaded behavior (or leave default if you did not override it). |
| 166 | + |
| 167 | +Action |
| 168 | + • If you previously set replica_parallel_workers=0, update configuration to 1 (or remove the setting to use the default) before upgrading. |
| 169 | + |
| 170 | + |
| 171 | +## InnoDB variables removed (9.3) |
| 172 | + |
| 173 | +Impact |
| 174 | + |
| 175 | +The following InnoDB variables are removed: |
| 176 | + • innodb_log_file_size |
| 177 | + • innodb_log_files_in_group |
| 178 | + • innodb_undo_tablespaces |
| 179 | + |
| 180 | +Redo and undo configuration is handled using new mechanisms. |
| 181 | + |
| 182 | +Replacement |
| 183 | + |
| 184 | +Removed variable MySQL 9.x approach |
| 185 | +innodb_log_file_size innodb_redo_log_capacity |
| 186 | +innodb_log_files_in_group Managed automatically |
| 187 | +innodb_undo_tablespaces Automatic undo management |
| 188 | + |
| 189 | +Action |
| 190 | + • Remove variables from configuration files. |
| 191 | + • Review the current redo and undo configuration model in the MySQL Reference Manual. |
| 192 | + |
| 193 | + |
| 194 | +## IGNORE and scalar subqueries (9.0) |
| 195 | + |
| 196 | +Impact |
| 197 | + • IGNORE no longer suppresses errors caused by scalar subqueries returning more than one row. |
| 198 | + • Statements such as INSERT IGNORE, UPDATE IGNORE, or DELETE IGNORE may now fail. |
| 199 | + |
| 200 | +Replacement |
| 201 | + • Ensure scalar subqueries return at most one row. |
| 202 | + |
| 203 | +Action |
| 204 | + • Review the application SQL and stored code and correct affected statements. |
| 205 | + |
| 206 | + |
| 207 | +## Inline foreign keys enforced (9.0) |
| 208 | + |
| 209 | +Impact |
| 210 | + • Inline foreign key specifications that were previously parsed but ignored are now enforced. |
| 211 | + |
| 212 | +Action |
| 213 | + • Review schema definitions and generated DDL. |
| 214 | + • Correct any statements that relied on previously ignored syntax. |
| 215 | + |
| 216 | +## MD5() and SHA1() deprecated in SQL (9.4) |
| 217 | + |
| 218 | +This change affects the SQL functions MD5() and SHA1(). It often breaks legacy PHP or Java applications that offload hashing to the database. |
| 219 | + |
| 220 | +Impact |
| 221 | + • The SQL functions MD5() and SHA1() are deprecated as of MySQL 9.4. |
| 222 | + • They continue to work but may be removed in a future release. |
| 223 | + • Applications that call these functions from the database layer (for example, legacy PHP or Java code that performs hashing in SQL) are particularly affected and may need changes before or after upgrade. |
| 224 | + |
| 225 | +Replacement |
| 226 | + • Use the SQL function SHA2() or another supported hashing mechanism in the database, or move hashing to the application layer. |
| 227 | + |
| 228 | +Action |
| 229 | + • Audit application code, stored procedures, and triggers for use of MD5() and SHA1(), especially in legacy PHP or Java applications that offload hashing to the database. Plan a migration to SHA2() or application-side hashing. |
| 230 | + |
| 231 | + |
| 232 | +## Group Replication and replication variables removed (9.5) |
| 233 | + |
| 234 | +Impact |
| 235 | + • group_replication_allow_local_lower_version_join is removed. |
| 236 | + • replica_parallel_type and slave_parallel_type are removed. |
| 237 | + • The legacy semisynchronous replication plugins (semisync_master.so and semisync_slave.so) and their associated system and status variables (prefixed with rpl_semi_sync_) are removed in MySQL 9.5. Semisynchronous replication itself is not gone; only the old plugin-based implementation is removed. |
| 238 | + |
| 239 | +Replacement |
| 240 | + • Semisynchronous replication is now provided by the Semisynchronous Replication Source and Replica components. Migrate to these components to keep semisync behavior. |
| 241 | + |
| 242 | +Action |
| 243 | + • Remove the removed variables from configuration, monitoring, and automation. |
| 244 | + • Migrate to the Semisynchronous Replication Source and Replica components if you use semisync; update replication configuration to use the new components and supported mechanisms. |
| 245 | + |
| 246 | +## Defaults and tuning guidance |
| 247 | + |
| 248 | +Replication defaults (9.0) |
| 249 | + |
| 250 | +Variable New default Previous |
| 251 | +gtid_mode ON OFF |
| 252 | +enforce_gtid_consistency ON OFF |
| 253 | + |
| 254 | +## InnoDB and binary logging (9.5+) |
| 255 | + |
| 256 | + • innodb_log_writer_threads default now depends on: |
| 257 | + • Whether binary logging is enabled |
| 258 | + • Number of logical CPUs |
| 259 | + • binlog_transaction_dependency_history_size default increased from 25,000 to 1,000,000; maximum increased to 10,000,000. |
| 260 | + |
| 261 | +Existing explicit settings are preserved. |
| 262 | + |
| 263 | +## Pre-upgrade checklist |
| 264 | + |
| 265 | + • Remove all removed or deprecated variables, options, and plugins. |
| 266 | + • Validate authentication plugins and migrate off mysql_native_password. |
| 267 | + • Review replication topology and GTID strategy. |
| 268 | + • Review InnoDB redo and undo configuration. |
| 269 | + • Test upgrades, replication, and failover in staging before production. |
0 commit comments