Upgrading a database server is usually straightforward when everything goes according to plan. Update the repository, install the new packages, restart the service, and verify that the database is running.

But sometimes, a successful package installation is only half the story.

Recently, I upgraded a MariaDB Master–Slave replication environment from MariaDB 10.11.19 to 11.8.9 on Debian 12 Bookworm. The package upgrade completed, but MariaDB refused to start afterward.

The interesting part was that the problem wasn’t caused by corrupted InnoDB data, a broken replication configuration, or an issue with the mounted data directory. The actual problem was much simpler, five compression provider plugins were missing.

There was another interesting lesson from this upgrade, I could upgrade the Slave to MariaDB 11.8.9 while keeping the Master on 10.11.19. Replication continued working normally.

This article documents the upgrade, the missing plugin issue, and why upgrading replicas before the primary is a useful strategy for MariaDB production environments.

The upgrade environment

The environment consisted of two Debian 12 servers running MariaDB with traditional binary log file and position-based replication.

Component	Before	After
Operating system	Debian 12 Bookworm	Debian 12 Bookworm
MariaDB Master	10.11.19	11.8.9
MariaDB Slave	10.11.19	11.8.9
Replication	File/position-based	File/position-based

I upgraded the Slave first, verified that replication was healthy, and then proceeded with the Master.

The upgrade itself used APT and the MariaDB repository. However, after installing the new packages, the MariaDB service failed to start.

The proble, MariaDB failed to start

The initial systemd status showed that MariaDB could not start.

sudo systemctl status mariadb

The service reported an unsuccessful startup. Unfortunately, the systemd output alone did not reveal the underlying problem.

I checked the journal.

sudo journalctl -xeu mariadb.serviceCode language: CSS (css)

But the output contained very little useful information about the actual MariaDB startup failure.

The next step was to run MariaDB directly and capture its error output.

sudo mariadbd \
  --user=mysql \
  --log-error=/tmp/mariadb-startup.log \
  --log-warnings=3Code language: JavaScript (javascript)

This exposed the actual problem.

MariaDB was looking for five compression provider libraries that were not available in the plugin directory:

/usr/lib/mysql/plugin/provider_bzip2.so
/usr/lib/mysql/plugin/provider_lz4.so
/usr/lib/mysql/plugin/provider_lzma.so
/usr/lib/mysql/plugin/provider_lzo.so
/usr/lib/mysql/plugin/provider_snappy.so

The startup log also reported unknown configuration variables.

provider_bzip2=force_plus_permanent
provider_lz4=force_plus_permanent
provider_lzma=force_plus_permanent
provider_lzo=force_plus_permanent
provider_snappy=force_plus_permanent

This was an important clue.

The existing MariaDB configuration still referenced all five compression providers, but the corresponding shared libraries were missing.

Understanding MariaDB compression provider plugins

MariaDB supports several compression algorithms through provider plugins.

These plugins extend compression support for storage engines and other database operations. Instead of bundling every compression implementation directly into the server, MariaDB distributes these providers separately.

The five providers involved in this incident were:

Provider	Compression algorithm
bzip2	BZip2
lz4	LZ4
lzma	LZMA
lzo	LZO
snappy	Snappy

If the server configuration explicitly requires these providers, their corresponding plugin libraries must be available.

The force_plus_permanent setting is particularly important. It tells MariaDB to require the provider rather than treating it as an optional plugin.

In my case, the configuration expected all five providers to be present, but the files were missing after the upgrade.

The official MariaDB documentation explains this plugin architecture in more detail.

MariaDB Compression Plugins Documentation

How to fix the missing compression plugins

The solution is to install the five provider packages.

On Debian, MariaDB distributes these plugins as separate APT packages.

First, refresh the package index.

sudo apt update

Then install all five compression providers.

sudo apt install \
  mariadb-plugin-provider-bzip2 \
  mariadb-plugin-provider-lz4 \
  mariadb-plugin-provider-lzma \
  mariadb-plugin-provider-lzo \
  mariadb-plugin-provider-snappy

These are the Debian package names. Make sure APT selects versions compatible with your installed MariaDB server package.

You can inspect the available package versions before installing.

apt-cache policy \
  mariadb-plugin-provider-bzip2 \
  mariadb-plugin-provider-lz4 \
  mariadb-plugin-provider-lzma \
  mariadb-plugin-provider-lzo \
  mariadb-plugin-provider-snappy

For a MariaDB 11.8.9 deployment, use provider packages built for the same MariaDB server package version from your configured repository.

Verify the plugin files

After installation, check whether all five shared libraries exist.

ls -lah /usr/lib/mysql/plugin/provider_*.so

You should find.

provider_bzip2.so
provider_lz4.so
provider_lzma.so
provider_lzo.so
provider_snappy.soCode language: CSS (css)

You can also run a simple automated check.

for plugin in bzip2 lz4 lzma lzo snappy; do
    file="/usr/lib/mysql/plugin/provider_${plugin}.so"

    if [ -f "$file" ]; then
        echo "[OK] $file"
    else
        echo "[MISSING] $file"
    fi
doneCode language: PHP (php)

The expected result is five [OK] messages.

Start MariaDB again

Once all required libraries are available, start MariaDB.

