System Design

MariaDB 13.1 Can Finally Validate a Config Before You Restart

A MariaDB configuration file being validated on the command line before the server restarts.

One transposed letter in my.cnf and a healthy database refuses to start. innodb_buffer_pool_size becomes innodb_buffer_pool_sze, you restart, and the service is down, always during an automated deploy or an upgrade or right as you were leaving, never during a calm maintenance window. MariaDB 13.1 Preview finally ships the obvious fix: mariadbd --validate-config, a dry run that reads the config, tells you whether it's acceptable, and exits without touching the running database. Credit to Frédéric Descamps for the writeup and Abdelrahman Hedia, who contributed the feature (MDEV-31527).

Here's what it does, where it genuinely helps, and the limits worth knowing before you lean on it.

The Problem It Solves

MariaDB reads config from a spread of files depending on OS and install method:

/etc/my.cnf
/etc/my.cnf.d/*.cnf
/etc/mysql/mariadb.conf.d/*.cnf

Convenient for layering package defaults under your own overrides, and also a great place for a mistake to hide. A misspelled variable, an option removed in a newer version, a value in the wrong format, or a setting dropped into a section mariadbd actually reads, any of them can sit unnoticed in one file out of several.

Until now the reliable way to find out was to restart and watch. That isn't validation, it's testing in production. On a box serving live traffic, "restart and see" is a coin flip on an outage.

The Feature

mariadbd --validate-config

It reads the configuration mariadbd would normally use, processes the server options, and exits instead of opening the database. No client connections, no workload, no actual startup. Point it at a specific file:

mariadbd --defaults-file=/tmp/my.cnf --validate-config

A clean config ends with [Note] Configuration is valid and exit code 0. A typo like max_conections (missing an n) gets you:

[ERROR] unknown variable 'max_conections=250'
[ERROR] Aborting

and a non-zero exit. That exit code is the whole point, because it's what makes the check scriptable.

Validate Before Restart

The change to your deploy flow is small and the payoff is an outage you don't have. From "edit, restart, hope" to "edit, validate, restart only if valid":

#!/bin/bash
set -e
MARIADBD=/usr/sbin/mariadbd
CONFIG=/etc/mysql/my.cnf

if ! "$MARIADBD" --defaults-file="$CONFIG" --validate-config; then
    echo "Config validation failed. Not restarting MariaDB."
    exit 1
fi

systemctl restart mariadb

⚠️ One caveat the announcement glosses over: --validate-config validates the config mariadbd resolves, which on a real server means the whole layered set of files, not just the one you edited. If you pass --defaults-file you're testing that file in isolation, which may not match what the server actually loads from /etc/my.cnf.d/ and friends. To validate what will really be loaded, run it without --defaults-file so it walks the same file precedence the server does. Test the isolated candidate file first to catch typos, then test the merged reality before you restart. They're two different questions and you want both answered.

The Config-Management Angle

This is where it earns its place for anyone running Ansible, and it plugs a real gap. The standard template-copy-notify-restart flow has a hole: the handler restarts the service even when the rendered template contains an invalid option, so a bad variable in your Jinja template takes down the database on the next converge. The safer shape:

Render the candidate config to a .candidate path, not the live file.
Validate it with the target mariadbd binary.
Install it over the active file only if validation passes.
Then notify the restart handler.

If you already use Ansible's validate parameter on the template/copy modules for sshd or sudoers (where a bad file can lock you out), this is the same discipline for MariaDB, and it's the pattern I lean on throughout the Terraform and Ansible IaC work: never let a config-management run push a file the target service can't actually parse. The validate step turns a converge that would've caused an outage into a converge that fails loudly and safely with the old config still running.

⚠️ Version-match the binary. Validate against the mariadbd that will actually run the config, not whatever's on your control node. A config valid for 10.11 may use an option removed in 13.1, and validating with the wrong binary gives you a false pass.

Containers and the Crash Loop

Containers are where an invalid config is most miserable, because the failure mode is a crash loop: start, mariadbd fails on the bad option, container exits, orchestrator restarts it, fails again, forever, while you dig through logs to find the one bad line. An entrypoint can validate the generated config before the real exec:

#!/bin/sh
set -e
generate_mariadb_config
mariadbd --defaults-file=/etc/mysql/my.cnf --validate-config
exec mariadbd --defaults-file=/etc/mysql/my.cnf

Now a bad ConfigMap or a botched env-var substitution fails at the validation step with a clear error, instead of a CrashLoopBackOff you have to reverse-engineer. If you run MariaDB or Galera on Proxmox or k8s, this is worth building into the image, and it pairs with the broader container isolation and image-hardening practices that keep a database container predictable.

The Upgrade Use Case Is the Best One

The single most valuable application: dry-running your current config against a newer MariaDB binary before you commit to the upgrade. Options get removed, renamed, or have their accepted values changed between major versions, and normally you discover that when the upgraded server refuses to start, mid-maintenance, with the old one already stopped.

/path/to/mariadb-13.1/bin/mariadbd --defaults-file=/etc/mysql/my.cnf --validate-config

Run that against the new binary while the old server is still happily serving traffic, fix whatever it flags, and the actual upgrade becomes far less of a gamble. This is exactly the pre-flight check that would have saved grief in more than one database migration, the same "verify before you cut over" instinct behind the CentOS-to-Ubuntu and cPanel-to-DirectAdmin migration work where an unexpected config incompatibility mid-cutover is the thing that turns a two-hour window into a six-hour one.

What It Does Not Do

⚠️ Set expectations correctly or you'll trust it too far. --validate-config answers exactly one question: can this MariaDB binary understand and accept this configuration? It checks that options exist, are spelled right, and have acceptable value formats. It does not:

tell you the config is good for your workload (a valid innodb_buffer_pool_size=64G on a 4GB box passes validation and then OOMs on start);
catch semantic or runtime problems (a path that doesn't exist yet, a port already in use, a permission the datadir lacks);
validate SQL-level or plugin-level behavior that only surfaces once the engine initializes fully.

It's a syntax-and-known-options gate, not a correctness or safety check. Enormously useful for catching the typo that causes 90% of failed restarts, useless for catching a value that's syntactically fine and operationally catastrophic. Treat it as the first gate, not the only one.

⚠️ And note it's a Preview feature in 13.1 right now, so the exact behavior may shift before the stable release. Fine to build into test automation and upgrade rehearsals today, but pin your expectations to "this may change" until 13.1 goes stable.

Bottom Line

--validate-config is a small addition with outsized operational value: it converts the most common cause of a failed MariaDB restart, a typo or a stale option, from a production outage into a caught error and a non-zero exit code. Wire it into your restart scripts, your Ansible converges (validate the candidate before installing it), your container entrypoints, and especially your upgrade rehearsals where dry-running the old config against the new binary is the cheapest insurance you'll buy all quarter. Just remember what it is: a gate that confirms MariaDB can parse the file, not that the settings are wise. Pair it with actual review for the values that matter, and let it kill the dumb typos before they kill your uptime.