Regular MariaDB replication is asynchronous, but MariaDB also provides a semisynchronous replication option.

In MariaDB 10.3 and later, semisynchronous replication is built into the server, so it can be enabled immediately in those versions.

In MariaDB 10.2 and before, semisynchronous replication requires the user to install a plugin on both the master and the slave before it can be enabled.

Installing the Plugin

The semisynchronous replication plugin is actually two different plugins--one for the master, and one for the slave. Shared libraries for both plugins are included with MariaDB. Although the plugins' shared libraries distributed with MariaDB by default, the plugin is not actually installed by MariaDB by default prior to MariaDB 10.3.3. There are two methods that can be used to install the plugin with MariaDB.

The first method can be used to install the plugin without restarting the server. You can install the plugin dynamically by executing INSTALL SONAME or INSTALL PLUGIN.

For example, if it's a master:

INSTALL SONAME 'semisync_master';

Or if it's a slave:

INSTALL SONAME 'semisync_slave';

The second method can be used to tell the server to load the plugin when it starts up. The plugin can be installed this way by providing the --plugin-load or the --plugin-load-add options. This can be specified as a command-line argument to mysqld or it can be specified in a relevant server option group in an option file.

For example, if it's a master:

[mariadb]
...
plugin_load_add = semisync_master

Or if it's a slave:

[mariadb]
...
plugin_load_add = semisync_slave

Uninstalling the Plugin

You can uninstall the plugin dynamically by executing UNINSTALL SONAME or UNINSTALL PLUGIN.

For example, if it's a master:

UNINSTALL SONAME 'semisync_master';

Or if it's a slave:

UNINSTALL SONAME 'semisync_slave';

If you installed the plugin by providing the --plugin-load or the --plugin-load-add options in a relevant server option group in an option file, then those options should be removed to prevent the plugin from being loaded the next time the server is restarted.

Enabling Semisynchronous Replication

Semisynchronous replication can be enabled by setting the relevant system variables on the master and the slave.

If a server needs to be able to switch between acting as a master and a slave, then you can enable both the master and slave system variables on the server. For example, you might need to do this if MariaDB MaxScale is being used to enable auto-failover or switchover with MariaDB Monitor.

Enabling Semisynchronous Replication on the Master

Semisynchronous replication can be enabled on the master by setting the rpl_semi_sync_master_enabled system variable to ON. It can be set dynamically with SET GLOBAL. For example:

SET GLOBAL rpl_semi_sync_master_enabled=ON;

It can also be set in a server option group in an option file prior to starting up the server. For example:

[mariadb]
...
rpl_semi_sync_master_enabled=ON

Enabling Semisynchronous Replication on the Slave

Semisynchronous replication can be enabled on the slave by setting the rpl_semi_sync_slave_enabled system variable to ON. It can be set dynamically with SET GLOBAL. For example:

SET GLOBAL rpl_semi_sync_slave_enabled=ON;

It can also be set in a server option group in an option file prior to starting up the server. For example:

[mariadb]
...
rpl_semi_sync_slave_enabled=ON

If semisynchronous replication is enabled on a server when slave threads were already running, the slave I/O thread will need to be restarted to enable the slave to register as a semisynchronous slave when it connects to the master. For example:

STOP SLAVE IO_THREAD;
START SLAVE IO_THREAD;

If this is not done, and the slave thread is already running, then it will continue to use asynchronous replication.

Configuring the Master Timeout

In semisynchronous replication, only after the events have been written to the relay log and flushed does the slave acknowledge receipt of a transaction's events. If the slave does not acknowledge the transaction before a certain amount of time has passed, then a timeout occurs and the master switches to asynchronous replication. This will be reflected in the master's error log with messages like the following:

[Warning] Timeout waiting for reply of binlog (file: mariadb-1-bin.000002, pos: 538), semi-sync up to file , position 0.
[Note] Semi-sync replication switched OFF.

When this occurs, the Rpl_semi_sync_master_status status variable will be switched to OFF.

When at least one semisynchronous slave catches up, semisynchronous replication is resumed. This will be reflected in the master's error log with messages like the following:

[Note] Semi-sync replication switched ON with slave (server_id: 184137206) at (mariadb-1-bin.000002, 215076)

When this occurs, the Rpl_semi_sync_master_status status variable will be switched to ON.

The number of times that semisynchronous replication has been switched off can be checked by looking at the value of the Rpl_semi_sync_master_no_times status variable.

If you see a lot of timeouts like this in your environment, then you may want to change the timeout period. The timeout period can be changed by setting the rpl_semi_sync_master_timeout system variable. It can be set dynamically with SET GLOBAL. For example:

