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

Running MariaDB Enterprise Server in a Galera Cluster? See Upgrading from MariaDB Enterprise Server 10.6 to 11.8 with Galera Cluster for the cluster-specific procedure (packages, shutdown order, and bootstrapping). The configuration changes below apply to every node.

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

1

Perform a Controlled Shutdown of 10.6

1. Initiate Fast Shutdown to ensure the InnoDB engine closes cleanly.

   SET GLOBAL innodb_fast_shutdown = 1;

2. Stop the Service mariadb.

   sudo systemctl stop mariadb

2

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

3

Switch to 11.8 Enterprise Repositories

Download the setup script, verify its checksum, and run it, specifying version 11.8. 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"

4

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

5

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 = "" to keep query planning closer to 10.6 and prevent unpredictable execution plan changes on Day 1. new_mode is a SET variable and does not accept a literal OFF value — setting OFF aborts startup (including during Galera/wsrep recovery). Note: "" is not the 11.8 default (the default is FIX_DISK_TMPTABLE_COSTS), so this is a deliberate opt-out.

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 empty to keep 10.6-like query planning ("" is not the default; the default is FIX_DISK_TMPTABLE_COSTS).
new_mode                      = ""
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 (optional tuning; not 11.8 defaults) ---
# Do not carry innodb_flush_method over from 10.6: it is deprecated
# and has no effect in 11.8 (file buffering is controlled by
# innodb_data_file_buffering and innodb_log_file_buffering).
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

6

Bring the Service Online and Finalize Data

1. Start the New Service: sudo systemctl start mariadb.

2. 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	FIX_DISK_TMPTABLE_COSTS	Recommended: set to "" (empty) for 10.6-like planning. new_mode is a SET variable and does not accept a literal OFF value (OFF aborts startup).
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^	16381 (derived from innodb_buffer_pool_size at startup)
INNODB_ALTER_COPY_BULK#	ON
INNODB_BUFFER_POOL_SIZE_AUTO_MIN	0 (auto: follows innodb_buffer_pool_size_max)
INNODB_BUFFER_POOL_SIZE_MAX	Auto-sized at startup
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	ON (Linux and FreeBSD; OFF on other platforms)
INNODB_LOG_FILE_WRITE_THROUGH	OFF
INNODB_LOG_SPIN_WAIT_DELAY	0 (deprecated; no effect)
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#	uca1400_ai_ci mapped for utf8mb3, utf8mb4, ucs2, utf16, and utf32	Set character_set_collations = '' on the 11.8 Primary when replicating back to 10.6 (see Reverse Replication)
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	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.
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. These parameters MUST be removed prior to 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 the file of these parameter 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 have existed in both versions but have different defaults (e.g., innodb_undo_tablespaces), the 11.8 engine will automatically apply the new value. If you require identical behavior to your 10.6 environment during the initial cutover, you must explicitly hardcode the 10.6 values into your new configuration file.

