The Ultimate Guide to High Availability with MariaDB

Upgrading between major MariaDB versions

You are viewing an old version of this article. View the current version here.

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. All older versions should work too (as long as you the storage engines you where using are still around).

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 with mysqldump --add-drop-table mysql 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 that you are upgrading to.
  • 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.

Disaster recovery

In the unlikely event something goes wrong, you can try the following:

  • Move the mysql data directory to mysql-old and run mysql_install_db to generate a new one. The script will give some warnings about some InnoDB tables it can't access. Copy those tables (the .frm and .idb file) from mysql-old to mysql and try starting the server.
  • After the above, you have to add back your old users.

Downgrading

In most cases, as long as you don't have done any ALTER TABLE and you have a mysqldump of your old mysql database , you should be able to downgrade to your previous version by doing:

  • Delete the tables in the mysql database (if you didn't use the option --add-drop-table to mysqldump
  • Delete the new MariaDB installation
  • Install the old MariaDB version
  • Start the server with mysqld --skip-grant-tables
  • Install the old mysql database
  • Execute in the mysql client FLUSH PRIVILEGES

See also

Comments

Comments loading...
Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.