SET GLOBAL rpl_semi_sync_master_timeout=20000;

It can also be set in a server option group in an option file prior to starting up the server. For example:

[mariadb]
...
rpl_semi_sync_master_timeout=20000

To determine a good value for the rpl_semi_sync_master_timeout system variable, you may want to look at the values of the Rpl_semi_sync_master_net_avg_wait_time and Rpl_semi_sync_master_tx_avg_wait_time status variables.

Configuring the Master Wait Point

In semisynchronous replication, there are two potential points at which the master can wait for the slave acknowledge the receipt of a transaction's events. These two wait points have different advantages and disadvantages.

The wait point is configured by the rpl_semi_sync_master_wait_point system variable. The supported values are:

• AFTER_SYNC
• AFTER_COMMIT

It can be set dynamically with SET GLOBAL. For example:

SET GLOBAL rpl_semi_sync_master_wait_point='AFTER_SYNC';

It can also be set in a server option group in an option file prior to starting up the server. For example:

[mariadb]
...
rpl_semi_sync_master_wait_point=AFTER_SYNC

When this variable is set to AFTER_SYNC, the master performs the following steps:

1. Prepares the transaction in the storage engine.
2. Syncs the transaction to the binary log.
3. Waits for acknowledgement from the slave.
4. Commits the transaction to the storage engine.
5. Returns an acknowledgement to the client.

The effects of the AFTER_SYNC wait point are:

• All clients see the same data on the master at the same time; after acknowledgement by the slave and after being committed to the storage engine on the master.

• If the master crashes, then failover should be lossless, because all transactions committed on the master would have been replicated to the slave.

• However, if the master crashes, then its binary log may also contain events for transactions that were prepared by the storage engine and written to the binary log, but that were never actually committed by the storage engine. As part of the server's automatic crash recovery process, the server may recover these prepared transactions when the server is restarted. This could cause the crashed master to become inconsistent with the slaves. Therefore, the crashed master may need to be rebuilt. See MDEV-19733 for more information.

When this variable is set to AFTER_COMMIT, the master performs the following steps:

1. Prepares the transaction in the storage engine.
2. Syncs the transaction to the binary log.
3. Commits the transaction to the storage engine.
4. Waits for acknowledgement from the slave.
5. Returns an acknowledgement to the client.

The effects of the AFTER_COMMIT wait point are:

• Other clients may see the committed transaction before the committing client.

• If the master crashes, then failover may involve some data loss, because the master may have committed transactions that had not yet been acknowledged by the slaves.

Versions

System Variables

rpl_semi_sync_master_enabled

• Description: Set to ON to enable semi-synchronous replication master. Disabled by default.
• Commandline: --rpl-semi-sync-master-enabled[={0|1}]
• Scope: Global
• Dynamic: Yes
• Data Type: boolean
• Default Value: OFF

rpl_semi_sync_master_timeout

• Description: The timeout value, in milliseconds, for semi-synchronous replication in the master. If this timeout is exceeded in waiting on a commit for acknowledgement from a slave, the master will revert to asynchronous replication.
  • When a timeout occurs, the Rpl_semi_sync_master_status status variable will also be switched to OFF.
  • See Configuring the Master Timeout for more information.
