Upgrade MariaDB or MySQL Major Version Safely

Old database versions stop receiving security fixes. A MariaDB or MySQL upgrade to a supported major version is routine if you prepare: most problems come from skipped backups, removed features or jumping too many versions at once.

Before you start

Root access and a maintenance window (expect a few minutes of database downtime).
Current version: mysql -V.
The target version's release notes: removed options, changed defaults (e.g. authentication plugins, SQL modes).
Free disk space at least equal to the data directory size, for the backup.
On cPanel servers, use WHM → Software → MySQL/MariaDB Upgrade instead of these steps.

Plan the upgrade path

MySQL supports upgrading one series at a time: 5.7 → 8.0 → 8.4 LTS. Do not skip from 5.7 straight to 8.4.
MariaDB is more flexible, but upgrading through intermediate LTS releases (e.g. 10.6 → 10.11 → 11.4) is the safest route.
Moving from MySQL to MariaDB is possible from MySQL 5.7, but from MySQL 8 a dump and import is needed.

Back up everything

Take a logical dump of all databases and keep it off the server too:

mysqldump --all-databases --single-transaction --routines --triggers --events | gzip > /backup/pre-upgrade-$(date +%F).sql.gz

Also copy the configuration and, if possible, take a VPS snapshot:

cp -a /etc/mysql /backup/etc-mysql-$(date +%F)

(/etc/my.cnf and /etc/my.cnf.d on AlmaLinux/Rocky.)

Check compatibility (MySQL)

For MySQL, run the upgrade checker from MySQL Shell against the running server:

mysqlsh -- util checkForServerUpgrade root@localhost:3306 --target-version=8.4.0

Fix every error it reports (removed functions, reserved words used as names, old authentication plugins). Warnings are worth reading too.

Upgrade MariaDB on Ubuntu/Debian

Switch the repository to the new series using MariaDB's official repository setup script, specifying the version:
```
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | bash -s -- --mariadb-server-version="mariadb-11.4"
```

Stop the service and upgrade the packages:

systemctl stop mariadb && apt update && apt install mariadb-server

Start it and run the upgrade step (recent versions run it automatically on start, but running it is harmless):
```
systemctl start mariadb && mariadb-upgrade
```

On AlmaLinux/Rocky, the same repository script works; then run dnf upgrade MariaDB-server (or remove the old packages and install the new ones if the package names changed).

Upgrade MySQL

Update the MySQL APT or Yum repository configuration to the target series (MySQL provides a repository setup package).
Stop MySQL and install the new server package: apt install mysql-server or dnf upgrade mysql-community-server.
Start MySQL. Since 8.0.16 the server upgrades the data dictionary and system tables automatically on first start; watch the error log while it runs.

Verify the result

mysql -V and SELECT VERSION(); show the new version.
The error log has no errors: journalctl -u mariadb -n 100 (or mysql/mysqld).
Check tables: mysqlcheck --all-databases --check
Test every application that uses the database: logins, writes, searches, admin pages.

Rollback plan

Major version downgrades in place are not supported: the data files are converted. To go back, reinstall the old version on an empty data directory and restore the logical dump, or restore the VPS snapshot. That is why the backup step is not optional.

Troubleshooting

Service fails to start after upgrade: an option in your config was removed in the new version (for example query_cache_size on MySQL 8). The error log names it; remove or update the line.
Apps fail with authentication errors on MySQL 8: the default plugin is caching_sha2_password. Update the client library, or set the app user to mysql_native_password where still supported.
Queries fail with syntax errors: a new reserved word (e.g. RANK, GROUPS) is used as a column name. Quote it with backticks.
Package conflicts: remove distribution packages before installing vendor packages, without deleting the data directory.

Database upgrade FAQ

How long does the upgrade take?

The package upgrade takes minutes. Converting system tables is fast; large data directories mostly add time for the backup.

Should I upgrade replicas first?

Yes. Replicas may run a newer version than the primary, so upgrade them first, then the primary.

Which version should I choose?

The latest LTS release supported by your applications: MySQL 8.4 LTS or a current MariaDB LTS series.

Next steps

Was this guide helpful?

Still stuck?

Ask MdmHost AI for a quick answer, or open a ticket and our team will take a look. We are here 24/7.

Ask MdmHost AI Open a ticket