Upgrade from MariaDB Community Server 10.6 to MariaDB Enterprise Server 11.8

Upgrade directly from MariaDB Community Server 10.6 to MariaDB Enterprise Server 11.8 — combining a product switch (Community to Enterprise) and a major version jump (10.6 to 11.8) in a single upgrade

This guide outlines a direct upgrade from MariaDB Community Server 10.6 to MariaDB Enterprise Server 11.8. It combines two transitions in a single upgrade window: a product switch (Community to Enterprise) and a major version jump (10.6 to 11.8). With MariaDB Community Server 10.6 approaching end-of-life, this path lets you move to a maintained Enterprise release without an intermediate stop on ES 10.6.

This guide assumes you are running on a variant of Linux that uses systemd to manage services (such as RHEL, CentOS, AlmaLinux, Rocky Linux, Debian, Ubuntu, or SLES).

This is a substantial change: a product switch and a major version jump performed back-to-back. Read this guide end-to-end before you start, and rehearse the procedure in a non-production environment first. Review the MariaDB Engineering Policies to confirm your operating system is supported on the 11.8 release series.

Prerequisites

Complete these checks and preparations before stopping your 10.6 service.

Data Backup and Integrity

Occasionally, issues can be encountered during upgrades. These issues can even potentially corrupt the database's data files, preventing you from easily reverting to the old installation. It is generally best to perform a backup prior to upgrading. If an issue is encountered during the upgrade, you can use the backup to restore your MariaDB Server database to the old version. If the upgrade finishes without issue, then the backup can be deleted.

The instructions below show how to perform a backup using MariaDB Backup. For more information about backing up and restoring the database, please see the Recovery Guide.

Take a full backup.

sudo mariadb-backup --backup \
      --user=mariadb-backup_user \
      --password=mariadb-backup_passwd \
      --target-dir=/data/backup/preupgrade_cs10.6_to_es11.8

Confirm successful completion of the backup operation.

Prepare the backup so it is ready for immediate restoration if required.
```
sudo mariadb-backup --prepare \
      --target-dir=/data/backup/preupgrade_cs10.6_to_es11.8
```
Confirm successful completion of the prepare operation.
Verify recoverability: test your backup by restoring it to a non-production environment before proceeding.

Convert InnoDB Row Format

MariaDB Enterprise Server 10.6 and later changed the COMPRESSED InnoDB row format to read-only. Before upgrading to MariaDB Enterprise Server 11.8, modify any compressed InnoDB tables on your 10.6 Community Server to use the DYNAMIC row format with PAGE_COMPRESSED=1.

Identify any InnoDB tables that use the COMPRESSED row format:

SELECT NAME, ROW_FORMAT
FROM information_schema.INNODB_SYS_TABLES
WHERE NAME NOT LIKE 'SYS_%'
   AND ROW_FORMAT = 'COMPRESSED';

Convert each table to DYNAMIC row format with page compression:

ALTER TABLE accounts.hq_sales
ROW_FORMAT = DYNAMIC
PAGE_COMPRESSED = 1;

Audit Plugin Considerations

If you have the MariaDB Audit Plugin (server_audit.so) installed on your Community Server, remove it before upgrading. Otherwise it will conflict with the MariaDB Enterprise Audit Plugin that ships with MariaDB Enterprise Server 10.4 and later.

Remove the plugin by using the UNINSTALL SONAME statement:

UNINSTALL SONAME 'server_audit';

If you load the plugin in a configuration file using the plugin_load_add option, remove that option as well. The MariaDB Enterprise Audit Plugin is automatically installed when you install MariaDB Enterprise Server.

Compatibility and Legacy Support

These defaults ensure 11.8 keeps behaving like your 10.6 instance for applications that aren't yet ready for the new defaults.