• Commandline: --rpl-semi-sync-master-timeout[=#]
• Scope: Global
• Dynamic: Yes
• Data Type: numeric
• Default Value: 10000 (10 seconds)
• Range: 0 to 18446744073709551615

rpl_semi_sync_master_trace_level

• Description: The tracing level for semi-sync replication. Four levels are defined:
  • 1: General level, including for example time function failures.
  • 16: More detailed level, with more verbose information.
  • 32: Net wait level, including more information about network waits.
  • 64: Function level, including information about function entries and exits.
• Commandline: --rpl-semi-sync-master-trace-level[=#]
• Scope: Global
• Dynamic: Yes
• Data Type: numeric
• Default Value: 32
• Range: 0 to 18446744073709551615

rpl_semi_sync_master_wait_no_slave

• Description: If set to ON, the default, the slave count (recorded by Rpl_semi_sync_master_clients) may drop to zero, and the master will still wait for the timeout period. If set to OFF, the master will revert to asynchronous replication as soon as the slave count drops to zero.
• Commandline: --rpl-semi-sync-master-wait-no-slave[={0|1}]
• Scope: Global
• Dynamic: Yes
• Data Type: boolean
• Default Value: ON

rpl_semi_sync_master_wait_point

• Description: Whether the transaction should wait for semi-sync acknowledgement after having synced the binlog (AFTER_SYNC), or after having committed in storage engine (AFTER_COMMIT, the default).
  • When this variable is set to AFTER_SYNC, the master performs the following steps:
    1. Prepares the transaction in the storage engine.
    2. Syncs the transaction to the binary log.
    3. Waits for acknowledgement from the slave.
    4. Commits the transaction to the storage engine.
    5. Returns an acknowledgement to the client.
  • When this variable is set to AFTER_COMMIT, the master performs the following steps:
    1. Prepares the transaction in the storage engine.
    2. Syncs the transaction to the binary log.
    3. Commits the transaction to the storage engine.
    4. Waits for acknowledgement from the slave.
    5. Returns an acknowledgement to the client.
  • In MariaDB 10.1.2 and before, this system variable does not exist. However, in those versions, the master waits for the acknowledgement from slaves at a point that is equivalent to AFTER_COMMIT.
  • See Configuring the Master Wait Point for more information.
• Commandline: --rpl-semi-sync-master-wait-point=value
• Scope: Global
• Dynamic: Yes
• Data Type: enum
• Default Value: AFTER_COMMIT
• Valid Values: AFTER_SYNC, AFTER_COMMIT
• Introduced: MariaDB 10.1.3

rpl_semi_sync_slave_delay_master

• Description: Only write master info file when ack is needed.
• Commandline: --rpl-semi-sync-slave-delay-master[={0|1}]
• Scope: Global
• Dynamic: Yes
• Data Type: boolean
• Default Value: OFF
• Introduced: MariaDB 10.3.3

rpl_semi_sync_slave_enabled

• Description: Set to ON to enable semi-synchronous replication slave. Disabled by default.
• Commandline: --rpl-semi-sync-slave-enabled[={0|1}]
• Scope: Global
• Dynamic: Yes
• Data Type: boolean
• Default Value: OFF

rpl_semi_sync_slave_kill_conn_timeout

• Description: Timeout for the mysql connection used to kill the slave io_thread's connection on master. This timeout comes into play when stop slave is executed.
• Commandline: --rpl-semi-sync-slave-kill-conn-timeout[={0|1}]
• Scope: Global
• Dynamic: Yes
• Data Type: numeric
• Default Value: 5
• Range: 0 to 4294967295
• Introduced: MariaDB 10.3.3

rpl_semi_sync_slave_trace_level

• Description: The tracing level for semi-sync replication. The levels are the same as for rpl_semi_sync_master_trace_level.
• Commandline: --rpl-semi-sync-slave-trace_level[=#]
• Scope: Global
• Dynamic: Yes
• Data Type: numeric
• Default Value: 32
• Range: 0 to 18446744073709551615

Options

rpl_semi_sync_master

• Description: Controls how the server should treat the plugin when the server starts up.
  • Valid values are:
    • OFF - Disables the plugin without removing it from the mysql.plugins table.
    • ON - Enables the plugin. If the plugin cannot be initialized, then the server will still continue starting up, but the plugin will be disabled.
    • FORCE - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error.
    • FORCE_PLUS_PERMANENT - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error. In addition, the plugin cannot be uninstalled with UNINSTALL SONAME or UNINSTALL PLUGIN while the server is running.
  • See Plugin Overview: Configuring Plugin Activation at Server Startup for more information.
• Commandline: --rpl-semi-sync-master=value
• Data Type: enumerated
• Default Value: ON
• Valid Values: OFF, ON, FORCE, FORCE_PLUS_PERMANENT
• Removed: MariaDB 10.3.3

rpl_semi_sync_slave

• Description: Controls how the server should treat the plugin when the server starts up.
  • Valid values are:
    • OFF - Disables the plugin without removing it from the mysql.plugins table.
    • ON - Enables the plugin. If the plugin cannot be initialized, then the server will still continue starting up, but the plugin will be disabled.
    • FORCE - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error.
    • FORCE_PLUS_PERMANENT - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error. In addition, the plugin cannot be uninstalled with UNINSTALL SONAME or UNINSTALL PLUGIN while the server is running.
  • See Plugin Overview: Configuring Plugin Activation at Server Startup for more information.
• Commandline: --rpl-semi-sync-slave=value
• Data Type: enumerated
• Default Value: ON
• Valid Values: OFF, ON, FORCE, FORCE_PLUS_PERMANENT
• Removed: MariaDB 10.3.3

Status Variables

For a list of status variables added when the plugin is installed, see Semisynchronous Replication Plugin Status Variables.