Downgrading between Major Versions of MariaDB

Downgrading MariaDB is not officially supported between major versions.

For minor versions, upgrade is supported to an earlier gamma/RC/GA version as we do not change the storage format after Alpha and very rarely during Beta (it has to be a very critical bug to require such a change). There are a few very rare cases when incompatible changes happen on a GA version, for example MariaDB 10.1.21 fixed a file format incompatibility bug that prevents a downgrade to earlier MariaDB 10.1 releases. After MariaDB 10.1.21 this has not happened in a GA release.

The main reason why downgrades between major versions do not work are:

• Changes in the privilege/status tables in the mysql schema. These changes happen between most major versions as we are continuously improving the privilege system.
• Changes that affect how data is stored on disk. This happens more rarely and is usually table specific. For example, if one has used Instant add column on a table in MariaDB 10.3, that table cannot be opened in MariaDB 10.2.
• Between major releases there are often substantial changes, even if none of the new features are used. For example, both MariaDB 10.2 and MariaDB 10.3 introduce new versions of the redo log.

The only reliable way to downgrade is to restore from a full backup made before upgrading, and start the old version of MariaDB. At least one should take a backup of the mysql schema as most upgrade changes happens in this directory. This may be of help if one needs to downgrade to an earlier MariaDB version. More about this later.

Some people have reported successfully downgrading, but there are many possible things that can go wrong, and downgrading between two major versions is not tested in any way by the MariaDB developers.

In general, one can downgrade a major version to an earlier version if one has not yet run mariadb-upgrade on the new version. Note however that it's recommended that one always uses mariadb-upgrade after upgrading to a new major version as otherwise some security features in the new server may not work and tables that have indexes using a character collation that has changed may not work properly.

Assuming one must downgrade to an earlier major version, here is a list of things one has to do:

• MariaDB must be shut down cleanly. This means that:
  • One should ensure that innodb_fast_shutdown≠2.
  • One uses the SHUTDOWN command, mariadb-admin shutdown or the operating system official commands, like systemctl stop mariadb.service.
• Start the old server with --skip-privilege-tables.
• Use ALTER TABLE to restore the mysql schema tables to their original definition or drop and recreate the mysql tables. One can find the old definition by using mariadb-install-db to create a separate temporary data directory. Starting the MariaDB server on the temporary directory will allow you to use SHOW CREATE TABLE to find the old definition.
• Execute FLUSH PRIVILEGES to reload the old tables.

The cases when the above will not work are when the table format has changed in an incompatible manner. In this case the affected tables may not be usable in the earlier version.

The following is an incomplete list of when one will not be able to use a table in an earlier major version:

• MariaDB 11.0 or later
  • A downgrade to MariaDB 10.4 or earlier is not possible, because MDEV-29694 removed the InnoDB change buffer.
  • A downgrade to MariaDB 10.5 or later is only possible if innodb_change_buffering=none (the default starting with MDEV-27734).
• MariaDB 10.8 or later
  • The InnoDB redo log file ib_logfile0 would have to be replaced with a logically equivalent file, or the shutdown LSN has to be written to the FIL_PAGE_FILE_FLUSH_LSN field in the system tablespace (see MDEV-27199), or the data may be accessed read-only when using innodb_force_recovery=6.
• MariaDB 10.5 → MariaDB 10.4
  • The InnoDB redo log file ib_logfile0 has to be deleted between a clean shutdown of the newer version and a startup of the older version. This is *not recommended*.
• MariaDB 10.4 → MariaDB 10.3
  • Any InnoDB table where one has used ALTER TABLE ALGORITHM=INSTANT DROP COLUMN while innodb_instant_alter_column_allowed=add_drop_reorder
  • Any InnoDB table that was created or rebuilt while innodb_checksum_algorithm=full_crc32
  • In MariaDB 10.4, the MariaDB mysql.user table was replaced by mysql.global_priv table which may cause problems if ones wants to downgrade to 10.3.
• MariaDB 10.3 → MariaDB 10.2
  • Any InnoDB table where one has used ALTER TABLE…ADD COLUMN (unless innodb_instant_alter_column_allowed=never).
  • A prior shutdown with innodb_fast_shutdown=0 will be needed in order to empty the undo logs whose format changed in MDEV-12288, and even then, you might need to set innodb_force_recovery=3.