Non-default character sets: If your 10.6 instance uses latin1 or utf8mb3, do not switch to utf8mb4 immediately. Explicitly define your existing character set in the new my.cnf to override the 11.8 defaults.
OLD_MODE tip: Set old_mode = UTF8_IS_UTF8MB3 in your configuration so that utf8 remains an alias for the legacy 3-byte character set instead of the new 4-byte standard.
SSL compatibility: MariaDB 11.4 and later enable "Zero-configuration TLS" by default. If your application does not support SSL, set require_secure_transport = OFF in the [mariadb] section of my.cnf to prevent connection refusals.
XA transactions: Run XA RECOVER; to identify any external XA transactions in a prepared state. These must be committed or rolled back before the service is stopped.

Environment Compatibility

Engineering policy: Verify your operating system version is supported for the 11.8 series in the MariaDB Engineering Policies.
Customer Download Token: Retrieve your token from https://customers.mariadb.com/downloads/token/. You'll need it to configure the Enterprise repository in the steps below.

The Upgrade Procedure

Perform a Controlled Shutdown of MariaDB Community Server 10.6

Initiate a fast shutdown so the InnoDB engine closes cleanly:
```
SET GLOBAL innodb_fast_shutdown = 1;
```
Stop the service:
```
sudo systemctl stop mariadb
```

Purge the MariaDB Community Server 10.6 Packages

When switching from MariaDB Community Server to MariaDB Enterprise Server, it is necessary to remove the existing Community Server installation before installing Enterprise Server. Otherwise, the package manager will refuse to install the Enterprise Server packages.

For Community Server 10.6, the Galera package is galera-4 (named galera-3 on APT for some legacy 10.3 installations, but 10.6 always uses galera-4).

On RHEL, AlmaLinux, CentOS, and Rocky Linux:

sudo yum remove "MariaDB-*" galera-4

Verify that all MariaDB Community Server packages are uninstalled. The following command should return no results:

rpm --query --all | grep -i -E "mariadb|galera"

On Debian and Ubuntu:

sudo apt-get remove "mariadb-*" galera-4

Verify that all MariaDB Community Server packages are uninstalled. The following command should return no results:

apt list --installed | grep -i -E "mariadb|galera"

On SLES:

sudo zypper remove "MariaDB-*" galera-4

Verify that all MariaDB Community Server packages are uninstalled. The following command should return no results:

rpm --query --all | grep -i -E "mariadb|galera"

Be sure to check that the wildcard does not unintentionally refer to any of your custom applications.

Configure the MariaDB Enterprise Server 11.8 Repository

Download the repository setup script, verify it, and run it with your Customer Download Token to register the 11.8 Enterprise repository. Replace CUSTOMER_DOWNLOAD_TOKEN with the token retrieved during Prerequisites, and substitute ${checksum} with the latest published checksum from the Versions section of the MariaDB Package Repository Setup and Usage page.

curl -LsSO https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
echo "${checksum}  mariadb_es_repo_setup" | sha256sum -c -
chmod +x mariadb_es_repo_setup
sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \
   --mariadb-server-version="11.8"

On APT systems, refresh the package index after running the setup script:

sudo apt update

Install MariaDB Enterprise Server 11.8

The repository setup only configures the source; install the new binaries explicitly.

sudo yum install MariaDB-server MariaDB-backup

Installation of additional packages may be required for some plugins. Installation only loads MariaDB Enterprise Server onto the system — configuration is the next step.

Implement Version-Specific Configuration Changes

Do not apply 11.8-specific variables while the 10.6 service is active. During the package swap, update my.cnf to adopt the 11.8 defaults for the Optimizer Cost Model. These variables replace legacy hardcoded logic and are essential to the new engine's performance.

Scrub legacy 10.6 variables (old_alter_table, etc.) — see Removed, Superseded, or Renamed Options below.
Adopt the new Optimizer Cost Model variables using their 11.8 defaults.
Stabilize with NEW_MODE = OFF to prevent unpredictable execution-plan changes on day one.

Recommended my.cnf for Version 11.8

[mariadb]
# --- CHARACTER SETS & COLLATIONS ---
# utf8mb4 is the modern default; UCA 14.0.0 is ID #2304
character-set-server  = utf8mb4
collation-server      = utf8mb4_uca1400_ai_ci
# Use old_mode if your app requires 3-byte utf8 aliases
old_mode              = UTF8_IS_UTF8MB3

