MariaDB 13.1 Feature in Focus: Validate Your Configuration Before Starting the Server

Have you ever modified a MariaDB configuration file, restarted the service, and immediately regretted it?

You wanted to change:

innodb_buffer_pool_size=16G

but accidentally wrote:

innodb_buffer_pool_sze=16G

One missing letter.

That is enough to turn a perfectly healthy database server into a service that refuses to start.

And of course, this kind of mistake never happens during a quiet maintenance window when everybody is available.

It happens during an automated deployment.
It happens during an upgrade.
It happens on a remote server.
Or it happens just before you planned to leave for dinner.

With MariaDB 13.1 Preview, we finally have a simple way to catch this kind of problem before restarting the database:

mariadbd --validate-config

Let’s take a closer look at this new feature.

The problem

MariaDB Server reads its configuration from several possible files and directories.

Depending on the operating system and installation method, you may have files such as:

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

This is very convenient.

We can keep server settings in separate files, let packages provide defaults, and manage our own configuration independently.

But it also means that a configuration error may be hidden somewhere in a collection of files.

The error could be:

• a misspelled variable;
• an option that no longer exists;
• a value using the wrong format;
• a setting that is valid in one MariaDB version but not another;
• or an option accidentally placed in a section read by mariadbd.

Until now, the most reliable validation method was often to start the server and see what happened.

That is not really validation.
That is testing in production.

The feature

MariaDB 13.1 introduces the --validate-config option.

It asks mariadbd to read and validate its configuration without continuing with a normal server startup. The feature was developed for MDEV-31527 and contributed by Abdelrahman Hedia.

The basic command is very simple:

mariadbd --validate-config

MariaDB reads the configuration it would normally use, processes the server options, and exits instead of opening the database for normal operation.

No client connections.
No production workload.
No actual database service startup.
Just configuration validation.

A valid configuration

Let’s start with a small configuration file:

[mariadb]
port=3306
max_connections=250
innodb_buffer_pool_size=1G

We can validate it using:

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

When the configuration is valid, the command completes successfully without starting the server:

2026-07-20  8:21:34 0 [Note] Starting MariaDB 13.1.0-MariaDB source
              revision 91f37a32f3ee463bdb8287ef951170b5f64201e0 server_uid
              VN4jfqgscGMaAzZFqoXFEGyvkSk= as process 99568
2026-07-20  8:21:34 0 [Note] Help others discover MariaDB. 
              Star it on GitHub: https://github.com/MariaDB/server
2026-07-20  8:21:34 0 [Note] Plugin 'FEEDBACK' is disabled.
2026-07-20  8:21:34 0 [Note] Configuration is valid.

We can also check the return code:

echo $?

A successful validation can then be used by a shell script, configuration-management system, container entrypoint, or CI/CD pipeline.

Conceptually:

if mariadbd --defaults-file=/tmp/my.cnf --validate-config
then
    echo "MariaDB configuration is valid"
else
    echo "MariaDB configuration is invalid"
    exit 1
fi

Catching a typo

Now let’s introduce a very realistic mistake:

[mariadb]
port=3306
max_conections=250
innodb_buffer_pool_size=1G

Did you notice it?

We wrote:

max_conections

instead of:

max_connections

Without validation, that typo might only be discovered when the service is restarted.

With MariaDB 13.1, we can test the file first:

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

MariaDB reports the unknown option and returns an error instead of attempting a normal server startup:

2026-07-20  8:24:16 0 [Note] Starting MariaDB 13.1.0-MariaDB source
             revision 91f37a32f3ee463bdb8287ef951170b5f64201e0 server_uid 
             VzioTnZyGSbQeYXk2etx7gOyuMQ= as process 100843
2026-07-20  8:24:16 0 [Note] Help others discover MariaDB. 
             Star it on GitHub: https://github.com/MariaDB/server
2026-07-20  8:24:16 0 [Note] Plugin 'FEEDBACK' is disabled.
2026-07-20  8:24:16 0 [ERROR] ../../opt/13.1.0/bin/mariadbd: 
             unknown variable 'max_conections=250'