Options	10.6 Default	11.8 Default	Impact / Note
character_set_server	latin1	utf8mb4	Certified Change: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 TIMESTAMPcolumns. Modify for reverse replication (11.8->10.6) to maintain same behavior on master and slave
HISTOGRAM_TYPE	DOUBLE_PREC_HB	JSON_HB	Optimizer now stores histogram stats in JSON format. Modify for reverse replication (11.8->10.6) to maintain same behavior on master and slave
IGNORE_DB_DIRS	(Empty)	#binlog_cache_files	Informational; no action needed. 11.8 automatically adds its internal binary log cache directory to this list so it is not treated as a database.
INNODB_BUFFER_POOL_CHUNK_SIZE	134217728	0	Deprecated in both versions and has no effect; remove it from your configuration.
INNODB_LOG_WRITE_AHEAD_SIZE	8192	512	Read-only in 11.8; must be a power of two.
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	Red Flag: Primary audit point for plan changes.
OPTIMIZER_SWITCH	index_merge=on, index_merge_union=on, index_merge_sort_union=on, index_merge_intersection=on, index_merge_sort_intersection=off, engine_condition_pushdown=off, index_condition_pushdown=on, derived_merge=on, derived_with_keys=on, firstmatch=on, loosescan=on, materialization=on, in_to_exists=on, semijoin=on, partial_match_rowid_merge=on, partial_match_table_scan=on, subquery_cache=on, mrr=off, mrr_cost_based=off, mrr_sort_keys=off, outer_join_with_cache=on, semijoin_with_cache=on, join_cache_incremental=on, join_cache_hashed=on, join_cache_bka=on, optimize_join_buffer_size=on, table_elimination=on, extended_keys=on, exists_to_in=on, orderby_uses_equalities=on, condition_pushdown_for_derived=on, split_materialized=on, condition_pushdown_for_subquery=on, rowid_filter=on, condition_pushdown_from_having=on, not_null_range_scan=off, hash_join_cardinality=off, cset_narrowing=off, sargable_casefold=off	index_merge=on, index_merge_union=on, index_merge_sort_union=on, index_merge_intersection=on, index_merge_sort_intersection=off, index_condition_pushdown=on, derived_merge=on, derived_with_keys=on, firstmatch=on, loosescan=on, materialization=on, in_to_exists=on, semijoin=on, partial_match_rowid_merge=on, partial_match_table_scan=on, subquery_cache=on, mrr=off, mrr_cost_based=off, mrr_sort_keys=off, outer_join_with_cache=on, semijoin_with_cache=on, join_cache_incremental=on, join_cache_hashed=on, join_cache_bka=on, optimize_join_buffer_size=on, table_elimination=on, extended_keys=on, exists_to_in=on, orderby_uses_equalities=on, condition_pushdown_for_derived=on, split_materialized=on, condition_pushdown_for_subquery=on, rowid_filter=on, condition_pushdown_from_having=on, not_null_range_scan=off, hash_join_cardinality=on, cset_narrowing=on, sargable_casefold=on	Now on by default: hash_join_cardinality, cset_narrowing, sargable_casefold. The engine_condition_pushdown flag was removed.
OPTIMIZER_ADJUST_SECONDARY_KEY_COSTS	fix_reuse_range_for_ref fix_card_multiplier	0	Deprecated and unused in 11.8 — its adjustments are built into the new cost model. Remove it from your configuration.
SESSION_TRACK_SYSTEM_VARIABLES	autocommit character_set_client character_set_connection character_set_results time_zone	autocommit character_set_client character_set_connection character_set_results redirect_url time_zone	Added redirect_url to the tracking list.

Read-only informational variables such as version, innodb_version, and have_ssl change their reported values after the upgrade (innodb_version no longer exists in 11.8), but they are not configuration options: they cannot be set in my.cnf in either version, so no configuration action is needed for them.

Deprecated Options

Option	Reason / Recommendation
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

Create a standalone configuration file to house these temporary reversion settings at /etc/my.cnf.d/rollback_compat.cnf

[mariadb]
# --- Core 10.6 Behavioral Reversion ---
character_set_server            = latin1
collation_server                = latin1_swedish_ci
explicit_defaults_for_timestamp = OFF
innodb_snapshot_isolation       = OFF

# --- Mandatory Metadata Compatibility (SME "Red" List) ---
# Prevents "Character set #2304" (utf8mb4_uca1400_ai_ci) errors on 10.6
character_set_collations        = ''

# Forces session metadata to legacy-compatible versions
collation_connection            = utf8mb3_general_ci
collation_database              = latin1_swedish_ci

# Standardizes log checksums for the 10.6 parser
binlog_checksum                 = CRC32

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 INSERT or UPDATE involving a VECTOR(N) column.

• New Functions: Use of VEC_Distance or other 11.8-specific SQL functions.

• Large Row Events: If binlog_row_event_max_size is 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. Simply 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

1

Isolate a 10.6 Node

Before upgrading your entire environment, identify one existing replica to remain on version 10.6. Stop the replication on this node just before you upgrade the Primary to 11.8.

2

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

3

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.

4

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 Version: SELECT VERSION(); should reflect the 11.8 GA series.

• Confirm Vector Search: Verify the new VECTOR(N) data type and conversion functions.

  CREATE TABLE test_vector (v VECTOR(3));
  SELECT VEC_ToText(VEC_FromText('[1,2,3]'));

• Verify Optimizer Performance: Prefix any SQL query with ANALYZE FORMAT=JSON on upgraded 11.8 instances to audit the new SSD-aware cost model:

  ANALYZE FORMAT=JSON SELECT * FROM orders WHERE total > 1000 AND status = 'shipped';

  The output pairs the optimizer's estimate for each table (cost, in optimizer cost units) with measured execution statistics such as r_total_time_ms and the r_engine_stats object (for example pages_accessed and pages_read_time_ms), so you can confirm the new cost model's estimates line up with actual I/O:

  "table": {
    "table_name": "orders",
    "access_type": "range",
    "cost": 4.12,
    "r_total_time_ms": 2.35,
    "r_engine_stats": {
      "pages_accessed": 142,
      "pages_read_time_ms": 1.05
    }
  }

• Check Replication Lag Fields: On a replica server, run SHOW REPLICA STATUS\G and look for the new Master_Slave_time_diff field.

_{This page is: Copyright © 2026 MariaDB. All rights reserved.}