# --- OPTIMIZER COST MODEL (CRITICAL) ---
# Adopting 11.8 defaults replaces legacy hardcoded logic.
# Set NEW_MODE = OFF to stabilize query plans during initial cutover.
new_mode                        = OFF
optimizer_disk_read_cost        = 10.24
optimizer_disk_read_ratio       = 0.02
optimizer_extra_pruning_depth   = 8
optimizer_index_block_copy_cost = 0.0356
optimizer_key_compare_cost      = 0.011361
optimizer_key_copy_cost         = 0.015685
optimizer_key_lookup_cost       = 0.435777
optimizer_key_next_find_cost    = 0.082347
optimizer_rowid_compare_cost    = 0.002653
optimizer_rowid_copy_cost       = 0.002653
optimizer_row_copy_cost         = 0.060866
optimizer_row_lookup_cost       = 0.130839
optimizer_row_next_find_cost    = 0.045916
optimizer_scan_setup_cost       = 10
optimizer_where_cost            = 0.032

# --- INNODB STORAGE ENGINE ---
innodb_flush_method      = O_DIRECT
innodb_undo_log_truncate = ON
innodb_purge_batch_size  = 1000

# --- REPLICATION SAFETY NET ---
# REQUIRED if you intend to fail back to an existing 10.6 node.
# Fixes "Character set #2304" errors on legacy replicas.
character_set_collations = ''
binlog_alter_two_phase   = 1

# --- COMPLIANCE & CLEANUP ---
transaction_isolation    = REPEATABLE-READ
transaction_read_only    = OFF

If your platform uses YUM or ZYpp, note that MariaDB Enterprise Server's packages bundle the following configuration files: /etc/my.cnf, /etc/my.cnf.d/client.cnf, /etc/my.cnf.d/mariadb-enterprise.cnf, /etc/my.cnf.d/mysql-clients.cnf, and /etc/my.cnf.d/server.cnf. If your previous Community Server configuration files contained custom edits, the package manager may save your edited version with the .rpmsave extension during installation. Restore your edits before starting the new server.

Bring the Service Online and Run mariadb-upgrade

Start the new service:
```
sudo systemctl start mariadb
```
Run the data-directory upgrade utility. It corrects system table structures and marks data files as compatible with version 11.8:
```
sudo mariadb-upgrade
```

Incompatible and Significant Changes

The following variables from version 10.6 have been removed, renamed, or deprecated in the 11.8 release series.

New Variables Added in 11.8

Once the 11.8 binaries are installed, update your my.cnf to define these new variables.

Optimizer Cost Model Variables

Handle with care. The 11.8 engine uses a new weighting system designed for modern storage (SSDs). Altering these variables without extensive benchmarks can lead to severe performance degradation or inefficient query execution plans. Keep these at their defaults upon upgrade unless you are performing expert-level performance tuning.

These variables define the weights of the new optimizer. If query execution plans change after the upgrade, these parameters are the primary audit points and represent the optimizer cost model.

Variable Name

11.8 Default

Note

NEW_MODE

OFF

OPTIMIZER_DISK_READ_COST

10.24

Optimizer Plan Consistency:

Row-based replication (RBR) remains unaffected by these changes. However, because the 11.8 Primary uses the new cost model while legacy 10.6 nodes use hardcoded logic, query execution plans may differ significantly between Master and Slave.

OPTIMIZER_DISK_READ_RATIO

0.02

OPTIMIZER_EXTRA_PRUNING_DEPTH

8

OPTIMIZER_INDEX_BLOCK_COPY_COST

0.0356

OPTIMIZER_KEY_COMPARE_COST

0.011361

OPTIMIZER_KEY_COPY_COST

0.015685

OPTIMIZER_KEY_LOOKUP_COST

0.435777

OPTIMIZER_KEY_NEXT_FIND_COST

0.082347

OPTIMIZER_ROWID_COMPARE_COST

0.002653

OPTIMIZER_ROWID_COPY_COST

0.002653

OPTIMIZER_ROW_COPY_COST

0.060866

OPTIMIZER_ROW_LOOKUP_COST

