WL#14539: GR: Specify the UUID used to log View_change_log_event

Affects: Server-8.0   —   Status: Complete

EXECUTIVE SUMMARY

This worklog shall provide a option for DBAs/operators to configure the UUID that will be used by Group Replication when logging View_change_log_event.

USER STORIES

As MySQL DBA, I want to :

  • distinguish the GTIDs assigned to transactions from the ones assigned to automatic group operations, more precisely Group Replication members joining which logs a View_change_log_event, with a group GTID on the binary log.

Scope

The work described in this document does:

  • implement group replication variable group_replication_view_change_uuid with uuid that will be used on group replication View_change_log_event on the binary log

  • implement validation on variable group_replication_view_change_uuid, shall be different from server uuid, group replication name and uuid assigned to anonymous transactions[1].

High Level Description

When a member joins a group in Group Replication, it logs a View_change_log_event, with Group Replication group name uuid.

We will introduce an option that will use a different uuid when logging View_change_log_event on binary log.

[1] ASSIGN_GTIDS_TO_ANONYMOUS_TRANSACTIONS https://dev.mysql.com/doc/refman/8.0/en/change-master-to.html

Functional Requirements

  • FR1: When Group Replication starts on boot if group_replication_view_change_uuid is equal to server uuid, group_replication_group_name or UUID used on ASSIGN_GTIDS_TO_ANONYMOUS_TRANSACTION[1] on any replication channel it shall abort the process of starting GR, but allow the server to start.

  • FR2: When execute START GROUP_REPLICATION if group_replication_view_change_uuid is equal to server uuid, group_replication_group_name or UUID used on anonymous gtid it shall abort start process.

  • FR3: All members on a group must have the same group_replication_view_change_uuid value. Attempting to join a group with a different value will cause the new member not to be allowed to join.

  • FR4: To change group_replication_view_change_uuid plugin shall be stopped

  • FR5: group_replication_view_change_uuid by default shall not have an uuid and Group Replication will use group name to write View_change_log_event to binary log

  • FR6: When group_replication_view_change_uuid value is different of "AUTOMATIC", View_change_log_event will be logged using that uuid.

  • FR7: The value of group_replication_view_change_uuid must be "AUTOMATIC" or a valid uuid.

  • FR8: Members which version does not know group_replication_view_change_uuid, will be considered as group_replication_view_change_uuid= "AUTOMATIC"

  • FR9: The statement CHANGE REPLICATION SOURCE TO ASSIGN_GTIDS_TO_ANONYMOUS_TRANSACTION shall fail if the specified UUID is equal to group_replication_view_change_uuid.

Non-Functional Requirements

[1] ASSIGN_GTIDS_TO_ANONYMOUS_TRANSACTIONS https://dev.mysql.com/doc/refman/8.0/en/change-master-to.html

Summary of the approach

  • A group can set a uuid that will be used on group replication View_change_log_event on the binary log

Security context

The use of group_replication_view_change_uuid will not introduce any modification on security.

Upgrade/downgrade and cross-version replication

All group members must have the same group_replication_view_change_uuid value. For server versions lower than 8.0.25, on which the option does not exist, its value is considered to be "AUTOMATIC".

It won't be possible to update group_replication_view_change_uuid while the group is online. The group shall be stopped to set the option on all the members and start the group.

User interface

On this worklog we will introduce an option to specify an uuid that will be used by Group Replication when logging View_change_log_event.

  • NAME: group_replication_view_change_uuid
  • VALUES: { AUTOMATIC, string containing a valid UUID }
  • DEFAULT: AUTOMATIC
  • SCOPE: global
  • DYNAMIC: must be set with group stopped
  • REPLICATED (written to the binary log): no
  • PERSIST: PERSIST, PERSIST_ONLY
  • PRIVILEGES REQUIRED: SYSTEM_VARIABLES_ADMIN
  • DESCRIPTION: AUTOMATIC is the group name uuid and string containing a valid UUID that will be used on logging View_change_log_event

API

The variable group_replication_view_change_uuid from the member will be added to member info structure.

Observability

When starting group replication group_replication_view_change_uuid shall be logged.

When updating group_replication_view_change_uuid variable on a session we have different messages for each of type failure.

