Stop a Primary Node

This page is part of MariaDB's Documentation.

The parent of this page is: Start and Stop Services

Topics on this page:

Overview
Compatibility
Shut Down a Primary Server

Overview

In some cases, special care must be taken when shutting down a server when using MariaDB Replication.

Compatibility

MariaDB Enterprise Server 10.4
MariaDB Enterprise Server 10.5
MariaDB Enterprise Server 10.6

Shut Down a Primary Server

When a server is shutdown, it kills client threads in random order. By default, a primary server also considers its binary log dump thread to be a regular client thread. As a consequence, the binary log dump thread can potentially be killed before real client threads. If those real client threads are still writing data, then that data will not be replicated to the replica servers. This even applies to semi-synchronous replication.

In MariaDB Enterprise Server 10.4, MariaDB Community Server 10.4, and later versions, this problem can be solved by performing a replication-aware shutdown on the primary server. A replication-aware shutdown is performed with the MariaDB Admin command-line client or with the SHUTDOWN statement.

Starting in MariaDB Enterprise Server 10.5, the server can be configured to perform replication-aware shutdowns by default by configuring the shutdown_wait_for_slaves system variable.

When replication-aware shutdown is performed, the primary server only kills its binary log dump threads after all real client threads have been killed, and it only completes the shutdown after the last binary log has been sent to all connected replica servers.

In older versions where replication-aware shutdowns are not supported, it is recommended to manually switchover replica servers to a new primary server before shutting down the old primary server.

Dynamically Enable Replication-Aware Shutdowns

Starting in MariaDB Enterprise Server 10.5, the server can be configured to perform replication-aware shutdowns by default by configuring the shutdown_wait_for_slaves system variable. To ensure that the change survives server restarts, the change should also be made in a configuration file.

Connect to the server using MariaDB Client as the root@localhost user account or another user account with the SUPER privilege:
```
$ sudo mariadb
```
Set the shutdown_wait_for_slaves system variable to ON using the SET GLOBAL statement.

For example:
```
SET GLOBAL shutdown_wait_for_slaves=ON;
```
Choose a configuration file in which to configure the shutdown_wait_for_slaves system variable.

MariaDB recommends creating a custom configuration file in one of the included directories instead of making custom changes to one of the bundled configuration files. Configuration files in included directories are read in alphabetical order. To make your custom configuration file override the bundled configuration files, prefix the custom configuration file's name with a string that will be sorted last, such as z-.
- On RHEL, CentOS, and SLES, a good custom configuration file would be: /etc/my.cnf.d/z-custom-my.cnf
- On Debian and Ubuntu, a good custom configuration file would be: /etc/mysql/mariadb.conf.d/z-custom-my.cnf
Set the shutdown_wait_for_slaves system variable in the configuration file.

It needs to be set in a group that will be read by MariaDB Server, such as [mariadb] or [server].

For example:
```
[mariadb]
...
shutdown_wait_for_slaves=ON
```

Configure Replication-Aware Shutdowns

Starting in MariaDB Enterprise Server 10.5, the server can be configured to perform replication-aware shutdowns by default by configuring the shutdown_wait_for_slaves system variable.

Choose a configuration file in which to configure the shutdown_wait_for_slaves system variable.

MariaDB recommends creating a custom configuration file in one of the included directories instead of making custom changes to one of the bundled configuration files. Configuration files in included directories are read in alphabetical order. To make your custom configuration file override the bundled configuration files, prefix the custom configuration file's name with a string that will be sorted last, such as z-.
- On RHEL, CentOS, and SLES, a good custom configuration file would be: /etc/my.cnf.d/z-custom-my.cnf
- On Debian and Ubuntu, a good custom configuration file would be: /etc/mysql/mariadb.conf.d/z-custom-my.cnf
Set the shutdown_wait_for_slaves system variable in the configuration file.

It needs to be set in a group that will be read by MariaDB Server, such as [mariadb] or [server].

For example:
```
[mariadb]
...
shutdown_wait_for_slaves=ON
```
Restart the server. You can avoid the need to restart by dynamically enabling replication-aware shutdowns:
```
$ sudo systemctl restart mariadb
```

Perform a Replication-Aware Shutdown with MariaDB Admin

On the primary server that is being shutdown, use the MariaDB Admin command-line client as the root@localhost user account or another user account with the SUPER privilege to shut down the server with the --wait-for-all-slaves option:
```
$ sudo mariadb-admin --wait-for-all-slaves shutdown
```

Perform a Replication-Aware Shutdown with SHUTDOWN

Connect to the primary server using MariaDB Client as the root@localhost user account or another user account with the SUPER privilege:
```
$ sudo mariadb
```
Execute the SHUTDOWN statement to shut down the server with the WAIT FOR ALL SLAVES option:
```
SHUTDOWN WAIT FOR ALL SLAVES;
```