2026-07-20  8:24:16 0 [ERROR] Aborting

This changes the deployment flow from:

⤍ modify configuration
⤍ restart MariaDB
⤍ hope

to:

⤍ modify configuration
⤍ validate configuration
⤍ restart MariaDB only when validation succeeds

Validate before restarting

A simple maintenance script could look like this:

#!/bin/bash

set -e

MARIADBD=/usr/sbin/mariadbd
CONFIG=/etc/mysql/my.cnf

echo "Validating MariaDB configuration..."

if ! "$MARIADBD" \
       --defaults-file="$CONFIG" \
       --validate-config
then
    echo "Configuration validation failed."
    echo "MariaDB will not be restarted."
    exit 1
fi

echo "Configuration is valid."
echo "Restarting MariaDB..."

systemctl restart mariadb

The key idea is simple: don’t restart MariaDB unless the configuration is valid.

Configuration management

This is also useful with tools such as Ansible, Puppet, Chef, or Salt.

A traditional configuration-management workflow may:

1. render a configuration template;
2. copy it to the server;
3. notify the MariaDB service;
4. restart MariaDB.

The problem is that the notification may restart the service even when the rendered configuration contains an invalid option.

A safer workflow is:

1. render the candidate configuration;
2. validate it with the target MariaDB binary;
3. install it only when validation succeeds;
4. restart or reload the service.

For example, the candidate file could first be generated as:

/etc/mysql/mariadb.conf.d/90-custom.cnf.candidate

Then validated using a temporary main configuration file or an isolated configuration directory.

Only after successful validation would it replace the active file.

Containers

The feature is especially interesting for containers.

A container often receives its MariaDB configuration from:

• a mounted configuration file;
• a Kubernetes ConfigMap;
• a generated template;
• environment-variable processing;
• or an entrypoint script.

When the configuration is invalid, the normal result is a crash loop:

⤍ start container
⤍ mariadbd fails
⤍ container exits
⤍ orchestrator restarts it
⤍ mariadbd fails again

With --validate-config, an entrypoint can check the generated configuration before attempting the real startup:

#!/bin/sh

set -e

generate_mariadb_config

mariadbd \
  --defaults-file=/etc/mysql/my.cnf \
  --validate-config

exec mariadbd \
  --defaults-file=/etc/mysql/my.cnf

Upgrades

Another very good use case is preparing an upgrade.

Imagine that you are moving from an older MariaDB release to MariaDB 13.1.

Your existing configuration may contain settings that:

• were removed;
• were renamed;
• changed accepted values;
• or are no longer relevant.

Instead of discovering those problems during the actual upgrade, you can validate the configuration using the new MariaDB binary beforehand:

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

This allows you to fix issues before stopping the current server.

CI/CD

Configuration files are code.

They are stored in Git.

They are reviewed.

They are templated.

They are deployed automatically.

So why shouldn’t they be tested automatically too?

A pipeline can validate every proposed configuration change:

mariadbd \
  --defaults-file="$CI_PROJECT_DIR/config/my.cnf" \
  --validate-config

A typo never reaches production.

What does it validate?

--validate-config validates the server configuration as MariaDB processes it during initialization.

It is useful for detecting problems such as unknown or invalid server options.

However, it does not guarantee that a configuration is optimal or safe for your workload.

It answers a simple but important question:

Can this MariaDB binary understand and accept this configuration?

Preview means preview

At the time of writing, MariaDB 13.1 is a Preview release.

This means the feature is available for testing and feedback, but it may still evolve before the final release.

So try it, test it with your automation. Test it with your upgrade procedures.

And report any issues you encounter.

Conclusion

--validate-config is a small addition, but it has a big operational impact.

It allows you to validate configuration files before restarting MariaDB, reducing the risk of outages caused by simple mistakes.

Whether you are managing servers manually, using configuration management, running containers, or building CI/CD pipelines, this feature can make your life easier.

And that’s exactly what we want from MariaDB 13.1.

Don’t forget that you can also see where a configuration variable was set; this is explained here.

Enjoy MariaDB Server!