Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 46.8Mb
PDF (A4) - 46.9Mb
PDF (RPM) - 42.2Mb
HTML Download (TGZ) - 10.8Mb
HTML Download (Zip) - 10.8Mb
HTML Download (RPM) - 9.3Mb
Man Pages (TGZ) - 226.1Kb
Man Pages (Zip) - 331.6Kb
Info (Gzip) - 4.2Mb
Info (Zip) - 4.2Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  Group Replication  /  Group Replication System Variables

18.8 Group Replication System Variables

This section lists the system variables that are specific to the Group Replication plugin. Every configuration option is prefixed with "group_replication".

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 only takes effect 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:

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:

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, cannot be changed while Group Replication is running, 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. These conditions apply to the following system variables:

From MySQL 8.0.16, you can use the group_replication_switch_to_single_primary_mode() and group_replication_switch_to_multi_primary_mode() UDFs 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 18.4.1.2, “Changing a Group's Mode”.

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 only fully validated 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.

The system variables that are specific to the Group Replication plugin are as follows:

  • group_replication_allow_local_disjoint_gtids_join

    Property Value
    Command-Line Format --group-replication-allow-local-disjoint-gtids-join[={OFF|ON}]
    Deprecated Yes (removed in 8.0.4)
    System Variable group_replication_allow_local_disjoint_gtids_join
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Removed in version 8.0.4. Allows the server to join the group even if it has local transactions that are not present in the group.

    Warning

    Use caution when enabling this option as incorrect usage can lead to conflicts in the group and rollback of transactions. The option should only be enabled as a last resort method to allow a server that has local transactions to join an existing group, and then only if the local transactions do not affect the data that is handled by the group (for example, an administrative action that was written to the binary log). The option should not be left enabled on all group members.

  • group_replication_allow_local_lower_version_join

    Property Value
    Command-Line Format --group-replication-allow-local-lower-version-join[={OFF|ON}]
    System Variable group_replication_allow_local_lower_version_join
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    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. Note that members running MySQL 8.0.17 or higher take into account the patch version of the release when checking their compatibility. Members running MySQL 8.0.16 or lower, or MySQL 5.7, only take into account the major version.

    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

    Property Value
    Command-Line Format --group-replication-auto-increment-increment=#
    System Variable group_replication_auto_increment_increment
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 7
    Minimum Value 1
    Maximum Value 65535

    Determines the interval between successive column values for transactions that execute on this server instance. This system variable should have the same value on all group members. When Group Replication is started on a server, 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. These settings avoid the selection of duplicate auto-increment values for writes on group members, which causes rollback of transactions. 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. From MySQL 8.0, the system variables are also not modified when Group Replication is in single-primary mode, where only one server writes.

    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. You cannot change the setting while Group Replication is running.

  • group_replication_autorejoin_tries

    Property Value
    Command-Line Format --group-replication-autorejoin-tries=#
    Introduced 8.0.16
    System Variable group_replication_autorejoin_tries
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 2016

    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. The default setting, 0, means that the member does not try to rejoin, and proceeds to the action specified by the group_replication_exit_state_action system variable. You can specify a maximum of 2016 tries.

    If you specify a number of tries, 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. During the auto-rejoin procedure, the member remains in super read only mode and displays an ERROR state on its view of the replication group. The member can be stopped manually at any time by using a STOP GROUP_REPLICATION statement or shutting down the server. 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.

    For more information on using this option, see Section 18.6.6.3, “Auto-Rejoin”.

  • group_replication_bootstrap_group

    Property Value
    Command-Line Format --group-replication-bootstrap-group[={OFF|ON}]
    System Variable group_replication_bootstrap_group
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Configure this server to bootstrap the group. This option 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.

  • group_replication_clone_threshold

    Property Value
    Command-Line Format --group-replication-clone-threshold=#
    Introduced 8.0.17
    System Variable group_replication_clone_threshold
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 9223372036854775807
    Minimum Value 1
    Maximum Value 9223372036854775807

    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 18.4.3.1, “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 will virtually always be 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

    Property Value
    Command-Line Format --group-replication-communication-debug-options=value
    Introduced 8.0.3
    System Variable group_replication_communication_debug_options
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String
    Default Value GCS_DEBUG_NONE
    Valid Values

    GCS_DEBUG_NONE

    GCS_DEBUG_BASIC

    GCS_DEBUG_TRACE

    XCOM_DEBUG_BASIC

    XCOM_DEBUG_TRACE

    GCS_DEBUG_ALL

    Configures the level of debugging messages to provide for the different Group Replication components, such as 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

    Property Value
    Command-Line Format --group-replication-communication-max-message-size=#
    Introduced 8.0.16
    System Variable group_replication_communication_max_message_size
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 10485760
    Minimum Value 0
    Maximum Value 1073741824

    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 18.6.4, “Message Fragmentation”.

    A maximum message size of 10485760 bytes (10 MiB) is set by default, which means that fragmentation is used by default in releases from MySQL 8.0.16. The greatest permitted value is the same as the maximum value of the slave_max_allowed_packet system variable, which is 1073741824 bytes (1 GB). The setting for group_replication_communication_max_message_size must be less than the slave_max_allowed_packet setting, because the applier thread cannot handle message fragments larger than slave_max_allowed_packet. To switch off fragmentation, specify a zero value for group_replication_communication_max_message_size. The value of group_replication_communication_max_message_size should be the same on all group members.

    In order for members of a replication group to use fragmentation, the group's communication protocol version must be MySQL 8.0.16 or above. Use the group_replication_get_communication_protocol() UDF 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() UDF to set the group's communication protocol to a higher version if all group members support it. For more information, see Section 18.4.1.4, “Setting a Group's Communication Protocol Version”.

  • group_replication_components_stop_timeout

    Property Value
    Command-Line Format --group-replication-components-stop-timeout=#
    System Variable group_replication_components_stop_timeout
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 31536000
    Minimum Value 2
    Maximum Value 31536000

    Timeout, in seconds, that Group Replication waits for each of the components when shutting down.

  • group_replication_compression_threshold

    Property Value
    Command-Line Format --group-replication-compression-threshold=#
    System Variable group_replication_compression_threshold
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 1000000
    Minimum Value 0
    Maximum Value 4294967295

    The value in bytes above which (LZ4) compression is enforced. When set to zero, deactivates compression. The value of group_replication_compression_threshold should be the same on all group members.

  • group_replication_consistency

    Property Value
    Command-Line Format --group-replication-consistency=value
    Introduced 8.0.14
    System Variable group_replication_consistency
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Enumeration
    Default Value EVENTUAL
    Valid Values

    EVENTUAL

    BEFORE_ON_PRIMARY_FAILOVER

    BEFORE

    AFTER

    BEFORE_AND_AFTER

    Controls the transaction consistency guarantee which a group provides. You can configure the consistency globally or per transaction. Also configures the fencing mechanism used by newly elected primaries in single primary groups. The effect of the variable must be considered for both read only (RO) and read write (RW) transactions. The following list shows the possible values of this variable, in order of increasing transaction consistency guarantee:

    • EVENTUAL

      Both RO and RW transactions do not wait for preceding transactions to be applied before executing. This was the behavior of Group Replication before this variable was added. A RW transaction does not wait for other members to apply a transaction. This means that a transaction could be externalized on one member before the others. This also means that in the event of a primary failover, the new primary can accept new RO and RW transactions before the previous primary transactions are all applied. RO transactions could result in outdated values, RW transactions could result in a rollback due to conflicts.

    • BEFORE_ON_PRIMARY_FAILOVER

      New RO or RW transactions with a newly elected primary that is applying backlog from the old primary are held (not applied) until any backlog has been applied. This ensures that when a primary failover happens, intentionally or not, clients always see the latest value on the primary. This guarantees consistency, but means that clients must be able to handle the delay in the event that a backlog is being applied. Usually this delay should be minimal, but does depend on the size of the backlog.

    • BEFORE

      A RW transaction waits for all preceding transactions to complete before being applied. A RO transaction waits for all preceding transactions to complete before being executed. This ensures that this transaction reads the latest value by only affecting the latency of the transaction. This reduces the overhead of synchronization on every RW transaction, by ensuring synchronization is used only on RO transactions. This consistency level also includes the consistency guarantees provided by BEFORE_ON_PRIMARY_FAILOVER.

    • AFTER

      A RW transaction waits until its changes have been applied to all of the other members. This value has no effect on RO transactions. This mode ensures that when a transaction is committed on the local member, any subsequent transaction reads the written value or a more recent value on any group member. Use this mode with a group that is used for predominantly RO operations to ensure that applied RW transactions are applied everywhere once they commit. This could be used by your application to ensure that subsequent reads fetch the latest data which includes the latest writes. This reduces the overhead of synchronization on every RO transaction, by ensuring synchronization is used only on RW transactions. This consistency level also includes the consistency guarantees provided by BEFORE_ON_PRIMARY_FAILOVER.

    • BEFORE_AND_AFTER

      A RW transaction waits for 1) all preceding transactions to complete before being applied and 2) until its changes have been applied on other members. A RO transaction waits for all preceding transactions to complete before execution takes place. This consistency level also includes the consistency guarantees provided by BEFORE_ON_PRIMARY_FAILOVER.

    The GROUP_REPLICATION_ADMIN privilege is required to change the global setting for this system variable. For more information, see Section 18.4.2, “Transaction Consistency Guarantees”.

  • group_replication_enforce_update_everywhere_checks

    Property Value
    Command-Line Format --group-replication-enforce-update-everywhere-checks[={OFF|ON}]
    System Variable group_replication_enforce_update_everywhere_checks
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Enable or disable strict consistency checks for multi-primary update everywhere. The default is that checks are disabled. In single-primary mode, this option must be disabled on all group members. In multi-primary mode, when this option is enabled, statements are checked as follows to ensure they are compatible with multi-primary mode:

    • If a transaction is executed under the SERIALIZABLE isolation level, then its commit fails when synchronizing itself with the group.

    • If a transaction executes against a table that has foreign keys with cascading constraints, then the transaction fails to commit when synchronizing itself with the group.

    This system variable is a group-wide configuration setting. It must have the same value on all group members, cannot be changed while Group Replication is running, and requires 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. From MySQL 8.0.16, you can use the group_replication_switch_to_single_primary_mode() and group_replication_switch_to_multi_primary_mode() UDFs to change the value of this system variable while the group is still running. For more information, see Section 18.4.1.2, “Changing a Group's Mode”.

  • group_replication_exit_state_action

    Property Value
    Command-Line Format --group-replication-exit-state-action=value
    Introduced 8.0.12
    System Variable group_replication_exit_state_action
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Enumeration
    Default Value (>= 8.0.16) READ_ONLY
    Default Value (>= 8.0.12, <= 8.0.15) ABORT_SERVER
    Valid Values (>= 8.0.18)

    ABORT_SERVER

    OFFLINE_MODE

    READ_ONLY

    Valid Values (>= 8.0.12, <= 8.0.17)

    ABORT_SERVER

    READ_ONLY

    Configures how Group Replication behaves when a server instance leaves the group unintentionally, for example after encountering an applier error, or in the case of a loss of majority, or when another member of the group expels it due to a suspicion timing out. The timeout period for a member to leave the group in the case of a loss of majority is set by the group_replication_unreachable_majority_timeout system variable, and the timeout period for suspicions is set by the group_replication_member_expel_timeout system variable. Note that an expelled group member does not know that it was expelled until it reconnects to the group, so the specified action is only taken if the member manages to reconnect, or if the member raises a suspicion on itself and expels itself.

    When a member is expelled due to a suspicion timing out or a loss of majority, if the member has the group_replication_autorejoin_tries system variable set to specify a number of auto-rejoin attempts, it first makes the specified number of attempts while in super read only mode, and then follows the action specified by group_replication_exit_state_action. Auto-rejoin attempts are not made in case of an applier error, because these are not recoverable.

    When group_replication_exit_state_action is set to READ_ONLY, if the member exits the group unintentionally or exhausts its auto-rejoin attempts, the instance switches MySQL to super read only mode (by setting the system variable super_read_only to ON). The READ_ONLY exit action was the behavior for MySQL 8.0 releases before the system variable was introduced, and became the default again from MySQL 8.0.16.

    When group_replication_exit_state_action is set to OFFLINE_MODE, if the member exits the group unintentionally or exhausts its auto-rejoin attempts, the instance switches MySQL to offline mode (by setting the system variable offline_mode to ON). In this mode, connected client users are disconnected on their next request and connections are no longer accepted, with the exception of client users that have the CONNECTION_ADMIN or SUPER privilege. Group Replication also sets the system variable super_read_only to ON, so clients cannot make any updates, even if they have connected with the SUPER privilege. The OFFLINE_MODE exit action is available from MySQL 8.0.18.

    When group_replication_exit_state_action is set to ABORT_SERVER, if the member exits the group unintentionally or exhausts its auto-rejoin attempts, the instance shuts down MySQL. This setting was the default from MySQL 8.0.12, when the system variable was added, to MySQL 8.0.15 inclusive.

    Important

    If a failure occurs before the member has successfully joined the group, the specified exit action is not taken. This is the case if there is a failure during the local configuration check, or a mismatch between the configuration of the joining member and the configuration of the group. In these situations, the super_read_only system variable is left with its original value, connections continue to be accepted, and the server does not shut down MySQL. To ensure that the server cannot accept updates when Group Replication did not start, we therefore recommend that super_read_only=ON is set in the server's configuration file at startup, which Group Replication will change to OFF on primary members after it has been started successfully. This safeguard is particularly important when the server is configured to start Group Replication on server boot (group_replication_start_on_boot=ON), but it is also useful when Group Replication is started manually using a START GROUP_REPLICATION command.

    For more information on using this option, and the full list of situations in which the exit action is taken, see Section 18.6.6.4, “Exit Action”.

  • group_replication_flow_control_applier_threshold

    Property Value
    Command-Line Format --group-replication-flow-control-applier-threshold=#
    System Variable group_replication_flow_control_applier_threshold
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 25000
    Minimum Value 0
    Maximum Value 2147483647

    Specifies the number of waiting transactions in the applier queue that trigger flow control. This variable can be changed without resetting Group Replication.

  • group_replication_flow_control_certifier_threshold

    Property Value
    Command-Line Format --group-replication-flow-control-certifier-threshold=#
    System Variable group_replication_flow_control_certifier_threshold
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 25000
    Minimum Value 0
    Maximum Value 2147483647

    Specifies the number of waiting transactions in the certifier queue that trigger flow control. This variable can be changed without resetting Group Replication.

  • group_replication_flow_control_hold_percent

    Property Value
    Command-Line Format --group-replication-flow-control-hold-percent=#
    Introduced 8.0.2
    System Variable group_replication_flow_control_hold_percent
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 10
    Minimum Value 0
    Maximum Value 100

    Defines what percentage of the group quota remains unused to allow a cluster under flow control to catch up on backlog. A value of 0 implies that no part of the quota is reserved for catching up on the work backlog.

  • group_replication_flow_control_max_commit_quota

    Property Value
    Command-Line Format --group-replication-flow-control-max-commit-quota=#
    Introduced 8.0.2
    System Variable group_replication_flow_control_max_commit_quota
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 2147483647

    Defines the maximum flow control quota of the group, or the maximum available quota for any period while flow control is enabled. A value of 0 implies that there is no maximum quota set. Cannot be smaller than group_replication_flow_control_min_quota and group_replication_flow_control_min_recovery_quota.

  • group_replication_flow_control_member_quota_percent

    Property Value
    Command-Line Format --group-replication-flow-control-member-quota-percent=#
    Introduced 8.0.2
    System Variable group_replication_flow_control_member_quota_percent
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 100

    Defines the percentage of the quota that a member should assume is available for itself when calculating the quotas. A value of 0 implies that the quota should be split equally between members that were writers in the last period.

  • group_replication_flow_control_min_quota

    Property Value
    Command-Line Format --group-replication-flow-control-min-quota=#
    Introduced 8.0.2
    System Variable group_replication_flow_control_min_quota
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 2147483647

    Controls the lowest flow control quota that can be assigned to a member, independently of the calculated minimum quota executed in the last period. A value of 0 implies that there is no minimum quota. Cannot be larger than group_replication_flow_control_max_commit_quota.

  • group_replication_flow_control_min_recovery_quota

    Property Value
    Command-Line Format --group-replication-flow-control-min-recovery-quota=#
    Introduced 8.0.2
    System Variable group_replication_flow_control_min_recovery_quota
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 2147483647

    Controls the lowest quota that can be assigned to a member because of another recovering member in the group, independently of the calculated minimum quota executed in the last period. A value of 0 implies that there is no minimum quota. Cannot be larger than group_replication_flow_control_max_commit_quota.

  • group_replication_flow_control_mode

    Property Value
    Command-Line Format --group-replication-flow-control-mode=value
    System Variable group_replication_flow_control_mode
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Enumeration
    Default Value QUOTA
    Valid Values

    DISABLED

    QUOTA

    Specifies the mode used for flow control. This variable can be changed without resetting Group Replication.

  • group_replication_flow_control_period

    Property Value
    Command-Line Format --group-replication-flow-control-period=#
    Introduced 8.0.2
    System Variable group_replication_flow_control_period
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 1
    Minimum Value 1
    Maximum Value 60

    Defines how many seconds to wait between flow control iterations, in which flow control messages are sent and flow control management tasks are run.

  • group_replication_flow_control_release_percent

    Property Value
    Command-Line Format --group-replication-flow-control-release-percent=#
    Introduced 8.0.2
    System Variable group_replication_flow_control_release_percent
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 50
    Minimum Value 0
    Maximum Value 1000

    Defines how the group quota should be released when flow control no longer needs to throttle the writer members, with this percentage being the quota increase per flow control period. A value of 0 implies that once the flow control thresholds are within limits the quota is released in a single flow control iteration. The range allows the quota to be released at up to 10 times current quota, as that allows a greater degree of adaptation, mainly when the flow control period is large and the quotas are very small.

  • group_replication_force_members

    Property Value
    Command-Line Format --group-replication-force-members=value
    System Variable group_replication_force_members
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String

    A list of peer addresses as a comma separated list such as host1:port1,host2:port2. This option is used to force a new group membership, in which the excluded members do not receive a new view and are blocked.

    You must specify the address or host name and port as they are given in the group_replication_local_address option for each member. An IPv6 address must be specified in square brackets. For example:

    "198.51.100.44:33061,[2001:db8:85a3:8d3:1319:8a2e:370:7348]:33061,example.org:33061"

    The group communication engine for Group Replication (XCom) checks that the supplied IP addresses are in a valid format, and checks that you have not included any group members that are currently unreachable. Otherwise, the new configuration is not validated, so you must be careful to include only online servers that are reachable members of the group. Any incorrect values or invalid host names in the list could cause the group to be blocked with an invalid configuration.

    It is important before forcing a new membership configuration to ensure that the servers to be excluded have been shut down. If they are not, shut them down before proceeding. Group members that are still online can automatically form new configurations, and if this has already taken place, forcing a further new configuration could create an artificial split-brain situation for the group.

    After you have used the group_replication_force_members system variable to successfully force a new group membership and unblock the group, ensure that you clear the system variable. group_replication_force_members must be empty in order to issue a START GROUP_REPLICATION statement.

    For details of the procedure to follow, see Section 18.4.4, “Network Partitioning”.

  • group_replication_group_name

    Property Value
    Command-Line Format --group-replication-group-name=value
    System Variable group_replication_group_name
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String

    The name of the group which this server instance belongs to. Must be a valid UUID. This UUID is used internally when setting GTIDs for Group Replication events in the binary log.

    Important

    A unique UUID must be used.

  • group_replication_group_seeds

    Property Value
    Command-Line Format --group-replication-group-seeds=value
    System Variable group_replication_group_seeds
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String

    A list of group members that provide a member which joins the group with the data required for the joining member to gain synchrony with the group. The list consists of a single internal network address or host name for each included seed member, as configured in the seed member's group_replication_local_address system variable (not the seed member's SQL hostname and port). The addresses of the seed members are specified as a comma separated list, such as host1:port1,host2:port2. An IPv6 address must be specified in square brackets. For example:

    group_replication_group_seeds= "198.51.100.44:33061,[2001:db8:85a3:8d3:1319:8a2e:370:7348]:33061, example.org:33061"

    Note that the value you specify for this variable is not validated until a START GROUP_REPLICATION statement is issued and the Group Communication System (GCS) is available.

    Usually this list consists of all members of the group, but you can choose a subset of the group members to be seeds. The list must contain at least one valid member address. Each address is validated when starting Group Replication. If the list does not contain any valid member addresses, issuing START GROUP_REPLICATION fails.

    When a server is joining a replication group, it attempts to connect to the first seed member listed in its group_replication_group_seeds system variable. If the connection is refused, the joining member tries to connect to each of the other seed members in the list in order. If the joining member connects to a seed member but does not get added to the replication group as a result (for example, because the seed member does not have the joining member's address in its whitelist and closes the connection), the joining member continues to try the remaining seed members in the list in order.

    A joining member must communicate with the seed member using the same protocol (IPv4 or IPv6) that the seed member advertises in the group_replication_group_seeds option. For the purpose of IP address whitelisting for Group Replication, the whitelist on the seed member must include an IP address for the joining member for the protocol offered by the seed member, or a host name that resolves to an address for that protocol. This address or host name must be set up and whitelisted in addition to the joining member's group_replication_local_address if the protocol for that address does not match the seed member's advertised protocol. If a joining member does not have a whitelisted address for the appropriate protocol, its connection attempt is refused. For more information, see Section 18.5.1, “Group Replication IP Address Whitelisting”.

  • group_replication_gtid_assignment_block_size

    Property Value
    Command-Line Format --group-replication-gtid-assignment-block-size=#
    System Variable group_replication_gtid_assignment_block_size
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 1000000
    Minimum Value 1
    Maximum Value (64-bit platforms) 9223372036854775807
    Maximum Value (32-bit platforms) 4294967295

    The number of consecutive GTIDs that are reserved for each member. Each member consumes its blocks and reserves more when needed.

    This system variable is a group-wide configuration setting. It must have the same value on all group members, cannot be changed while Group Replication is running, and requires 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.

  • group_replication_ip_whitelist

    Property Value
    Command-Line Format --group-replication-ip-whitelist=value
    System Variable group_replication_ip_whitelist
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String
    Default Value AUTOMATIC

    Specifies which hosts are permitted to connect to the group. The address that you specify for each group member in group_replication_local_address must be whitelisted on the other servers in the replication group. Note that the value you specify for this variable is not validated until a START GROUP_REPLICATION statement is issued and the Group Communication System (GCS) is available.

    By default, this system variable is set to AUTOMATIC, which permits connections from private subnetworks active on the host. The group communication engine for Group Replication (XCom) automatically scans active interfaces on the host, and identifies those with addresses on private subnetworks. These addresses and the localhost IP address for IPv4 and (from MySQL 8.0.14) IPv6 are used to create the Group Replication whitelist. For a list of the ranges from which addresses are automatically whitelisted, see Section 18.5.1, “Group Replication IP Address Whitelisting”.

    The automatic whitelist of private addresses cannot be used for connections from servers outside the private network. For Group Replication connections between server instances that are on different machines, you must provide public IP addresses and specify these as an explicit whitelist. If you specify any entries for the whitelist, the private and localhost addresses are not added automatically, so if you use any of these, you must specify them explicitly.

    As the value of the group_replication_ip_whitelist option, you can specify any combination of the following:

    • IPv4 addresses (for example, 198.51.100.44)

    • IPv4 addresses with CIDR notation (for example, 192.0.2.21/24)

    • IPv6 addresses, from MySQL 8.0.14 (for example, 2001:db8:85a3:8d3:1319:8a2e:370:7348)

    • IPv6 addresses with CIDR notation, from MySQL 8.0.14 (for example, 2001:db8:85a3:8d3::/64)

    • Host names (for example, example.org)

    • Host names with CIDR notation (for example, www.example.com/24)

    Before MySQL 8.0.14, host names could only resolve to IPv4 addresses. From MySQL 8.0.14, host names can resolve to IPv4 addresses, IPv6 addresses, or both. If a host name resolves to both an IPv4 and an IPv6 address, the IPv4 address is always used for Group Replication connections. You can use CIDR notation in combination with host names or IP addresses to whitelist a block of IP addresses with a particular network prefix, but do ensure that all the IP addresses in the specified subnet are under your control.

    A comma must separate each entry in the whitelist. For example:

    "192.0.2.21/24,198.51.100.44,203.0.113.0/24,2001:db8:85a3:8d3:1319:8a2e:370:7348,example.org,www.example.com/24"

    If any of the seed members for the group are listed in the group_replication_group_seeds option with an IPv6 address when a joining member has an IPv4 group_replication_local_address, or the reverse, you must also set up and whitelist an alternative address for the joining member for the protocol offered by the seed member (or a host name that resolves to an address for that protocol). For more information, see Section 18.5.1, “Group Replication IP Address Whitelisting”.

    It is possible to configure different whitelists on different group members according to your security requirements, for example, in order to keep different subnets separate. However, this can cause issues when a group is reconfigured. If you do not have a specific security requirement to do otherwise, use the same whitelist on all members of a group. For more details, see Section 18.5.1, “Group Replication IP Address Whitelisting”.

    For host names, name resolution takes place only when a connection request is made by another server. A host name that cannot be resolved is not considered for whitelist validation, and a warning message is written to the error log. Forward-confirmed reverse DNS (FCrDNS) verification is carried out for resolved host names.

    Warning

    Host names are inherently less secure than IP addresses in a whitelist. FCrDNS verification provides a good level of protection, but can be compromised by certain types of attack. Specify host names in your whitelist only when strictly necessary, and ensure that all components used for name resolution, such as DNS servers, are maintained under your control. You can also implement name resolution locally using the hosts file, to avoid the use of external components.

  • group_replication_local_address

    Property Value
    Command-Line Format --group-replication-local-address=value
    System Variable group_replication_local_address
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String

    The network address which the member provides for connections from other members, specified as a host:port formatted string. This address must be reachable by all members of the group because it is used by the group communication engine for Group Replication (XCom, a Paxos variant) for TCP communication between remote XCom instances. Communication with the local instance is over an input channel using shared memory.

    Warning

    Do not use this address for communication with the member. This is not the MySQL server SQL protocol host and port.

    The address or host name that you specify in group_replication_local_address is used by Group Replication as the unique identifier for a group member within the replication group. You can use the same port for all members of a replication group as long as the host names or IP addresses are all different, and you can use the same host name or IP address for all members as long as the ports are all different. The recommended port for group_replication_local_address is 33061. Note that the value you specify for this variable is not validated until the START GROUP_REPLICATION statement is issued and the Group Communication System (GCS) is available.

    The network address configured by group_replication_local_address must be resolvable by all group members. For example, if each server instance is on a different machine with a fixed network address, you could use the IP address of the machine, such as 10.0.0.1. If you use a host name, you must use a fully qualified name, and ensure it is resolvable through DNS, correctly configured /etc/hosts files, or other name resolution processes. From MySQL 8.0.14, IPv6 addresses (or host names that resolve to them) can be used as well as IPv4 addresses. An IPv6 address must be specified in square brackets in order to distinguish the port number, for example:

    group_replication_local_address= "[2001:db8:85a3:8d3:1319:8a2e:370:7348]:33061"

    If a host name specified as the Group Replication local address for a server instance resolves to both an IPv4 and an IPv6 address, the IPv4 address is always used for Group Replication connections. For more information on Group Replication support for IPv6 networks and on replication groups with a mix of members using IPv4 and members using IPv6, see Section 18.4.5, “Support For IPv6 And For Mixed IPv6 And IPv4 Groups”.

    For the purpose of IP address whitelisting for Group Replication, the address that you specify for each group member in group_replication_local_address must be added to the list for the group_replication_ip_whitelist option on the other servers in the replication group. If any of the seed members for the group are listed in the group_replication_group_seeds option with an IPv6 address when this member has an IPv4 group_replication_local_address, or the reverse, you must also set up and whitelist an alternative address for this member for the required protocol (or a host name that resolves to an address for that protocol). For more information, see Section 18.5.1, “Group Replication IP Address Whitelisting”.

  • group_replication_member_weight

    Property Value
    Command-Line Format --group-replication-member-weight=#
    Introduced 8.0.2
    System Variable group_replication_member_weight
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 50
    Minimum Value 0
    Maximum Value 100

    A percentage weight that can be assigned to members to influence the chance of the member being elected as primary in the event of failover, for example when the existing primary leaves a single-primary group. Assign numeric weights to members to ensure that specific members are elected, for example during scheduled maintenance of the primary or to ensure certain hardware is prioritized in the event of failover.

    For a group with members configured as follows:

    • member-1: group_replication_member_weight=30, server_uuid=aaaa

    • member-2: group_replication_member_weight=40, server_uuid=bbbb

    • member-3: group_replication_member_weight=40, server_uuid=cccc

    • member-4: group_replication_member_weight=40, server_uuid=dddd

    during election of a new primary the members above would be sorted as member-2, member-3, member-4, and member-1. This results in member-2 being chosen as the new primary in the event of failover. For more information, see Section 18.1.3.1, “Single-Primary Mode”.

  • group_replication_member_expel_timeout

    Property Value
    Command-Line Format --group-replication-member-expel-timeout=#
    Introduced 8.0.13
    System Variable group_replication_member_expel_timeout
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value (>= 8.0.14) 3600
    Maximum Value (<= 8.0.13) 31536000

    The period of time in seconds that a Group Replication group member waits after creating a suspicion before expelling from the group the member suspected of having failed. The initial 5-second detection period before a suspicion is created does not count as part of this time. Changing the value of group_replication_member_expel_timeout on a group member takes effect immediately for existing as well as future suspicions on that group member. It is not mandatory for all members of a group to have the same setting, but it is recommended in order to avoid unexpected expulsions.

    By default, group_replication_member_expel_timeout is set to 0, meaning that there is no waiting period and a suspected member is liable for expulsion immediately after the 5-second detection period ends. To avoid unnecessary expulsions on slower networks, or in the case of expected transient network failures or machine slowdowns, you can specify a timeout value greater than zero, up to a maximum of 3600 seconds (1 hour). If a suspect member becomes active again before the suspicion times out, it rejoins the group, applies all the messages that were buffered by the remaining group members, and enters ONLINE state.

    If the timeout is exceeded, the suspect member is liable for expulsion immediately after the suspicion times out. If the member is able to resume communications and receives a view where it is expelled, and the member has the group_replication_autorejoin_tries system variable set to specify a number of auto-rejoin attempts, it proceeds to make the specified number of attempts to rejoin the group while in super read only mode. If the member does not have any auto-rejoin attempts specified, or if it has exhausted the specified number of attempts, it follows the action specified by the system variable group_replication_exit_state_action.

    For more information on using this option, see Section 18.6.6.1, “Expel Timeout”. For alternative mitigation strategies to avoid unnecessary expulsions where this system variable is not available, see Section 18.9.2, “Group Replication Limitations”.

  • group_replication_message_cache_size

    Property Value
    Command-Line Format --group-replication-message-cache-size=#
    Introduced 8.0.16
    System Variable group_replication_message_cache_size
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 1073741824 (1 GB)
    Minimum Value 1073741824 (1 GB)
    Maximum Value (64-bit platforms) 18446744073709551615 (16 EiB)
    Maximum Value (32-bit platforms) 315360004294967295 (4 GB)

    The maximum amount of memory that is available for the message cache in the group communication engine for Group Replication (XCom), which holds messages (and their metadata) that are exchanged between the group members as a part of the consensus protocol. Among other functions, the message cache is used for recovery by members that return to the group after a period where they were unable to communicate with the other group members. The group_replication_member_expel_timeout system variable determines the time (up to an hour) allowed for members to return to the group rather than being expelled. The size of the message cache should be set with reference to the expected volume of messages in this time period, so that it contains all the missed messages required for members to return successfully.

    group_replication_message_cache_size has a default and minimum setting of 1073741824 bytes (1 GB). The same cache size limit should be set on all group members, because an unreachable member that is attempting to reconnect selects any other member at random for recovery of missed messages. Ensure that sufficient memory is available on your system for your chosen cache size limit, considering the size of MySQL Server's other caches and object pools.

    The cache size limit can be increased or reduced dynamically at runtime. If you reduce the cache size limit, XCom removes the oldest entries that have been decided and delivered until the current size is below the limit. Group Replication's Group Communication System (GCS) alerts you, by a warning message, when a message that is likely to be needed for recovery by a member that is currently unreachable is removed from the message cache. For more information on tuning the message cache size, see Section 18.6.5, “XCom Cache Management”.

  • group_replication_poll_spin_loops

    Property Value
    Command-Line Format --group-replication-poll-spin-loops=#
    System Variable group_replication_poll_spin_loops
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value (64-bit platforms) 18446744073709551615
    Maximum Value (32-bit platforms) 4294967295

    The number of times the group communication thread waits for the communication engine mutex to be released before the thread waits for more incoming network messages.

  • group_replication_recovery_complete_at

    Property Value
    Command-Line Format --group-replication-recovery-complete-at=value
    System Variable group_replication_recovery_complete_at
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Enumeration
    Default Value TRANSACTIONS_APPLIED
    Valid Values

    TRANSACTIONS_CERTIFIED

    TRANSACTIONS_APPLIED

    The policy applied during the distributed recovery process when handling cached transactions after state transfer. This option specifies whether a member is marked online after it has received all transactions that it missed before it joined the group (TRANSACTIONS_CERTIFIED) or after it has received and applied them (TRANSACTIONS_APPLIED).

  • group_replication_recovery_compression_algorithm

    Property Value
    Command-Line Format --group-replication-recovery-compression-algorithm=value
    Introduced 8.0.18
    System Variable group_replication_recovery_compression_algorithm
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Set
    Default Value uncompressed
    Valid Values

    zlib

    zstd

    uncompressed

    The compression algorithms permitted for Group Replication distributed recovery connections for state transfer from a donor's binary log. The available algorithms are the same as for the protocol_compression_algorithms system variable. For more information, see Section 4.2.6, “Connection Compression Control”.

    This setting does not apply if the server has been set up to support cloning (see Section 18.4.3.1, “Cloning for Distributed Recovery”) and a remote cloning operation is used during distributed recovery. For this method of state transfer, the clone plugin's clone_enable_compression setting applies.

  • group_replication_recovery_get_public_key

    Property Value
    Command-Line Format --group-replication-recovery-get-public-key[={OFF|ON}]
    Introduced 8.0.4
    System Variable group_replication_recovery_get_public_key
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Whether to request from the master the public key required for RSA key pair-based password exchange. If group_replication_recovery_public_key_path is set to a valid public key file, it takes precedence over group_replication_recovery_get_public_key. This variable applies if you are not using SSL for distributed recovery over the group_replication_recovery channel (group_replication_recovery_use_ssl=ON), and the replication user account for Group Replication authenticates with the caching_sha2_password plugin (which is the default in MySQL 8.0). For more details, see Using Group Replication and the Caching SHA-2 User Credentials Plugin.

  • group_replication_recovery_public_key_path

    Property Value
    Command-Line Format --group-replication-recovery-public-key-path=file_name
    Introduced 8.0.4
    System Variable group_replication_recovery_public_key_path
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type File name
    Default Value NULL

    The path name to a file containing a slave-side copy of the public key required by the master for RSA key pair-based password exchange. The file must be in PEM format. If group_replication_recovery_public_key_path is set to a valid public key file, it takes precedence over group_replication_recovery_get_public_key. This variable applies if you are not using SSL for distributed recovery over the group_replication_recovery channel (so group_replication_recovery_use_ssl is set to OFF), and the replication user account for Group Replication authenticates with the caching_sha2_password plugin (which is the default in MySQL 8.0) or the sha256_password plugin. (For sha256_password, setting group_replication_recovery_public_key_path applies only if MySQL was built using OpenSSL.) For more details, see Using Group Replication and the Caching SHA-2 User Credentials Plugin.

  • group_replication_recovery_reconnect_interval

    Property Value
    Command-Line Format --group-replication-recovery-reconnect-interval=#
    System Variable group_replication_recovery_reconnect_interval
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 60
    Minimum Value 0
    Maximum Value 31536000

    The sleep time, in seconds, between reconnection attempts when no suitable donor was found in the group for distributed recovery.

  • group_replication_recovery_retry_count

    Property Value
    Command-Line Format --group-replication-recovery-retry-count=#
    System Variable group_replication_recovery_retry_count
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 10
    Minimum Value 0
    Maximum Value 31536000

    The number of times that the member that is joining tries to connect to the available donors for distributed recovery before giving up.

  • group_replication_recovery_ssl_ca

    Property Value
    Command-Line Format --group-replication-recovery-ssl-ca=value
    System Variable group_replication_recovery_ssl_ca
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String

    The path to a file that contains a list of trusted SSL certificate authorities for distributed recovery connections. See Section 18.5.2, “Group Replication Secure Socket Layer (SSL) Support” for information on configuring SSL for recovery.

    If this server has been set up to support cloning (see Section 18.4.3.1, “Cloning for Distributed Recovery”), and you have set group_replication_recovery_use_ssl to ON, Group Replication automatically configures the setting for the clone SSL option clone_ssl_ca to match your setting for group_replication_recovery_ssl_ca.

  • group_replication_recovery_ssl_capath

    Property Value
    Command-Line Format --group-replication-recovery-ssl-capath=value
    System Variable group_replication_recovery_ssl_capath
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String

    The path to a directory that contains trusted SSL certificate authority certificates for distributed recovery connections. See Section 18.5.2, “Group Replication Secure Socket Layer (SSL) Support” for information on configuring SSL for distributed recovery.

  • group_replication_recovery_ssl_cert

    Property Value
    Command-Line Format --group-replication-recovery-ssl-cert=value
    System Variable group_replication_recovery_ssl_cert
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String

    The name of the SSL certificate file to use for establishing a secure connection for distributed recovery. See Section 18.5.2, “Group Replication Secure Socket Layer (SSL) Support” for information on configuring SSL for distributed recovery.

    If this server has been set up to support cloning (see Section 18.4.3.1, “Cloning for Distributed Recovery”), and you have set group_replication_recovery_use_ssl to ON, Group Replication automatically configures the setting for the clone SSL option clone_ssl_cert to match your setting for group_replication_recovery_ssl_cert.

  • group_replication_recovery_ssl_cipher

    Property Value
    Command-Line Format --group-replication-recovery-ssl-cipher=value
    System Variable group_replication_recovery_ssl_cipher
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String

    The list of permissible ciphers for SSL encryption. See Section 18.5.2, “Group Replication Secure Socket Layer (SSL) Support” for information on configuring SSL for distributed recovery.

  • group_replication_recovery_ssl_crl

    Property Value
    Command-Line Format --group-replication-recovery-ssl-crl=value
    System Variable group_replication_recovery_ssl_crl
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type File name

    The path to a directory that contains files containing certificate revocation lists. See Section 18.5.2, “Group Replication Secure Socket Layer (SSL) Support” for information on configuring SSL for distributed recovery.

  • group_replication_recovery_ssl_crlpath

    Property Value
    Command-Line Format --group-replication-recovery-ssl-crlpath=value
    System Variable group_replication_recovery_ssl_crlpath
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Directory name

    The path to a directory that contains files containing certificate revocation lists. See Section 18.5.2, “Group Replication Secure Socket Layer (SSL) Support” for information on configuring SSL for distributed recovery.

  • group_replication_recovery_ssl_key

    Property Value
    Command-Line Format --group-replication-recovery-ssl-key=value
    System Variable group_replication_recovery_ssl_key
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String

    The name of the SSL key file to use for establishing a secure connection. See Section 18.5.2, “Group Replication Secure Socket Layer (SSL) Support” for information on configuring SSL for distributed recovery.

    If this server has been set up to support cloning (see Section 18.4.3.1, “Cloning for Distributed Recovery”), and you have set group_replication_recovery_use_ssl to ON, Group Replication automatically configures the setting for the clone SSL option clone_ssl_key to match your setting for group_replication_recovery_ssl_key.

  • group_replication_recovery_ssl_verify_server_cert

    Property Value
    Command-Line Format --group-replication-recovery-ssl-verify-server-cert[={OFF|ON}]
    System Variable group_replication_recovery_ssl_verify_server_cert
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Make the distributed recovery connection check the server's Common Name value in the donor sent certificate. See Section 18.5.2, “Group Replication Secure Socket Layer (SSL) Support” for information on configuring SSL for distributed recovery.

  • group_replication_recovery_use_ssl

    Property Value
    Command-Line Format --group-replication-recovery-use-ssl[={OFF|ON}]
    System Variable group_replication_recovery_use_ssl
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Whether Group Replication distributed recovery connections between group members should use SSL or not. See Section 18.5.2, “Group Replication Secure Socket Layer (SSL) Support” for information on configuring SSL for distributed recovery.

    If this server has been set up to support cloning (see Section 18.4.3.1, “Cloning for Distributed Recovery”), and you set this option to ON, Group Replication uses SSL for remote cloning operations as well as for state transfer from a donor's binary log. If you set this option to OFF, Group Replication does not use SSL for remote cloning operations.

  • group_replication_recovery_zstd_compression_level

    Property Value
    Command-Line Format --group-replication-recovery-zstd-compression-level=#
    Introduced 8.0.18
    System Variable group_replication_recovery_zstd_compression_level
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 3
    Minimum Value 1
    Maximum Value 22

    The compression level to use for Group Replication distributed recovery connections that use the zstd compression algorithm. The permitted levels are from 1 to 22, with larger values indicating increasing levels of compression. The default zstd compression level is 3. For distributed recovery connections that do not use zstd compression, this variable has no effect.

    For more information, see Section 4.2.6, “Connection Compression Control”.

  • group_replication_single_primary_mode

    Property Value
    Command-Line Format --group-replication-single-primary-mode[={OFF|ON}]
    System Variable group_replication_single_primary_mode
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value ON

    Instructs the group to automatically pick a single server to be the one that handles read/write workload. This server is the PRIMARY and all others are SECONDARIES.

    This system variable is a group-wide configuration setting. It must have the same value on all group members, cannot be changed while Group Replication is running, and requires 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. From MySQL 8.0.16, you can use the group_replication_switch_to_single_primary_mode() and group_replication_switch_to_multi_primary_mode() UDFs to change the value of this system variable while the group is still running. For more information, see Section 18.4.1.2, “Changing a Group's Mode”.

  • group_replication_ssl_mode

    Property Value
    Command-Line Format --group-replication-ssl-mode=value
    System Variable group_replication_ssl_mode
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Enumeration
    Default Value DISABLED
    Valid Values

    DISABLED

    REQUIRED

    VERIFY_CA

    VERIFY_IDENTITY

    Sets the security state of group communication connections between Group Replication members. The possible values are as follows:

    DISABLED

    Establish an unencrypted connection (the default).

    REQUIRED

    Establish a secure connection if the server supports secure connections.

    VERIFY_CA

    Like REQUIRED, but additionally verify the server TLS certificate against the configured Certificate Authority (CA) certificates.

    VERIFY_IDENTITY

    Like VERIFY_CA, but additionally verify that the server certificate matches the host to which the connection is attempted.

    See Section 18.5.2, “Group Replication Secure Socket Layer (SSL) Support” for information on configuring SSL for group communication.

  • group_replication_start_on_boot

    Property Value
    Command-Line Format --group-replication-start-on-boot[={OFF|ON}]
    System Variable group_replication_start_on_boot
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value ON

    Whether the server should start Group Replication or not during server start.

  • group_replication_transaction_size_limit

    Property Value
    Command-Line Format --group-replication-transaction-size-limit=#
    System Variable group_replication_transaction_size_limit
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value (>= 8.0.2) 150000000
    Default Value (<= 8.0.1) 0
    Minimum Value 0
    Maximum Value 2147483647

    Configures the maximum transaction size in bytes which the replication group accepts. Transactions larger than this size are rolled back by the receiving member and are not broadcast to the group. Large transactions can cause problems for a replication group in terms of memory allocation, which can cause the system to slow down, or in terms of network bandwidth consumption, which can cause a member to be suspected of having failed because it is busy processing the large transaction.

    When this system variable is set to 0 there is no limit to the size of transactions the group accepts. From MySQL 8.0, the default setting for this system variable is 150000000 bytes (approximately 143 MB). Adjust the value of this system variable depending on the maximum message size that you need the group to tolerate, bearing in mind that the time taken to process a transaction is proportional to its size. The value of group_replication_transaction_size_limit should be the same on all group members. For further mitigation strategies for large transactions, see Section 18.9.2, “Group Replication Limitations”.

  • group_replication_unreachable_majority_timeout

    Property Value
    Command-Line Format --group-replication-unreachable-majority-timeout=#
    Introduced 8.0.2
    System Variable group_replication_unreachable_majority_timeout
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 31536000

    Specifies a number of seconds for which members that suffer a network partition and cannot connect to the majority wait before leaving the group. In a group of 5 servers (S1,S2,S3,S4,S5), if there is a disconnection between (S1,S2) and (S3,S4,S5) there is a network partition. The first group (S1,S2) is now in a minority because it cannot contact more than half of the group. While the majority group (S3,S4,S5) remains running, the minority group waits for the specified time for a network reconnection. For a detailed description of this scenario, see Section 18.4.4, “Network Partitioning”.

    By default, group_replication_unreachable_majority_timeout is set to 0, which means that members that find themselves in a minority due to a network partition wait forever to leave the group. If you set a timeout, when the specified time elapses, all pending transactions processed by the minority are rolled back, and the servers in the minority partition move to the ERROR state. If a member has the group_replication_autorejoin_tries system variable set to specify a number of auto-rejoin attempts, it proceeds to make the specified number of attempts to rejoin the group while in super read only mode. If the member does not have any auto-rejoin attempts specified, or if it has exhausted the specified number of attempts, it follows the action specified by the system variable group_replication_exit_state_action.

    Warning

    When you have a symmetric group, with just two members for example (S0,S2), if there is a network partition and there is no majority, after the configured timeout all members enter the ERROR state.

    For more information on using this option, see Section 18.6.6.2, “Unreachable Majority Timeout”.

Group Replication Status Variable

This section describes the status variables which provide information about Group Replication. The variable has the following meaning: