Before starting a new MySQL binary on an existing data directory, check both the live server and its configuration file for incompatibilities. A removed option in my.cnf or my.ini can stop startup, and by then the newer server may already have changed internal metadata.
Last updated: October 12, 2026.
// Run in MySQL Shell JavaScript mode with a current backup available.
util.checkForServerUpgrade('admin@db01:3306', {
targetVersion: '8.4.0',
configPath: '/etc/mysql/my.cnf',
outputFormat: 'TEXT'
});Use the newest MySQL Shell version that supports both the current and target servers, and set the actual target version rather than copying the example. Provide configPath so checks for removed or changed system variables can inspect the file used at startup.
Treat the report as a preflight checklist
The official Upgrade Checker documentation lists checks for removed system variables, changed defaults, obsolete SQL modes, removed functions, and schema incompatibilities. Resolve every applicable error, then rerun the utility until the report matches the intended upgrade path.
Confirm which option files the service actually reads. Package installations, containers, and manual tarball installations can use different paths or include directories. Save the effective configuration and server variables with the backup so the pre-upgrade environment can be reconstructed.
Prepare rollback before the first new startup
MySQL’s upgrade prerequisites warn that removed startup options require configuration changes. Take a tested physical or logical backup appropriate to the database size, record replication state, and rehearse restore on a separate system. Do not assume old binaries can open a data directory after the newer server upgrades its data dictionary.
Perform a rehearsal on a restored copy with the same option files, plugins, character sets, and operating-system packages. Start the target server, run application smoke tests, and execute integrity and backup checks. A schema-only compatibility report cannot expose every runtime or deployment problem.
Read the target release’s upgrade and downgrade restrictions, then schedule time to validate authentication, applications, replication, and backups. Continue with authentication plugin errors, cross-version restore errors, and checking the MySQL version.
