Patch, Innovation, and LTS Upgrade Planning with Release Notes and Deprecations

Learning outcomes

ServiceHub runs a supported MariaDB release, several connectors, a backup tool, and one optional plugin. A security fix lands while a new LTS is also available. The dangerous question is “what is the latest version?” The useful question is “what exact source → target transition is supported for this topology, and what evidence must survive it?” A maintenance update inside one release series is operationally different from a release-series upgrade.

1. Classify the change before designing the runbook

Maturity must come from official release notes, not from the numerical distance between versions. “12.3” does not mean “riskier than 11.8” merely because the number is larger; likewise “LTS” does not remove the need for testing.

2. Inventory everything that can break independently

SELECT VERSION() AS server_version, @@version_comment AS product_comment,       @@version_compile_machine AS arch, @@version_compile_os AS os;SHOW ENGINES;SELECT PLUGIN_NAME, PLUGIN_VERSION, PLUGIN_STATUS, PLUGIN_TYPEFROM information_schema.PLUGINSORDER BY PLUGIN_TYPE, PLUGIN_NAME;SHOW VARIABLES WHERE Variable_name IN('sql_mode','character_set_server','collation_server','log_bin','binlog_format','gtid_strict_mode','wsrep_on');

mariadb --versionmariadb-backup --versionmariadb-upgrade --version# Linux examples only; use your platform package manager.dpkg -l | grep -Ei 'mariadb|galera' || truerpm -qa | grep -Ei 'mariadb|galera' || true# Application repos:npm list mariadb || truepython -m pip show mariadb || true

The same server upgrade can be safe on one host and unsafe on another because an authentication plugin, storage engine, backup binary or OS repository differs. Treat the inventory as an artifact committed to the change ticket.

3. Build the upgrade matrix from official evidence

Release notes are input to a decision, not the decision itself. Convert each incompatible change into a concrete probe: a config-start test, schema dump/restore, representative query, connector integration test, replication check, or benchmark.

4. Wrong approach: “upgrade because the package manager offers it”

A real failure mode is changing the repository, running a general OS update, and discovering only at restart that an option was removed or a plugin package no longer exists. The repair is a pinned target, preflight diff, tested package transaction, backup, and rollback plan.

# Do not execute production upgrades blindly.# First capture effective configuration and package candidates.mariadbd --help --verbose > mariadbd-effective-help.txt 2>&1 || true# Inspect package-manager candidate versions without installing them.apt-cache policy mariadb-server 2>/dev/null || truednf list --showduplicates MariaDB-server 2>/dev/null || true# Compare option files in version control before the maintenance window.

5. Define rollback before the first irreversible step

Rollback is not “reinstall the old binary.” After the new server writes data, system tables or on-disk structures, downgrade may be unsupported. A safe rollback plan may instead be: preserve an untouched old-version replica, restore a tested backup to old binaries, or fail back before promotion while the old primary is still authoritative. Name the point after which rollback becomes restore/migration rather than binary reversal.

6. Local lab: produce an upgrade decision record

component,current,target,evidence,go_no_goserver,11.8.x,12.3.2,release-notes+lab-start,GO-after-testbackup-tool,11.8.x,12.3.2,matching-package+restore-drill,GOconnector-node,recorded,recorded,app-integration-suite,GO-or-upgradeplugin-X,installed,unknown,target-package-check,HOLDconfig,git-sha-A,git-sha-B,removed-options-test,GO-after-edit

Use your actual versions. Add one row for every storage engine, authentication plugin, proxy/orchestrator, and HA component. The lab succeeds only when every “unknown” becomes evidence or an explicit block.

Production judgment and bridge to Lesson 2

Do not schedule the maintenance window until the target, package sources, dependencies, backup/restore path, config changes, HA order, rollback boundary and acceptance gates are explicit. Lesson 2 moves from planning into the server transition itself: starting the new binaries, running mariadb-upgrade where required, reconciling system metadata and proving that the upgraded instance is actually healthy.

Build an upgrade dossier before touching packages

An upgrade plan is strongest when it is an evidence packet for one exact source-to-target transition. Record the current MariaDB server series and maintenance release, package source, operating system, architecture, active storage engines/plugins, Galera provider if present, backup utility version, client/connectors, replication peers, proxy/router, and important global configuration. Then record the proposed target for each component. This prevents a common failure mode: reviewing server release notes while an incompatible plugin, connector, repository package, or Galera provider remains invisible until restart.

Separate three questions. First, must we change? Security/support status and a required defect fix may create urgency. Second, may we change? The target must support every engine/plugin/topology and application dependency. Third, are we ready? Backups, restore testing, canary capacity, maintenance communication, rollback boundaries, and performance baselines determine operational readiness. A green answer to only one of these questions is not an approval.

Read release notes cumulatively. If the source and target span multiple release series, inspect incompatible changes, removed/deprecated options, default changes, reserved words, authentication changes, optimizer behavior, InnoDB/replication/Galera notes, and client/tool changes for every relevant intermediate series even when a direct standalone upgrade path is supported. Translate each discovered item into a test or configuration action rather than leaving it as prose in a checklist.

• Configuration gate: every startup option is recognized by the target and its effective value is verified after boot.
• Data gate: engines, tables, collations, generated objects, routines/events/triggers, and system schema have a supported path.
• Topology gate: source/target version coexistence and upgrade order are explicitly supported for the chosen async/Galera design.
• Application gate: critical queries, connectors, migrations, auth, and failover behavior pass target-version tests.
• Recovery gate: a pre-change backup and a tested restore path exist outside the data directory being modified.

Finally, write the rollback boundary. Before the new binary touches on-disk/system metadata, rollback may be package/config restoration. After system-table or other irreversible transformations, rollback often means restoring the pre-upgrade backup or failing back to an untouched node—not simply reinstalling the old binary. That distinction belongs in the change ticket before maintenance begins.

Rehearsal artifact: convert release-note findings into executable acceptance tests

A release-note review is only useful if each material finding changes the rehearsal. If a variable was removed, start a disposable target with the old option and prove whether startup rejects or ignores it, then update the configuration and verify the effective value. If a collation, reserved word, authentication plugin, optimizer rule, or storage-engine capability changed, create a focused fixture that exercises that dependency. Store the command, expected result, actual result, and target build with the change record. This turns “we read the notes” into evidence another operator can repeat.

Include non-database dependencies in the same rehearsal. Run the exact connector major/minor version, migration framework, backup binary, monitoring queries, and automation scripts against the target. Verify service-manager behavior and option-file include paths on the target operating-system packages. Where a topology is involved, rehearse the supported coexistence window rather than testing only isolated nodes.

Approve the upgrade only when every exception has an owner and disposition: fixed before change, explicitly accepted with monitoring, or blocked. A waived issue should state what signal would trigger rollback. This discipline prevents a long release-note document from becoming a ceremonial attachment that nobody can connect to runtime behavior.

Authoritative references

• MariaDB Server Documentation — Upgrading MariaDB and version-specific upgrade guides.
• MariaDB Release Notes / Downloads / Support Policy.
• MariaDB documentation for mariadb-backup, Galera and connectors used by the deployment.