For an Invalid UUID it uses existing error ER_WRONG_VALUE_FOR_VAR: "Variable '%-.64s' can't be set to the value of '%-.200s'" with following parameters:

  1. group_replication_view_change_uuid
  2. value used to set group_replication_view_change_uuid

For Same UUID has group name it uses existing error ER_WRONG_VALUE_FOR_VAR_PLUS_ACTIONABLE_PART: Variable '%-.64s' cannot be set to the value of '%-.200s'. %-.200s with following parameters:

  1. group_replication_view_change_uuid
  2. value used to set group_replication_view_change_uuid
  3. Is the same as group_replication_name. Please change group_replication_view_change_uuid to AUTOMATIC

For UUID in use by an channel configured with ANONYMOUS GTIDS

  1. group_replication_group_view_change_uuid
  2. value used to set group_replication_view_change_uuid
  3. Is already used for ASSIGN_GTIDS_TO_ANOYMOUS_TRANSACTIONS in a server channel

When group replication starts will validate group_replication_view_change_uuid variable, if configuration is invalid it will abort and log one of the following errors:

  • ER_GRP_RPL_VIEW_CHANGE_UUID_INVALID: "The group_replication_view_change_uuid is not a valid UUID"
  • ER_GRP_RPL_VIEW_CHANGE_UUID_SAME_AS_GROUP_NAME: "The group_replication_view_change_uuid is '%s', which is the same as group_replication_name. Please change group_replication_view_change_uuid to AUTOMATIC"
  • ER_GRP_RPL_VIEW_CHANGE_UUID_IS_SAME_AS_ANONYMOUS_TO_GTID_UUID: "The group_replication_group_name '%s' is the same as the UUID value for ASSIGN_GTIDS_TO_ANONYMOUS_TRANSACTIONS in a server channel"

If server UUID is the same as configured on group_replication_group_view_change_uuid it will abort when trying to join to group with message:

  • ER_GRP_RPL_SERVER_UUID_IS_INCOMPATIBLE_WITH_GRP_VIEW_CHANGE_UUID: "Member server_uuid is incompatible with the group. Server_uuid %s matches group_replication_group_view_change_uuid %s."

If a member joins the group but on compatibility check has a different value of group_replication_group_view_change_uuid than the group it will exit from it and log the error: * ER_GRP_RPL_VIEW_CHANGE_UUID_DIFF_FROM_GRP: The member is configured with a view_change_uuid option value '%s' different from the group '%s'. The member will now exit the group.

Deployment and installation

To a group be able to use this functionality all members shall have same value of group_replication_view_change_uuid of member that started the group.

Protocol

On member join it does a state exchange with members of the group and it will execute compatibility tests with configuration of the group.

A joiner will have is group_replication_view_change_uuid configuration compared with remaining members, it needs to be equal to all members to be allowed to join.

In a group with members having an older version that don't have group_replication_view_change_uuid the joining member shall use AUTOMATIC to be allowed to join.

Failure model specification

Since the compatibility is check on the member join call, it does not follow group_replication_exit_state_action, the join leaves the group by returning a error to START GROUP_REPLICATION.

Summary of Changes

Server will transmit his group_replication_view_change_uuid on member info structure to allow joining server to confirm is using the same value.

That infomartion will be sent on Plugin_gcs_message:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ class Group_member_info : public Plugin_gcs_message { /* ... */

// Length of the payload item: variable
PIT_VIEW_CHANGE_UUID = 21,

// No valid type codes can appear after this one.
PIT_MAX = 22

};

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When a server is joining it will confirm has the same group_replication_view_change_uuid than all the members of the group.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // pseudo code

  for (member : members_in_the_group) {
    if (joiner.change_view_uuid() != member.change_view_uuid()) {
      abort_join();
    }
  }

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Member info shall have group_replication_view_change_uuid configured as AUTOMATIC by default, so if a member don't have defined it the joiner knows it has default configuration.

On certification.cc it will be added a variable with view change uuid that will be used when logging View_change_pipeline_action.

When executing a CHANGE REPLICATION SOURCE TO ASSIGN_GTIDS_TO_ANONYMOUS_TRANSACTION it shall validate that specified UUID is different from group_replication_view_change_uuid.



Copyright (c) 2000, 2025, Oracle Corporation and/or its affiliates. All rights reserved.