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.8Confirm 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.8Confirm 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
COMPRESSEDrow format:Convert each table to
DYNAMICrow format with page compression:
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:
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
latin1orutf8mb3, do not switch toutf8mb4immediately. Explicitly define your existing character set in the newmy.cnfto override the 11.8 defaults.OLD_MODEtip: Setold_mode = UTF8_IS_UTF8MB3in your configuration so thatutf8remains 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 = OFFin the[mariadb]section ofmy.cnfto 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
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:
Verify that all MariaDB Community Server packages are uninstalled. The following command should return no results:
On Debian and Ubuntu:
Verify that all MariaDB Community Server packages are uninstalled. The following command should return no results:
On SLES:
Verify that all MariaDB Community Server packages are uninstalled. The following command should return no results:
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.
On APT systems, refresh the package index after running the setup script:
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 = OFFto prevent unpredictable execution-plan changes on day one.
Recommended my.cnf for Version 11.8
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.
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.
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.
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.
BINLOG_DO_DB
(None)
BINLOG_IGNORE_DB
(None)
BINLOG_LARGE_COMMIT_THRESHOLD
134217728
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
SLAVE_ABORT_BLOCKING_TIMEOUT
31536000
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.
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.
ALLOW_SUSPICIOUS_UDFS
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.
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_DISTANCEto 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.
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.
(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.
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.
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.
utf8mb4=...
character_set_collations must be empty for reverse replication (11.8 → 10.6).
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.
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
Scrub. Feature retired; logic is now internal.
INNODB_DEFRAGMENT_FILL_FACTOR_N_RECS²
20
Scrub. Feature retired; logic is now internal.
INNODB_DEFRAGMENT_FREQUENCY²
40
Scrub. Feature retired; logic is now internal.
INNODB_DEFRAGMENT_N_PAGES²
7
Scrub. Feature retired; logic is now internal.
INNODB_DEFRAGMENT_STATS_ACCURACY²
0
Scrub. Feature retired; logic is now internal.
INNODB_VERSION¹
10.6.26
Remove. Versioning is consolidated in global server metadata.
MAX_TMP_TABLES¹
32
Remove. Internal temp table management is now automated.
OLD_ALTER_TABLE¹
DEFAULT
Remove. Superseded by ALTER_ALGORITHM.
TIME_FORMAT²
%H:%i:%s
Scrub. Enforced standard format.
WSREP_CAUSAL_READS²
OFF
Scrub. Superseded by wsrep_sync_wait.
WSREP_LOAD_DATA_SPLITTING¹
OFF
Remove. Legacy Galera splitting logic retired.
WSREP_REPLICATE_MYISAM¹
OFF
Remove. Galera no longer supports MyISAM replication.
WSREP_STRICT_DDL¹
OFF
Remove. Replaced by wsrep_mode=STRICT_REPLICATION.
¹Fatal error. MariaDB 11.8 will abort startup if these legacy parameters are detected in the configuration file. They MUST be removed before restart to prevent upgrade failure.
Example: [ERROR] /usr/sbin/mariadbd: unknown variable 'MAX_TMP_TABLES=32'
²Warning. MariaDB 11.8 will start but log a warning if these legacy parameters are detected in the configuration file. Scrub them during the upgrade to maintain configuration hygiene and ensure settings reflect active 11.8 features.
Warning example: [Warning] 'innodb-change-buffering' was removed. It does nothing now and exists only for compatibility with old my.cnf files.
Options That Have Changed Default Values
For variables that exist in both versions but have different defaults (such as innodb_purge_batch_size), the 11.8 engine automatically applies the new value. If you require identical behavior to your 10.6 environment during the initial cutover, hardcode the 10.6 values into your new configuration file.
character_set_server
latin1
utf8mb4
Global default encoding shift.
CHARACTER_SET_CLIENT
latin1
utf8mb4
Modern standard for client connections.
CHARACTER_SET_CONNECTION
latin1
utf8mb4
Modern standard for session connections.
CHARACTER_SET_DATABASE
latin1
utf8mb4
Modern standard for database storage.
CHARACTER_SET_RESULTS
latin1
utf8mb4
Modern standard for query results.
collation_server
latin1_swedish_ci
utf8mb4_uca1400_ai_ci
Transition to the modern Unicode collation standard.
COLLATION_CONNECTION
latin1_swedish_ci
utf8mb4_uca1400_ai_ci
Update to modern Unicode Collation Algorithm (UCA).
COLLATION_DATABASE
latin1_swedish_ci
utf8mb4_uca1400_ai_ci
Update to modern Unicode Collation Algorithm (UCA).
EXPLICIT_DEFAULTS_FOR_TIMESTAMP
OFF
ON
Impacts NULL handling in TIMESTAMP columns. Modify for reverse replication (11.8 → 10.6) to maintain the same behavior on master and slave.
HAVE_SSL
DISABLED
YES
SSL/TLS is now natively available and enabled by default.
HISTOGRAM_TYPE
(Empty)
JSON_HB
Optimizer now stores histogram stats in JSON format. Modify for reverse replication (11.8 → 10.6).
INNODB_BUFFER_POOL_CHUNK_SIZE
134217728
0
Set to 0 to enable automatic calculation.
INNODB_LOG_WRITE_AHEAD_SIZE
8192
4096
Optimized for modern storage block alignment.
innodb_snapshot_isolation
OFF
ON
Enabled by default for improved consistency.
innodb_undo_tablespaces
0
3
Enables online truncation of undo logs.
optimizer_prune_level
1
2
Primary audit point for plan changes.
VERSION
10.6.26-MariaDB-log
11.8.7-MariaDB-log
Metadata only.
Deprecated Options
tx_isolation
Replaced by transaction_isolation.
tx_read_only
Replaced by transaction_read_only.
innodb_purge_rseg_truncate_frequency
Obsolete due to lighter truncation operations.
Reverse Replication (11.8 to 10.6)
If a critical regression is discovered, you can use an existing 10.6 machine in your setup as a failback safety net.
Replicating from a MariaDB 11.8 Primary to a MariaDB 10.6 Replica is NOT officially supported by MariaDB Engineering. This configuration should only be used as a temporary emergency safety net during the upgrade window.
Required 11.8 Primary Configuration
To prevent the 10.6 replica from crashing due to modern metadata (such as the #2304 character set ID), the 11.8 Primary must be configured to "downgrade" its binary log output using a compatibility file.
The rollback_compat.cnf Setup
rollback_compat.cnf SetupCreate a standalone configuration file to house these temporary reversion settings at /etc/my.cnf.d/rollback_compat.cnf:
To activate these settings, append the following line to the end of the [mariadb] section in your primary /etc/my.cnf file: !include /etc/my.cnf.d/rollback_compat.cnf
Critical Compatibility Step
MariaDB 11.8 uses a new default collation ID (#2304) that version 10.6 does not recognize. To prevent the 10.6 replica from crashing, you must set character_set_collations = '' on the 11.8 Primary. This forces the Primary to use legacy IDs that the 10.6 machine can process.
Known "Breaking" Factors
Certain 11.8 features will immediately break the 10.6 replication link if used:
Vector data types: any
INSERTorUPDATEinvolving aVECTOR(N)column.New functions: use of
VEC_Distanceor other 11.8-specific SQL functions.Large row events: if
binlog_row_event_max_sizeis tuned significantly higher than 10.6 defaults.
Note on Existing Nodes
You do not need a new machine for reverse replication. You can use an existing 10.6 node already in your setup — stop replication on that node before the upgrade and resume it once the 11.8 Primary is configured for compatibility.
Operational Steps for the Safety Net
Isolate a 10.6 Node
Before upgrading your entire environment, identify one existing replica to remain on version 10.6. Stop replication on this node just before you upgrade the Primary to 11.8.
Configure 11.8 for Compatibility
Immediately after installing version 11.8 on your Primary, apply the rollback_compat.cnf settings (such as character_set_collations = '' and binlog_checksum = CRC32).
Start 11.8 and Rotate Logs
Start the 11.8 service and run FLUSH LOGS;. This ensures the Primary begins writing its binary logs in a format the 10.6 replica can understand.
Connect the 10.6 Node
Point your existing 10.6 machine to the new 11.8 Primary. Because the data on the 10.6 node is already consistent with the pre-upgrade state, it can simply pick up the new changes from the 11.8 Primary.
Post-Upgrade Verification
After the data upgrade is complete, verify the functionality of 11.8 features.
Confirm the server version:
The result should reflect the 11.8 GA series.
Confirm Vector Search by verifying the new
VECTOR(N)data type and conversion functions:Verify optimizer performance by prefixing any SQL query with
ANALYZE FORMAT=JSONto audit the new SSD-aware cost model:The output includes real-time execution metrics such as
engine_cost(measured in milliseconds) andpages_accessed, verifying that the optimizer is correctly prioritizing high-speed storage over legacy 10.6 logic:On a replica server, run
SHOW REPLICA STATUS\Gand look for the newMaster_Slave_time_difffield.
This page is: Copyright © 2025 MariaDB. All rights reserved.
Last updated
Was this helpful?

