20.9.1 Group Replication System Variables

Skip to Main Content

MySQL 8.4 Reference Manual Including MySQL NDB Cluster 8.4

20.9.1 Group Replication System Variables

This section lists the system variables that are specific to the Group Replication plugin.

The name of each Group Replication system variable is prefixed with group_replication_.

Note

InnoDB Cluster uses Group Replication, but the default values of the Group Replication system variables may differ from the defaults documented in this section. For example, in InnoDB Cluster, the default value of group_replication_communication_stack is MYSQL, not XCOM as it is for a default Group Replication implementation.

For more information, see MySQL InnoDB Cluster.

Some system variables on a Group Replication group member, including some Group Replication-specific system variables and some general system variables, are group-wide configuration settings. These system variables must have the same value on all group members, and require a full reboot of the group (a bootstrap by a server with group_replication_bootstrap_group=ON) in order for the value change to take effect. For instructions to reboot a group where every member has been stopped, see Section 20.5.2, “Restarting a Group”.

If a running group has a value set for a group-wide configuration setting, and a joining member has a different value set for that system variable, the joining member cannot join the group until the value is changed to match. If the group has a value set for one of these system variables, and the joining member does not support the system variable, it cannot join the group.

The following system variables are group-wide configuration settings:

• group_replication_single_primary_mode
• group_replication_enforce_update_everywhere_checks
• group_replication_gtid_assignment_block_size
• group_replication_view_change_uuid (deprecated)
• group_replication_paxos_single_leader
• group_replication_communication_stack (a special case not policed by Group Replication's own checks; see the system variable description for details)
• default_table_encryption
• lower_case_table_names

Group-wide configuration settings cannot be changed by the usual methods while Group Replication is running, but it is possible to use the group_replication_switch_to_single_primary_mode() and group_replication_switch_to_multi_primary_mode() functions to change the values of group_replication_single_primary_mode and group_replication_enforce_update_everywhere_checks while the group is still running. For more information, see Section 20.5.1.2, “Changing the Group Mode”.

Most system variables for Group Replication can have different values on different group members. For the following system variables, it is advisable to set the same value on all members of a group in order to avoid unnecessary rollback of transactions, failure of message delivery, or failure of message recovery:

• group_replication_auto_increment_increment
• group_replication_communication_max_message_size
• group_replication_compression_threshold
• group_replication_message_cache_size
• group_replication_transaction_size_limit

The value of group_replication_preemptive_garbage_collection must be the same on all group members.

Most system variables for Group Replication are described as dynamic, and their values can be changed while the server is running. However, in most cases, the change takes effect only after you stop and restart Group Replication on the group member using a STOP GROUP_REPLICATION statement followed by a START GROUP_REPLICATION statement. Changes to the following system variables take effect without stopping and restarting Group Replication:

• group_replication_advertise_recovery_endpoints
• group_replication_autorejoin_tries
• group_replication_consistency
• group_replication_exit_state_action
• group_replication_flow_control_applier_threshold
• group_replication_flow_control_certifier_threshold
• group_replication_flow_control_hold_percent
• group_replication_flow_control_max_quota
• group_replication_flow_control_member_quota_percent
• group_replication_flow_control_min_quota
• group_replication_flow_control_min_recovery_quota
• group_replication_flow_control_mode
• group_replication_flow_control_period
• group_replication_flow_control_release_percent
• group_replication_force_members
• group_replication_ip_allowlist
• group_replication_member_expel_timeout
• group_replication_member_weight
• group_replication_transaction_size_limit
• group_replication_unreachable_majority_timeout

When you change the values of any Group Replication system variables, bear in mind that if there is a point where Group Replication is stopped on every member at once by a STOP GROUP_REPLICATION statement or system shutdown, the group must be restarted by bootstrapping as if it was being started for the first time. For instructions on doing this safely, see Section 20.5.2, “Restarting a Group”. In the case of group-wide configuration settings, this is required, but if you are changing other settings, try to ensure that at least one member is running at all times.

Important

• A number of system variables for Group Replication are not completely validated during server startup if they are passed as command line arguments to the server. These system variables include group_replication_group_name, group_replication_single_primary_mode, group_replication_force_members, the SSL variables, and the flow control system variables. They are fully validated only after the server has started.
• System variables for Group Replication that specify IP addresses or host names for group members are not validated until a START GROUP_REPLICATION statement is issued. Group Replication's Group Communication System (GCS) is not available to validate the values until that point.

Server system variables specific to the Group Replication plugin, along with descriptions of their function or purpose, are listed here:

• group_replication_advertise_recovery_endpoints

The value of this system variable can be changed while Group Replication is running. The change takes effect immediately on the member. However, a joining member that already received the previous value of the system variable continues to use that value. Only members that join after the value change receive the new value.

group_replication_advertise_recovery_endpoints specifies how a joining member can establish a connection to an existing member for state transfer for distributed recovery. The connection is used for both remote cloning operations and state transfer from the donor's binary log.

A value of DEFAULT, which is the default setting, means joining members use the existing member's standard SQL client connection, as specified by MySQL Server's hostname and port system variables. If an alternative port number is specified by the report_port system variable, that one is used instead. The Performance Schema table replication_group_members shows this connection's address and port number in the MEMBER_HOST and MEMBER_PORT columns.

Instead of DEFAULT, you can specify one or more distributed recovery endpoints, which the existing member advertises to joining members for them to use. Offering distributed recovery endpoints lets administrators control distributed recovery traffic separately from regular MySQL client connections to the group members. Joining members try each of the endpoints in turn in the order they are specified on the list.

Specify the distributed recovery endpoints as a comma-separated list of IP addresses and port numbers, for example:

group_replication_advertise_recovery_endpoints= "127.0.0.1:3306,127.0.0.1:4567,[::1]:3306,localhost:3306"

IPv4 and IPv6 addresses and host names can be used in any combination. IPv6 addresses must be specified in square brackets. Host names must resolve to a local IP address. Wildcard address formats cannot be used, and you cannot specify an empty list. Note that the standard SQL client connection is not automatically included on a list of distributed recovery endpoints. If you want to use it as an endpoint, you must include it explicitly on the list.

For details of how to select IP addresses and ports as distributed recovery endpoints, and how joining members use them, see Section 20.5.4.1.1, “Selecting addresses for distributed recovery endpoints”. A summary of the requirements is as follows:

• The IP addresses do not have to be configured for MySQL Server, but they do have to be assigned to the server.
• The ports do have to be configured for MySQL Server using the port, report_port, or admin_port system variable.
• Appropriate permissions are required for the replication user for distributed recovery if the admin_port is used.
• The IP addresses do not need to be added to the Group Replication allowlist specified by the group_replication_ip_allowlist system variable.
• The SSL requirements for the connection are as specified by the group_replication_recovery_ssl_* options.
• group_replication_allow_local_lower_version_join

The value of this system variable can be changed while Group Replication is running, but the change takes effect only after you stop and restart Group Replication on the group member.

group_replication_allow_local_lower_version_join allows the current server to join the group even if it is running a lower MySQL Server version than the group. With the default setting OFF, servers are not permitted to join a replication group if they are running a lower version than the existing group members. This standard policy ensures that all members of a group are able to exchange messages and apply transactions.

Set group_replication_allow_local_lower_version_join to ON only in the following scenarios:

• A server must be added to the group in an emergency in order to improve the group's fault tolerance, and only older versions are available.
• You want to roll back an upgrade for one or more replication group members without shutting down the whole group and bootstrapping it again.

Warning

Setting this option to ON does not make the new member compatible with the group, and allows it to join the group without any safeguards against incompatible behaviors by the existing members. To ensure the new member's correct operation, take both of the following precautions:

1. Before the server running the lower version joins the group, stop all writes on that server.
2. From the point where the server running the lower version joins the group, stop all writes on the other servers in the group.

Without these precautions, the server running the lower version is likely to experience difficulties and terminate with an error. - group_replication_auto_increment_increment

This system variable should have the same value on all group members. You cannot change the value of this system variable while Group Replication is running. You must stop Group Replication, change the value of the system variable, then restart Group Replication, on each of the group members. During this process, the value of the system variable is permitted to differ between group members, but some transactions on group members might be rolled back.

group_replication_auto_increment_increment determines the interval between successive values for auto-incremented columns for transactions that execute on this server instance. Adding an interval avoids the selection of duplicate auto-increment values for writes on group members, which causes rollback of transactions. The default value of 7 represents a balance between the number of usable values and the permitted maximum size of a replication group (9 members). If your group has more or fewer members, you can set this system variable to match the expected number of group members before Group Replication is started.

Important

Setting group_replication_auto_increment_increment has no effect when group_replication_single_primary_mode is ON.

When Group Replication is started on a server instance, the value of the server system variable auto_increment_increment is changed to this value, and the value of the server system variable auto_increment_offset is changed to the server ID. The changes are reverted when Group Replication is stopped. These changes are only made and reverted if auto_increment_increment and auto_increment_offset each have their default value of 1. If their values have already been modified from the default, Group Replication does not alter them. The system variables are also not modified when Group Replication is in single-primary mode, where only one server writes. - group_replication_autorejoin_tries

The value of this system variable can be changed while Group Replication is running, and the change takes effect immediately. The system variable's current value is read when an issue occurs that means the behavior is needed.

group_replication_autorejoin_tries specifies the number of tries that a member makes to automatically rejoin the group if it is expelled, or if it is unable to contact a majority of the group before the group_replication_unreachable_majority_timeout setting is reached. When the member's expulsion or unreachable majority timeout is reached, it makes an attempt to rejoin (using the current plugin option values), then continues to make further auto-rejoin attempts up to the specified number of tries. After an unsuccessful auto-rejoin attempt, the member waits 5 minutes before the next try. If the specified number of tries is exhausted without the member rejoining or being stopped, the member proceeds to the action specified by the group_replication_exit_state_action system variable.

During and between auto-rejoin attempts, a member remains in super read only mode and does not accept writes, but reads can still be made on the member, with an increasing likelihood of stale reads over time. If you cannot tolerate the possibility of stale reads for any period of time, set group_replication_autorejoin_tries to 0. For more information on the auto-rejoin feature, and considerations when choosing a value for this option, see Section 20.7.7.3, “Auto-Rejoin”. - group_replication_bootstrap_group

group_replication_bootstrap_group configures this server to bootstrap the group. This system variable must only be set on one server, and only when starting the group for the first time or restarting the entire group. After the group has been bootstrapped, set this option to OFF. It should be set to OFF both dynamically and in the configuration files. Starting two servers or restarting one server with this option set while the group is running may lead to an artificial split brain situation, where two independent groups with the same name are bootstrapped.

For instructions to bootstrap a group for the first time, see Section 20.2.1.5, “Bootstrapping the Group”. For instructions to safely bootstrap a group where transactions have been executed and certified, see Section 20.5.2, “Restarting a Group”. - group_replication_clone_threshold

The value of this system variable can be changed while Group Replication is running, but the change takes effect only after you stop and restart Group Replication on the group member.

group_replication_clone_threshold specifies the transaction gap, as a number of transactions, between the existing member (donor) and the joining member (recipient) that triggers the use of a remote cloning operation for state transfer to the joining member during the distributed recovery process. If the transaction gap between the joining member and a suitable donor exceeds the threshold, Group Replication begins distributed recovery with a remote cloning operation. If the transaction gap is below the threshold, or if the remote cloning operation is not technically possible, Group Replication proceeds directly to state transfer from a donor's binary log.

Warning

Do not use a low setting for group_replication_clone_threshold in an active group. If a number of transactions above the threshold takes place in the group while the remote cloning operation is in progress, the joining member triggers a remote cloning operation again after restarting, and could continue this indefinitely. To avoid this situation, ensure that you set the threshold to a number higher than the number of transactions that you would expect to occur in the group during the time taken for the remote cloning operation.

To use this function, both the donor and the joining member must be set up beforehand to support cloning. For instructions, see Section 20.5.4.2, “Cloning for Distributed Recovery”. When a remote cloning operation is carried out, Group Replication manages it for you, including the required server restart, provided that group_replication_start_on_boot=ON is set. If not, you must restart the server manually. The remote cloning operation replaces the existing data dictionary on the joining member, but Group Replication checks and does not proceed if the joining member has additional transactions that are not present on the other group members, because these transactions would be erased by the cloning operation.

The default setting (which is the maximum permitted sequence number for a transaction in a GTID) means that state transfer from a donor's binary log is virtually always attempted rather than cloning. However, note that Group Replication always attempts to execute a cloning operation, regardless of your threshold, if state transfer from a donor's binary log is impossible, for example because the transactions needed by the joining member are not available in the binary logs on any existing group member. If you do not want to use cloning at all in your replication group, do not install the clone plugin on the members. - group_replication_communication_debug_options

The value of this system variable can be changed while Group Replication is running, and the change takes effect immediately.

group_replication_communication_debug_options configures the level of debugging messages to provide for the different Group Replication components, such as the Group Communication System (GCS) and the group communication engine (XCom, a Paxos variant). The debug information is stored in the GCS_DEBUG_TRACE file in the data directory.

The set of available options, specified as strings, can be combined. The following options are available:

• GCS_DEBUG_NONE disables all debugging levels for both GCS and XCom.
• GCS_DEBUG_BASIC enables basic debugging information in GCS.
• GCS_DEBUG_TRACE enables trace information in GCS.
• XCOM_DEBUG_BASIC enables basic debugging information in XCom.
• XCOM_DEBUG_TRACE enables trace information in XCom.
• GCS_DEBUG_ALL enables all debugging levels for both GCS and XCom.

Setting the debug level to GCS_DEBUG_NONE only has an effect when provided without any other option. Setting the debug level to GCS_DEBUG_ALL overrides all other options. - group_replication_communication_max_message_size

This system variable should have the same value on all group members. You cannot change the value of this system variable while Group Replication is running. You must stop Group Replication, change the value of the system variable, then restart Group Replication, on each of the group members. During this process, the value of the system variable is permitted to differ between group members, but some transactions on group members might be rolled back.

group_replication_communication_max_message_size specifies a maximum message size for Group Replication communications. Messages greater than this size are automatically split into fragments that are sent separately and reassembled by the recipients. For more information, see Section 20.7.5, “Message Fragmentation”.

A maximum message size of 10485760 bytes (10 MiB) is set by default, which means that fragmentation is used by default. The greatest permitted value is the same as the maximum value of the replica_max_allowed_packet system variable, which is 1073741824 bytes (1 GB). group_replication_communication_max_message_size must be less than replica_max_allowed_packet, because the applier thread cannot handle message fragments larger than the maximum permitted packet size. To switch off fragmentation, set group_replication_communication_max_message_size to 0.

In order for members of a replication group to use fragmentation, the group's communication protocol version must be 8.0.16 or later. Use the group_replication_get_communication_protocol() function to view the group's communication protocol version. If a lower version is in use, group members do not fragment messages. You can use the group_replication_set_communication_protocol() function to set the group's communication protocol to a higher version if all group members support it. For more information, see Section 20.5.1.4, “Setting a Group's Communication Protocol Version”. - group_replication_communication_stack

Note

This system variable is effectively a group-wide configuration setting; although it can be set at runtime, a full reboot of the replication group is required for any change to take effect.

group_replication_communication_stack specifies whether the XCom communication stack or the MySQL communication stack is to be used to establish group communication connections between members. The XCom communication stack is Group Replication's own implementation, and does not support authentication or network namespaces. The MySQL communication stack is MySQL Server's native implementation, with support for authentication and network namespaces, and access to new security functions immediately on release. All members of a group must use the same communication stack.

When you use the MySQL communication stack in place of XCom, MySQL Server establishes each connection between group members using its own authentication and encryption protocols.

Note

If you are using InnoDB Cluster, the default value of group_replication_communication_stack is MYSQL.

For more information, see MySQL InnoDB Cluster.

Additional configuration is required when you set up a group to use MySQL’s communication stack; see Section 20.6.1, “Communication Stack for Connection Security Management”.

group_replication_communication_stack is effectively a group-wide configuration setting, and the setting must be the same on all group members. However, this is not policed by Group Replication’s own checks for group-wide configuration settings. A member with a different value from the rest of the group cannot communicate with the other members at all, because the communication protocols are incompatible, so it cannot exchange information about its configuration settings.

This means that although the value of the system variable can be changed while Group Replication is running, and takes effect after you restart Group Replication on the group member, the member still cannot rejoin the group until the setting has been changed on all the members. You must therefore stop Group Replication on all of the members and change the value of the system variable on them all before you can restart the group. Because all of the members are stopped, a full reboot of the group (a bootstrap by a server with group_replication_bootstrap_group=ON) is required in order for the value change to take effect. For instructions to migrate from one communication stack to another, see Section 20.6.1, “Communication Stack for Connection Security Management”. - group_replication_components_stop_timeout

The value of this system variable can be changed while Group Replication is running, but the change takes effect only after you stop and restart Group Replication on the group member.

group_replication_components_stop_timeout specifies the time, in seconds, for which Group Replication waits for each of its modules to complete ongoing processes while shutting down. The component timeout applies after a STOP GROUP_REPLICATION statement is issued, which happens automatically during server restart or auto-rejoin.

The timeout is used to resolve situations in which Group Replication components cannot be stopped normally, which might happen if a member is expelled from the group while it is in an error state, or while a process such as MySQL Enterprise Backup is holding a global lock on tables on the member. In such situations, the member cannot stop the applier thread or complete the distributed recovery process to rejoin. STOP GROUP_REPLICATION does not complete until either the situation is resolved (for example, by the lock being released), or the component timeout expires and the modules are shut down regardless of their status.

The default value is 300 seconds, so that Group Replication components are stopped after 5 minutes if the situation is not resolved before that time, allowing the member to be restarted and to rejoin. - group_replication_compression_threshold

（本文超出站点单文档体积上限，已截断）