0.130839

OPTIMIZER_ROW_NEXT_FIND_COST

0.045916

OPTIMIZER_SCAN_SETUP_COST

10

OPTIMIZER_WHERE_COST

0.032

InnoDB Variables

InnoDB used complex buffering (such as the Change Buffer) to delay writes because hard drives were slow at random I/O. In version 11.8 these legacy layers are stripped back. The following InnoDB system variables let MariaDB communicate more directly with modern SSD/NVMe storage, reducing the "middleman" overhead of the operating system's cache.

Variable Name

11.8 Default

INNODB_ADAPTIVE_HASH_INDEX_CELLS^{^}

34679

INNODB_ALTER_COPY_BULK^#

ON

INNODB_BUFFER_POOL_SIZE_AUTO_MIN

134217728

INNODB_BUFFER_POOL_SIZE_MAX

134217728

INNODB_DATA_FILE_BUFFERING

OFF

INNODB_DATA_FILE_WRITE_THROUGH

OFF

INNODB_LINUX_AIO

auto

INNODB_LOG_CHECKPOINT_NOW

OFF

INNODB_LOG_FILE_BUFFERING

OFF

INNODB_LOG_FILE_MMAP

OFF

INNODB_LOG_FILE_WRITE_THROUGH

OFF

INNODB_LOG_SPIN_WAIT_DELAY

0

INNODB_TRUNCATE_TEMPORARY_TABLESPACE_NOW

OFF

Replication and Binlog Variables

As clusters grow, managing the Global Transaction ID (GTID) list becomes a performance bottleneck. 11.8 introduces "GTID Indexing," which treats the replication log more like a database table, allowing near-instant lookups when a replica reconnects. See Replication and Binary Logging Variables for details.

Variable Name

11.8 Default

Note

BINLOG_ALTER_TWO_PHASE^#

OFF

BINLOG_DO_DB

(None)

BINLOG_GTID_INDEX^#

ON

BINLOG_GTID_INDEX_PAGE_SIZE^#

4096

BINLOG_GTID_INDEX_SPAN_MIN^#

65536

BINLOG_IGNORE_DB

(None)

BINLOG_LARGE_COMMIT_THRESHOLD

134217728

BINLOG_LEGACY_EVENT_POS^#

OFF

BINLOG_ROW_EVENT_MAX_SIZE^#

8192

Packet safety: ensure this value on the 11.8 Primary is strictly lower than the MAX_ALLOWED_PACKET setting on your 10.6 Replicas. If an 11.8 row event exceeds the legacy replica's packet limit, replication will fail with a "Packet too large on slave" error.

BINLOG_SPACE_LIMIT

0

REPLICATE_REWRITE_DB^#

(None)

SLAVE_ABORT_BLOCKING_TIMEOUT

31536000

SLAVE_CONNECTIONS_NEEDED_FOR_PURGE^#

1

Binary log purge safety:

The default value is 1. If your topology requires that binary logs be retained until acknowledged by multiple replicas, increase this value to prevent the primary from purging logs before all critical slaves have synchronized the data.

SLAVE_MAX_STATEMENT_TIME

0

Advanced Logging Variables

Slow logging was often a blunt instrument that could either miss critical spikes or flood the disk with useless data. Version 11.8 introduces granular filters: you can ignore queries that touch many rows but are still fast, or ensure that queries exceeding a specific "emergency" duration are always captured regardless of other filters. See Server System Variables for details.

Variable Name

11.8 Default

LOG_SLOW_ALWAYS_QUERY_TIME

31536000

LOG_SLOW_MIN_EXAMINED_ROW_LIMIT

0

LOG_SLOW_QUERY

OFF

LOG_SLOW_QUERY_FILE

(Host Specific)

LOG_SLOW_QUERY_TIME

10

Security and Authentication Variables

MariaDB 11.8 shifts toward modern cryptographic standards. This includes better handling of User-Defined Functions (UDFs) and a transition toward the caching_sha2_password plugin, which provides significantly stronger protection against man-in-the-middle and brute-force attacks compared to legacy authentication.

