Use wsrep_sst_mysqldump Safely for a MariaDB SST

Someone spots wsrep_sst_mysqldump in a config file and assumes it is just a scheduled dump, but it is a Galera SST that can block your donor. This guide walks through deciding whether it is the right method here, then checks a real donor and joiner before anything runs.

• Time: about 20 minutes for preparation, plus however long the dataset takes to transfer.
• You need: access to the donor and joiner hosts, MariaDB administration privileges, a healthy Galera configuration, and a tested recovery plan.
• Version: the examples use MariaDB Server package 10.11.14, where the installed man page identifies the tool as MariaDB 10.11.

1. Confirm what the command is

Read the local manual page first:

$ man wsrep_sst_mysqldump

On the installed release, the page is deliberately short. It describes wsrep_sst_mysqldump as a mysqldump-based state snapshot transfer and points to the MariaDB Knowledge Base. That means its useful interface is the Galera SST contract, not a set of interactive command-line options.

Check the installed files and package version:

$ command -v wsrep_sst_mysqldump
/usr/bin/wsrep_sst_mysqldump
$ dpkg-query -W -f='${Package} ${Version}\n' mariadb-server
mariadb-server 1:10.11.14-0ubuntu0.24.04.1

The helper is a shell script supplied by the mariadb-server package. It calls the installed MariaDB client and dump utilities after Galera has supplied its role, address, socket and state information.

2. Check whether a logical SST is the right trade-off

mysqldump SST is the logical transfer method. MariaDB's current Galera documentation describes it as requiring the joiner to be initialised and ready to accept connections, and as blocking the donor for the transfer. It is also the slowest SST method for a large cluster dataset.

• Use it when the constraints are acceptable, such as a small dataset or a controlled recovery window.
• Compare the physical method first for anything larger. For a bigger or busier cluster, check the supported physical method for your MariaDB release, normally mariadb-backup, before changing anything.

Do not select this method merely because the name resembles mariadb-dump. The SST helper is launched by the server's WSREP integration. It is not a replacement for an operator-created backup, and it does not make an arbitrary standalone dump safe for cluster recovery.

3. Verify the donor and joiner before the transfer

Check both nodes using your normal MariaDB administrative connection. The exact output depends on the cluster, but you need a donor that is serving the primary component and a joiner that is genuinely the node requesting the transfer:

SHOW GLOBAL STATUS LIKE 'wsrep_cluster_status';
SHOW GLOBAL STATUS LIKE 'wsrep_local_state_comment';
SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_method';

• Cluster status should be Primary on a healthy donor. A node is not ready just because the MariaDB process accepts a connection: confirm the WSREP state and intended SST method in the server logs too.
• Check the network path and endpoint. The helper requires a distinct destination address and port. The installed script rejects a destination that resolves to the donor's own local address and port, because that would send the transfer back to the source.
• Handle authentication with care. The SST setup supplies a database user and password to the helper. Never paste a real password into a shell command, a ticket, or a public configuration example. Use the documented protected MariaDB configuration and file permissions for your deployment, then verify the joiner can authenticate before arranging a transfer.

4. Check the client tools and compatibility

The installed helper checks the MariaDB client version before it starts the dump. Confirm the tools it will find:

$ command -v mariadb mariadb-dump
/usr/bin/mariadb
/usr/bin/mariadb-dump
$ mariadb-dump --version
mariadb-dump  Ver 10.19 Distrib 10.11.14-MariaDB, for debian-linux-gnu (x86_64)

The script accepts a client version of MariaDB 10.1 or newer, or a sufficiently recent MySQL client according to its version check. Keep the client and server packages from a compatible installation; do not quietly substitute a dump binary from another host.

Running the helper by itself is not a useful dry run. With no SST environment it fails while initialising the common WSREP helper, before a transfer can be meaningfully tested:

$ env -i PATH=/usr/bin:/bin /usr/bin/wsrep_sst_mysqldump
/usr/bin/wsrep_sst_common: ...: WSREP_SST_OPT_PATH: unbound variable
$ printf '%s\n' "$?"
1

The line number can vary with the package build. This is an expected boundary check, not evidence that the installed package is broken. Let Galera invoke the script with its complete SST environment.

5. Understand what the helper changes during an SST

Before dumping, the installed script connects to the joiner and inspects binary logging, server version and GTID state. In the normal non-bypass path it temporarily disables WSREP for the SQL it sends, disables the general and slow query logs while the dump is loaded, and uses the dump client with all databases, events, quick reads and table-drop statements.

Those details explain the safety boundary:

• This is cluster state movement, not an isolated read-only export.
• The dump is destructive on load, including statements such as DROP DATABASE and DROP TABLE.
• Binary logs can be reset on a binary-logging joiner, along with GTID state, as part of the transfer.
• Query-log restoration is best-effort. The script tries to restore the general and slow query log settings after loading the dump, but a failed or interrupted transfer still needs operator inspection.

6. Start and verify the transfer through Galera

Once the checks pass, use your cluster's normal controlled action to make the joiner request state transfer. Do not invoke the helper with invented flags. Watch the MariaDB error log on both nodes and retain the timestamp, donor, joiner and transfer method.

$ journalctl -u mariadb --since '10 minutes ago' --follow

Look for the WSREP state transition and the helper's completion message. After the transfer, verify the joiner from a MariaDB session:

SHOW GLOBAL STATUS LIKE 'wsrep_local_state_comment';
SHOW GLOBAL STATUS LIKE 'wsrep_ready';
SHOW GLOBAL STATUS LIKE 'wsrep_cluster_size';

The expected result is a synced joiner with wsrep_ready set to ON, but use the exact state names and values from your MariaDB release and cluster policy. Compare representative database counts or application health checks with the donor. A successful script exit is not a substitute for checking that the application sees the expected data.

If the transfer fails, leave the joiner out of service, save both error logs, and identify whether the failure was authentication, connectivity, client compatibility, donor availability or data loading. Do not repeatedly retry against a partially understood state. Recover by following the cluster's documented joiner reinitialisation procedure, or restore the joiner from the separate backup you prepared.