sudo systemctl start mariadb

Check the service.

sudo systemctl status mariadb

Then verify the installed version.

sudo mariadb -e "SELECT VERSION();"Code language: JavaScript (javascript)

You should see MariaDB 11.8.9.

Finally, check the startup log.

sudo journalctl -u mariadb -n 100 --no-pager

Look for any remaining plugin loading errors or other startup warnings that require attention.

Why I upgraded the Slave before the Master

One interesting aspect of this migration was that the Slave could run MariaDB 11.8.9 while the Master was still running MariaDB 10.11.19.

I initially upgraded only the Slave. After restarting it, I checked replication status and confirmed that both replication threads were running normally.

The topology temporarily looked like this.

        Master
      MariaDB 10.11.19
             |
             | Binary log replication
             |
             v
         Slave
      MariaDB 11.8.9

This was not an accidental compatibility result. It follows the general direction supported by MariaDB’s cross-version replication compatibility, a newer replica can replicate from an older primary, provided the versions and replication features are compatible.

MariaDB generally recommends that a replica run the same or a newer version than its primary.

The reason is straightforward, newer MariaDB versions are designed to understand older replication events, while older versions may not understand newer binary log events or features generated by a newer primary.

For that reason, upgrading the Slave first is a sensible strategy for a rolling major-version upgrade.

The recommended upgrade sequence

For a Master–Slave environment, the sequence should look like this.

Stage 1, Before the upgrade

Master: MariaDB 10.11.19
   |
   v
Slave:  MariaDB 10.11.19

Both servers run the same version.

Stage 2, Upgrade the Slave first

Master: MariaDB 10.11.19
   |
   v
Slave:  MariaDB 11.8.9

The older Master continues generating binary logs, which the newer Slave processes.

At this stage, verify that replication is healthy before touching the Master.

Stage 3, Upgrade the Master

Master: MariaDB 11.8.9
   |
   v
Slave:  MariaDB 11.8.9

Once both servers are upgraded, the replication environment returns to a matching-version configuration.

Why not upgrade the Master first?

Imagine upgrading the Master to 11.8.9 while leaving the Slave on 10.11.19.

The newer Master could generate binary log events involving features or behavior that the older Slave does not understand.

Potential compatibility problems include.

• New SQL syntax or database features.
• New data types or collations.
• Changes to binary log event formats.
• Differences in storage engine behavior.

An older Slave might fail to process an event even though both database services are running normally.

This is why upgrading the replica first is generally the safer direction.

There is an important caveat, cross-version replication compatibility is not an unconditional guarantee that every SQL statement or database feature will work across versions. Review the official compatibility matrix and release notes before upgrading, particularly when using new features, data types, or replication-related settings.

You can find more information here.

• MariaDB Replication Overview
• MariaDB Upgrade Guide

Verify replication after the upgrade

Since this environment uses Master–Slave replication, getting the database service running is not enough. Replication must also be healthy.

On the Slave, run :

sudo mariadb -e "SHOW SLAVE STATUS\G"Code language: JavaScript (javascript)

Pay attention to these fields.

Field	Expected value
Slave_IO_Running	Yes
Slave_SQL_Running	Yes
Seconds_Behind_Master	0
Last_IO_Error	Empty
Last_SQL_Error	Empty

A zero replication delay is ideal when the workload is idle and the Slave has caught up.

Also verify that MariaDB starts automatically after a server reboot.

sudo systemctl enable mariadb

In my case, the service was running after the manual start but was still marked as disabled in systemd. Enabling it ensures that MariaDB starts automatically during boot.

Add compression plugin verification to your upgrade checklist

The main lesson from this upgrade is that package installation and database readiness are two different things.

Before restarting MariaDB after a major version upgrade, I recommend checking the configuration for external plugin dependencies.

You can search for compression provider references with:

sudo grep -RniE \
  'provider_(bzip2|lz4|lzma|lzo|snappy)' \
  /etc/mysql/Code language: JavaScript (javascript)

If these providers are configured, verify that their corresponding libraries are installed.

For a Master–Slave environment, perform this check on both servers.

My updated MariaDB upgrade checklist now includes.

• Back up the database and verify the backup.
• Check MariaDB repository configuration and package versions.
• Review existing MariaDB configuration files.
• Identify external plugin dependencies.
• Verify all required compression provider packages.
• Upgrade the Slave first.
• Verify the Slave starts and replication is healthy.
• Upgrade the Master.
• Verify the Master and Slave versions.
• Verify replication status again.
• Ensure MariaDB is enabled at boot.

Final thoughts

The interesting thing about this incident is that the database itself was not the problem. InnoDB initialized successfully and recovered its data directory. The startup failure was caused by missing external plugin libraries referenced by the existing configuration.

There was also a useful architectural lesson, MariaDB’s cross-version replication compatibility makes it possible to upgrade replicas first, validate the new version, and then upgrade the primary.

This is a practical approach for production environments where database downtime needs to be minimized.

For anyone running MariaDB in production, especially with Master–Slave replication, I would add plugin verification and replica-first sequencing to the upgrade procedure rather than waiting for the database to fail during its first restart.

A few minutes of dependency checks and a carefully planned upgrade sequence can save a lot of troubleshooting afterward.