Upgrading from MariaDB Enterprise Server 10.6 to 11.8

This guide outlines the process for performing a major version upgrade from MariaDB Enterprise Server (ES) 10.6 directly to MariaDB Enterprise Server 11.8.

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).

Prerequisites

Before beginning the upgrade, ensure these precautionary measures and environment checks are completed to protect your data.

Data Backup and Integrity

Perform a Full Backup: Use mariadb-backup to create a complete copy of your current data.

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

Prepare the Backup: Consolidate the backup files so they are ready for immediate restoration if required.
```
sudo mariadb-backup --prepare --target-dir=/data/backup/preupgrade_10.6_to_11.8
```
Verify Recoverability: Test your backup by restoring it to a non-production environment before proceeding.

Service and Plugin Preparation

Audit Plugin Transition: If you currently use the MariaDB 10.6 Audit Plugin (server_audit.so), it is recommended to transition to the MariaDB Enterprise Audit Plugin during this upgrade. If you maintain the Community version, ensure your configuration explicitly loads it to avoid conflicts.
Commit or Roll Back XA Transactions: Run XA RECOVER; to identify any external XA transactions in a prepared state; these must be finalized before the service is stopped.

Compatibility & Legacy Support

This ensures the team can maintain 10.6 behavior for applications that aren't ready for the new defaults.

Handling Non-Default Character Sets: If your 10.6 instance uses latin1 or utf8mb3, do not switch to utf8mb4 immediately. You must explicitly define your existing character set in the new my.cnf to override the 11.8 defaults.
The OLD_MODE Tip: Set old_mode = UTF8_IS_UTF8MB3 in your configuration; this ensures that utf8 remains an alias for the legacy 3-byte character set instead of the new 4-byte standard.
Maintaining SSL Compatibility: Version 11.4+ enables "Zero-configuration TLS" by default. If your application does not support SSL, set require_secure_transport = OFF in the [mariadb] section of your my.cnf to prevent connection refusals.

Environment Compatibility

Engineering Policy: Verify your operating system version is still supported for the 11.8 series by checking the MariaDB Engineering Policies.
Customer Token: Have your Customer Download Token ready for the repository configuration step.

The Upgrade Procedure

Perform a Controlled Shutdown of 10.6

Initiate Fast Shutdown to ensure the InnoDB engine closes cleanly.
```
SET GLOBAL innodb_fast_shutdown = 1;
```
Stop the Service mariadb.
```
sudo systemctl stop mariadb
```

Purge Legacy 10.6 Packages

Remove the old version to prevent package manager conflicts before installing 11.8.

YUM (RHEL/CentOS/Alma/Rocky): sudo yum remove "MariaDB-*" galera-enterprise-4
APT (Debian/Ubuntu): sudo apt-get remove "mariadb-*" galera-enterprise-4
ZYpp (SLES): sudo zypper remove "MariaDB-*" galera-enterprise-4

Switch to 11.8 Enterprise Repositories

Download and run the setup script, specifying version 11.8.

curl -LsSO https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
chmod +x mariadb_es_repo_setup
sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply --mariadb-server-version="11.8"

Install the 11.8 Release Series

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

YUM: sudo yum install MariaDB-server MariaDB-backup
APT: sudo apt update && sudo apt install mariadb-server mariadb-backup
ZYpp: sudo zypper install MariaDB-server MariaDB-backup
{% endstep %}

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 for the new engine's performance.

Scrub: Remove legacy 10.6 variables (old_alter_table, etc.).
Adopt: Add the new Optimizer Cost Model variables using their 11.8 defaults.
Stabilize: Set NEW_MODE = OFF to prevent unpredictable execution plan changes on Day 1.

Recommended my.cnf for Version 11.8 section

[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 for failing 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

Bring the Service Online and Finalize Data

Start the New Service: sudo systemctl start mariadb.
Execute the Data Upgrade Utility: This 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

Because the 11.8 engine uses a completely 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. It is strongly recommended to keep these at their defaults upon upgradation 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 the 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 (like the "Change Buffer") to delay writes because hard drives were slow at random I/O. In version 11.8, these legacy layers are being stripped back. The following InnoDB System Variables allow MariaDB to 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 & 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 and log more like a database table, allowing for near-instant lookups when a replica reconnects. See Replication and Binary Logging Variables to learn more about the variables.

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 they are 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 now tell the engine to ignore queries that touch many rows but are still fast, or to ensure that queries exceeding a specific "emergency" duration are always captured, regardless of other filters. See Server System Variables to learn more about the following variables

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 & 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 entire operating system. Version 11.8 introduces "Safety Valves" that allow administrators to 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.

A feature entirely absent in MariaDB 10.6, MariaDB 11.8 introduced native Vector Search (MHNSW).

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:

The REDIRECT_URL variable allows the server to send redirection hints to proxies or clients. Crucial: Configure this carefully on replicas to ensure that 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 value for this variable is acceptable for standard operations. However, because MariaDB 11.8's mariadb-binlog utility explicitly prints this value in its output, replaying binary logs using the 11.8 version of the tool is not recommended during the transition period.

BLOCK_ENCRYPTION_MODE^{^}

aes-128-ecb

High; Block_encryption_mode default on 11.8 is fine, but we should be careful when calling AES_ENCRYPT and AES DECRYPT_FUNCTION as syntax is different in 10.6

CHARACTER_SET_COLLATIONS^#

utf8mb4=...

Character_set_collations should be empty for 11.8 -> 10.6

TRANSACTION_ISOLATION^#

REPEATABLE-READ

TRANSACTION_READ_ONLY^#

OFF

WSREP_ALLOWLIST

(None)

WSREP_STATUS_FILE

(None)

^#Handle them 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