Upgrading between major MariaDB versions
MariaDB is designed from the start up to allow easy upgrades. This means that you should be able to trivially upgrade from ANY earlier MariaDB version to the latest one (for example MariaDB 5.5.x to MariaDB 10.5.x), usually in a few seconds. This is also mainly true for any MySQL version < 8.0 to MariaDB 10.4 and up.
The reason that upgrades are normally *easy* are:
- All MariaDB table data files are backward compatible
- The MariaDB connection protocol is backward compatible.
- The MariaDB Slave can be of any newer version than Master.
MariaDB Corporation is regularly running test to check that one can upgrade from MariaDB 5.5 to the latest MariaDB version without any trouble.
Requirements for doing an upgrade between major versions
- Clean shutdown of the server. The reason this is needed is that even if data files are compatible between versions, the recovery logs may not be. A clean shutdown ensures that the old recovery logs can
- Backup of the database (just in case). At least, take a copy of the *mysql* data directory as most of the upgrade changes are done there (adding new fields and new system tables etc).
Note that rpm's doesn't support upgrade between major versions, only minor like 10.4.1 to 10.4.2. If you are using rpm's, you should de-install the old MariaDB rpms and install the new MariaDB rpm's before running mysql_upgrade. Note that when installing the new rpm's the mysql_upgrade may be run automatically. There is however no problem with running mysql_upgrade many times.
Work done by mysql_upgrade
The main work done when doing an upgrade is done by running mysql_upgrade. The main things that mysql_upgrade are doing are:
- Updating the system tables in the mysql database to the newest version. This is a very fast process!
- mysql_upgrade also runs mysqlcheck --check-upgrade to check if there has been any collaction changes between the major versions. This recreates indexes in old tables that are using any of the changed collation. This can take a bit of time if there is a lot of tables or there are many tables with is used the changed collation. The last time a collation changed was in MariaDB/MySQL 5.1.23.
Post upgrade work
Check the MariaDB error log for any problems during upgrade. The common errors are:
- Using obsolete options. If this is the case, remove them from your [configuring-mariadb-with-option-files|my.cnf files]].
- Check the manual for new features that has been added since your last MariaDB version.
- Test that your application works as before. The main difference from before is that because of optimizer improvements your application should work better than before, but in some rare cases the optimizer may get something wrong. In this case, you can try to use explain, optimizer trace or optimizer_switch to fix the queries.
If something goes wrong
- Check first the MariaDB error log if you are using any old configure options that are not supported anymore. In MariaDB we do our best to not remove options (as this makes upgrades harder), but some times we are depending on external storage engines that handles their own options and that can cause issues.
- Check the upgrade notices for the MariaDB release
- File an issue in the MariaDB bug tracker so that we know about the issue and can provide a fix to make upgrades even better!
- Add a comment to this manual entry for how we can improve it.
