Downgrading MariaDB

Information on how to downgrade MariaDB Server to a lower release series, including version-specific incompatibility notes, backup and restore fallbacks, and a secure replica-based process.

Downgrade planning should ideally be taken into consideration before upgrading in settings where data loss cannot be acceptable. This may need setting up replication between versions in advance to enable controlled switching between versions if necessary.

Overview

Downgrading MariaDB is not officially supported between major versions. Downgrades, unlike upgrades, pose a potential risk since the on-disk data format, internal system tables, and storage engine architecture may not be backwards compatible.

However, a downgrade is achievable as long as you plan properly and avoid using any features that are exclusively available to the higher versions.

Before You Begin

If backported features are used with MariaDB Enterprise Server, downgrading after upgrading to a newer maintenance version may not be allowed. For more information, see the release notes for your version of MariaDB Enterprise Server, specifically the Backports section of the What's New page.

See MariaDB Enterprise Server Considerations.

Before attempting any downgrade, ensure the following factors:

Feature Compatibility

The downgrade will not succeed if any features introduced in the higher version are in use, such as new InnoDB table formats, storage engine behaviors, or system table structures.

Common version-specific features that may prevent downgrading include:

• Instant ADD/DROP COLUMN (ALTER TABLE ALGORITHM=INSTANT ): Introduced across versions 10.3 and 10.4.

• New InnoDB redo log formats: Changed across multiple versions 10.2, 10.3, 10.5, 10.8, 11.0.

• mysql.global_priv table: Replaced mysql.user in MariaDB 10.4; incompatible with 10.3.

• InnoDB change buffer removal: MariaDB 11.0 removed it; cannot downgrade to 10.4 or earlier.

See Version-Specific Incompatibilities for the full list.

Configuration Compatibility

If the older version does not support configuration options added or enabled in the current version, downgrading (and replication to a lower version) may fail.

In such circumstances, configuration variables may need to be modified to match the target version's defaults or supported options before proceeding with the downgrade.

Maintenance Releases

Downgrades within the same release series are generally possible, but compatibility should be verified, especially if changes affecting storage formats or system tables are involved. There are relatively few exceptions; for example, MariaDB 10.1.21 fixed a file format bug that prevented downgrading to previous MariaDB 10.1 versions.

Why Major Version Downgrades Break

The main reasons for a major version downgrade failure are:

• System table schema changes: As the privilege system improves, the privilege and status tables in the mysql schema change between most major versions.

• Format changes on on-disk data: These are less common and generally table-specific, but when they occur (e.g., using Instant add column in MariaDB 10.3), the affected tables cannot be opened in earlier versions.

• Internal changes to storage engines: Both MariaDB 10.2 and MariaDB 10.3, for example, introduced new versions of the InnoDB redo log that are not backward-compatible.

Generic Downgrade Process

The following is a general approach to attempting a downgrade with minimal risk. This method, which minimizes downtime and data risk, is similar to the recommended upgrade path: you set up a replica running the target lower version, make sure it replicates well, and then switch to it.

1. Before attempting downgrade process, verify that features exclusive to the higher version are not used.

2. Use mariadb-dump to create a full logical backup of your entire database.

mariadb-dump --all-databases > dumpfile

1. Additionally, back up the mysql schema separately, as this is where the majority of version-specific upgrading changes occur.

2. Store both backups securely and verify their readability before proceeding. These backups serve as your recovery path if anything goes wrong.

3. Install MariaDB's target lower version on a separate server or environment. Then, set up the lower-version server as a replica and the current (higher version) server as the primary.

4. Verify replication is working. On the lower version replica, run:

SHOW REPLICA STATUS\G

1. Once validation is complete:

   1. Stop writes to the current (higher version) server.

   2. Promote the downgraded server to the primary.

   3. Redirect application traffic to the downgraded server.

Restore from Backup (Fallback Method)

