Upgrading MySQL is often seen as straightforward — install the new binaries, restart, done. In reality, it’s more like upgrading a production jet engine mid-flight. Small changes in defaults, deprecated settings, or old privileges can lead to surprises you don’t want at 2:00 AM on maintenance night. Or even worse, see your performance deteriorating during the peak of business activity.
Fortunately, MySQL Shell ships with a utility to help validate whether your server is actually ready before you pull the trigger: util.checkForServerUpgrade().
In this post, we’ll walk you through the installation of MySQL Shell and running the upgrade checker.
Installing MySQL Shell
If you don’t already have MySQL Shell available on your server, install it first. Packages are available at:
https://dev.mysql.com/downloads/shell/
On RHEL-based systems, you can just download and install the RPM:
|
1 |
yum install https://dev.mysql.com/get/Downloads/MySQL-Shell/mysql-shell-8.4.4-1.el9.x86_64.rpm |
If your MySQL repo is already configured:
|
1 |
yum install mysql-shell |
Nothing fancy here — just a standard installation. You can also install MySQL Shell using the Percona repositories.
Running the Upgrade Checker
With MySQL Shell installed, we can start validating our server. The checker looks at things like:
-
Deprecated features and settings
-
Schema definitions that won’t be compatible
-
Privileges that will disappear
-
System variables with new defaults
-
Storage engine checks
-
Authentication method changes
To run it, connect and run the util.checkForServerUpgrade() helper. Here are a few common examples.
Standard Syntax
|
1 |
mysqlsh -- util checkForServerUpgrade root@localhost:3306 --target-version=8.0.40 --config-path=/etc/percona-server.conf.d/mysqld.cnf |
Or with flags:
|
1 |
mysqlsh -- util check-for-server-upgrade --user=root --host=localhost --port=3306 --target-version=8.0.40 --config-path=/etc/percona-server.conf.d/mysqld.cnf |
Or inline:
|
1 |
mysqlsh -e "util.checkForServerUpgrade('root@localhost:3306', {'targetVersion':'8.0.40','configPath':'/etc/percona-server.conf.d/mysqld.cnf'})" |
If your environment prefers sockets — often the case for local admin checks — here’s an example:
|
1 2 3 4 5 6 7 8 |
MySQL localhost JS > util.checkForServerUpgrade( 'root@localhost?socket=(/mysql/data/mysqld.sock)', { "password":"msandbox", "targetVersion":"8.0.40", "configPath":"/etc/mysql/conf.d/mysqld.cnf" } ) |
Note: Your target version must be ≤ the version of MySQL Shell you’re using. If you’re checking for 8.0.40, use Shell 8.0.40 or newer.
Example Output
Running the checker generates a report that summarizes issues and their severity. A typical result looks like:
|
1 2 3 4 5 |
Errors: 6 Warnings: 397 Notices: 2 ERROR: 6 errors were found. Please correct these issues before upgrading to avoid compatibility issues. |
And an example of a warning:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
22) New default authentication plugin considerations (defaultAuthenticationPlugin) Warning: The default authentication plugin 'caching_sha2_password' offers more secure password hashing than previously used 'mysql_native_password' (and consequent improved client connection authentication). However, it also has compatibility implications that may affect existing MySQL installations. If your MySQL installation must serve pre-8.0 clients and you encounter compatibility issues after upgrading, the simplest way to address those issues is to reconfigure the server to revert to the previous default authentication plugin (mysql_native_password). For example, use these lines in the server option file: [mysqld] default_authentication_plugin=mysql_native_password However, the setting should be viewed as temporary, not as a long term or permanent solution, because it causes new accounts created with the setting in effect to forego the improved authentication security. MySQL 8.4.0 removes the deprecated default_authentication_plugin option. The deprecated mysql_native_password authentication plugin is disabled by default as of MySQL 8.4.0, and is subject to removal in a future version. If you are using replication please take time to understand how the authentication plugin changes may impact you. More information: https://dev.mysql.com/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-caching-sha2-password-compatibility-issues https://dev.mysql.com/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-caching-sha2-password-replication https://dev.mysql.com/doc/refman/8.4/en/mysql-nutshell.html |
Most warnings tend to involve system variables whose defaults change. For example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 |
17) System variables with new default values (sysVarsNewDefaults) Warning: Following system variables that are not defined in your configuration file will have new default values. Please review if you rely on their current values and if so define them before performing upgrade. back_log - default value will change. character_set_server - default value will change from latin1 to utf8mb4. collation_server - default value will change from latin1_swedish_ci to utf8mb4_0900_ai_ci. event_scheduler - default value will change from OFF to ON. explicit_defaults_for_timestamp - default value will change from OFF to ON. innodb_autoinc_lock_mode - default value will change from 1 (consecutive) to 2 (interleaved). innodb_flush_method - default value will change from NULL to fsync (Unix), unbuffered (Windows). innodb_flush_neighbors - default value will change from 1 (enable) to 0 (disable). innodb_max_dirty_pages_pct - default value will change from 75 (%) 90 (%). innodb_max_dirty_pages_pct_lwm - default value will change from_0 (%) to 10 (%). innodb_undo_log_truncate - default value will change from OFF to ON. innodb_undo_tablespaces - default value will change from 0 to 2. log_bin - default value will change from OFF to ON. log_error_verbosity - default value will change from 3 (Notes) to 2 (Warning). log_slave_updates - default value will change from OFF to ON. master_info_repository - default value will change from FILE to TABLE. max_allowed_packet - default value will change from 4194304 (4MB) to 67108864 (64MB). max_error_count - default value will change from 64 to 1024. optimizer_trace_max_mem_size - default value will change from 16KB to 1MB. performance_schema_consumer_events_transactions_current - default value will change from OFF to ON. performance_schema_consumer_events_transactions_history - default value will change from OFF to ON. relay_log_info_repository - default value will change from FILE to TABLE. server_id - default value will change from 0 to 1. slave_rows_search_algorithms - default value will change from 'INDEX_SCAN, TABLE_SCAN' to 'INDEX_SCAN, HASH_SCAN'. table_open_cache - default value will change from 2000 to 4000. transaction_write_set_extraction - default value will change from OFF to XXHASH64. binlog_transaction_dependency_tracking - default value will change from COMMIT_ORDER to WRITESET. group_replication_consistency - default value will change from EVENTUAL to BEFORE_ON_PRIMARY_FAILOVER. group_replication_exit_state_action - default value will change from READ_ONLY to OFFLINE_MODE. innodb_adaptive_hash_index - default value will change from ON to OFF. innodb_buffer_pool_in_core_file - default value will change from ON to OFF. innodb_buffer_pool_instances - default value will change from 8 (or 1 if innodb_buffer_pool_size < 1GB) to MAX(1, #vcpu/4). innodb_change_buffering - default value will change from all to none. innodb_doublewrite_files - default value will change from innodb_buffer_pool_instances * 2 to 2. innodb_doublewrite_pages - default value will change from innodb_write_io_threads to 128. innodb_flush_method - default value will change from fsynch (unix) or unbuffered (windows) to O_DIRECT. |
And the example of an error:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
36) Check for deprecated temporal delimiters in table partitions. (deprecatedTemporalDelimiter) Error: The following columns are referenced in partitioning function using custom temporal delimiters. Custom temporal delimiters were deprecated since 8.0.29. Partitions using them will make partitioned tables unaccessible after upgrade. These partitions need to be updated to standard temporal delimiters before the upgrade. [...] More information: https://dev.mysql.com/doc/relnotes/mysql/8.0/en/news-8-0-29.html#mysqld-8-0-29-deprecation-removal https://dev.mysql.com/doc/refman/en/datetime.html |
Takeaways
A few key notes before pushing the upgrade button:
-
Always run the upgrade checker before major changes
-
Match or exceed the target version with your MySQL Shell version
-
Review warnings — especially defaults that change under the hood
-
Fix real blockers before your maintenance window
-
Test in a staging environment when possible
This tool doesn’t replace a full upgrade plan — backups, rollback path, replication considerations, plugin compatibility, and app testing still matter — but it’s a solid early line of defense.
See you next time!
The floor is yours.
0 comments · Moderated · civil & on-topicFirst comment appears here once approved. Questions, corrections, and counterpoints welcome — just no self-promotion.