Variable Name

11.8 Default

ALLOW_SUSPICIOUS_UDFS

OFF

SKIP_GRANT_TABLES^#

OFF

Resource Limits Variables

A single unoptimized query could theoretically consume all available disk space by creating a massive temporary table, crashing the operating system. Version 11.8 introduces safety valves that let administrators set hard limits on how much temporary space a single session or the entire server can use.

Variable Name

11.8 Default

MAX_BINLOG_TOTAL_SIZE

0

MAX_TMP_SESSION_SPACE_USAGE

1099511627776 (1TB)

MAX_TMP_TOTAL_SPACE_USAGE

1099511627776 (1TB)

Vector Search / MHNSW Variables

MariaDB 11.8 introduces a native Vector Search engine using the Metadata-HNSW (Hierarchical Navigable Small Worlds) algorithm. This allows the database to store and query embeddings (mathematical representations of text/images), enabling AI-powered semantic search directly within the SQL layer.

Vector Search is entirely absent from MariaDB 10.6.

Primary config: use MHNSW_DEFAULT_DISTANCE to define semantic search logic (default: euclidean).
Compatibility warning: legacy 10.6 replicas cannot process vector data types or SQL functions; using them will break the replication link.

Variable Name

11.8 Default

MHNSW_DEFAULT_DISTANCE^#

euclidean

MHNSW_DEFAULT_M

6

MHNSW_EF_SEARCH

20

MHNSW_MAX_CACHE_SIZE

16777216

General Architecture Changes Variables

The final group of changes focuses on renaming legacy variables for industry compliance (SQL Standard) and adding features that improve how the database communicates with external tools such as proxies or system-versioning audit logs.

Variable Name

11.8 Default

Note

REDIRECT_URL^#

(None)

Replication redirection safety:

REDIRECT_URL lets the server send redirection hints to proxies or clients. Crucial: configure this carefully on replicas to ensure internal slave-to-primary connections are not redirected, as accidental redirection of replication traffic will break the sync link.

SYSTEM_VERSIONING_INSERT_HISTORY^#

OFF

System versioning & binlog replay:

The default is acceptable for standard operations. Because MariaDB 11.8's mariadb-binlog utility explicitly prints this value in its output, replaying binary logs with the 11.8 version of the tool is not recommended during the transition period.

BLOCK_ENCRYPTION_MODE^{^}

aes-128-ecb

The 11.8 default is fine, but exercise care when calling AES_ENCRYPT and AES_DECRYPT; the syntax differs from 10.6.

CHARACTER_SET_COLLATIONS^#

utf8mb4=...

character_set_collations must be empty for reverse replication (11.8 → 10.6).

TRANSACTION_ISOLATION^#

REPEATABLE-READ

TRANSACTION_READ_ONLY^#

OFF

WSREP_ALLOWLIST

(None)

WSREP_STATUS_FILE

(None)

^#Handle with extra care. These variables have the highest impact on system stability and performance; please review during your configuration updates.

^{^}Caution. These variables may impact system stability and performance; please review during your configuration updates.

Options to Remove, Rename, or Update in 11.8

Removed, Superseded, or Renamed Options

During the maintenance window (after stopping 10.6 and before starting 11.8), you must scrub your my.cnf of all removed, superseded, and renamed options.

Variable Name

10.6 Default

Technical Action / Replacement

DATETIME_FORMAT²

%Y-%m-%d %H:%i:%s

Scrub. 11.8 enforces standard internal format strings.

DATE_FORMAT²

%Y-%m-%d

Scrub. Enforced standard format.

DEBUG_NO_THREAD_ALARM¹

OFF

Remove. Retired legacy debug code.

INNODB_CHANGE_BUFFERING²

none

Scrub. Logic replaced by SSD-optimized write paths.

INNODB_CHANGE_BUFFER_MAX_SIZE¹

25

Remove. Buffer size is now managed internally by the engine.

INNODB_DEFRAGMENT²

OFF

Scrub. Manual defragmentation is no longer supported.

INNODB_DEFRAGMENT_FILL_FACTOR²

0.9