If the replica-based method is not possible, the most reliable alternative is to restore from a full backup created in Step 2 of the Generic Downgrade Process.

1. Install a lower version of MariaDB on a clean server.

2. Launch MariaDB, then restore the backup:

3. To update system tables for the previous version, run mariadb-upgrade.

4. Restart MariaDB and check the connectivity of the application.

When used on a clean installation, this method is reliable but involves more downtime than the replica-based approach.

In-Place Downgrade Method

The MariaDB developers have not tested this method, so it is not advised. A lot of things can go wrong. Whenever possible, use the backup-restore or replica-based methods mentioned above.

In general, an in-place downgrade to a previous major version is only allowed if you have not yet executed mariadb-upgrade on the new version.

Note: It is recommended to run mariadb-upgrade after upgrading to ensure security and collation correctness, which limits the available downgrade window.

If you have to attempt an in-place downgrade process, perform the following steps:

1. Shut down MariaDB cleanly. Ensure:

   1. innodb_fast_shutdown≠2.

   2. You use SHUTDOWN command, mariadb-admin shutdown or the operating system official commands, like systemctl stop mariadb.service.

2. Start the old server binary with --skip-privilege-tables to bypass the incompatible privilege tables.

3. Restore the mysql schema tables to the old definitions using ALTER TABLE, or drop and recreate them. To find the old definitions, run mariadb-install-db on a temporary data directory, start a temporary server, and use SHOW CREATE TABLE.

4. Execute FLUSH PRIVILEGES to reload the restored privilege tables.

This procedure will not work if the table format has changed in an incompatible manner. In this case the affected tables may not be accessible in the earlier version. See Version-Specific Incompatibilities below.

Version-Specific Considerations

Many of the examples that follow use outdated MariaDB versions that are currently End of Life (EOL). For production environments, downgrading to EOL versions is not recommended. These examples are provided for reference and to demonstrate potential incompatibilities.

The following is an incomplete list of cases where a table or component cannot be used in an earlier major version. Before proceeding, always check the Release Notes and Changes and Improvements pages for your target version to ensure that there are no additional incompatibilities specific to your version pair.

• MariaDB 11.0 or later

  • A downgrade to MariaDB 10.4 or earlier is not possible, because MDEV-29694 removed the InnoDB change buffer. making the format incompatible.

  • 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 need to be replaced with a logically equivalent file, or the shutdown LSN 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 must be deleted between a clean shutdown of the 10.5 and a startup of 10.4. This is not recommended.

• MariaDB 10.4 → MariaDB 10.3

  • Any InnoDB table where ALTER TABLE ALGORITHM=INSTANT DROP COLUMN was used while innodb_instant_alter_column_allowed=add_drop_reorder.

  • Any InnoDB table created or rebuilt while innodb_checksum_algorithm=full_crc32.

  • In MariaDB 10.4, the mysql.user table was replaced by the mysql.global_priv table, which may cause problems if one wants to downgrade to 10.3.

• MariaDB 10.3 → MariaDB 10.2

  • Any InnoDB table where ALTER TABLE…ADD COLUMN was used (unless innodb_instant_alter_column_allowed=never).

  • A prior shutdown with innodb_fast_shutdown=0 is required in order to empty the undo logs whose format changed in MDEV-12288. Even then, setting innodb_force_recovery=3 may be necessary.

MariaDB Enterprise Server Considerations

MariaDB Enterprise Server may include backported features, which are functionalities from newer versions added to a previous maintenance release. Downgrading to a version without a backport (even within the same release series) might not be feasible if you use a backported feature.

Before downgrading Enterprise Server:

• Review the Backports section of the relevant What's New page for your current version.

• Check for enabled backported features.

See Also

• Upgrading MariaDB

• Backup and Restore Overview

• mariadb-dump

• Setting Up Replication

• mariadb-upgrade

_{This page is licensed: CC BY-SA / Gnu FDL}