Shutting Down a Server with MariaDB Replication

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

Shutting 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.

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 Enabling Replication-Aware Shutdowns

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.

  1. Connect to the server using MariaDB Client as the root@localhost user account or another user account with the SUPER privilege:

    $ sudo mariadb
    
  2. Set the shutdown_wait_for_slaves system variable to the new size using the SET GLOBAL statement.

    For example:

    SET GLOBAL shutdown_wait_for_slaves=ON;
    
  3. Choose a configuration file in which to configure the shutdown_wait_for_slaves system variable.

    It not recommended to make custom changes to one of the bundled configuration files. Instead, it is recommended to create a custom configuration file in one of the included directories. Configuration files in included directories are read in alphabetical order. If you want your custom configuration file to override the bundled configuration files, then it is a good idea to 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

  4. 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
    

Configuring Replication-Aware Shutdowns

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.

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

    It not recommended to make custom changes to one of the bundled configuration files. Instead, it is recommended to create a custom configuration file in one of the included directories. Configuration files in included directories are read in alphabetical order. If you want your custom configuration file to override the bundled configuration files, then it is a good idea to 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

  2. 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
    
  3. Restart the server. You can avoid the need to restart by dynamically enabling replication-aware shutdowns.

    To restart the server on operating systems that use systemd:

    $ sudo systemctl restart mariadb
    

    On systems that use Upstart:

    $ sudo service mysql restart
    

Performing a Replication-Aware Shutdown with MariaDB Admin

  1. 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
    

Performing a Replication-Aware Shutdown with SHUTDOWN

  1. Connect to the primary server using MariaDB Client as the root@localhost user account or another user account with the SUPER privilege:

    $ sudo mariadb
    
  2. Execute the SHUTDOWN statement to shut down the server with the WAIT FOR ALL SLAVES option:

    SHUTDOWN WAIT FOR ALL SLAVES;