Modify the number of Paxos replicas of a log stream

If the number of Paxos replicas of a log stream is different from that of full-featured replicas specified in the locality of the tenant due to exceptions, you can execute the ALTER SYSTEM MODIFY statement to specify the paxos_replica_num parameter to modify the number of Paxos replicas.

Limitations

• You can modify the number of Paxos replicas of log streams of all tenants in the sys tenant but modify only the number of Paxos replicas of log streams of the current tenant in a user tenant.

• One log stream of a tenant supports only parallel replica migration tasks and only one replica task at a time, such as a task to add replicas, remove replicas, convert the type of a replica, and modify the number of Paxos replicas of a log stream.

  You can query ongoing replica tasks from the CDB_OB_LS_REPLICA_TASKS view in the sys tenant or from the DBA_OB_LS_REPLICA_TASKS view in a user tenant.

• You can only decrease the value of the paxos_replica_num parameter.

Prerequisites

• You have the ALTER SYSTEM privilege.

• You have the SELECT privilege on the following views:

  • DBA_OB_TENANTS

  • DBA_OB_LS/CDB_OB_LS

  • DBA_OB_LS_LOCATIONS/CDB_OB_LS_LOCATIONS

Procedure

Assume that log stream 1002 of a tenant named tenant1 has four full-featured replicas but the value of the paxos_replica_num parameter is 5. In this case, you can change the value of the paxos_replica_num parameter to 4 to make it consistent with the number of full-featured replicas specified in the locality of the tenant.

1. Log in to the tenant.

   Here is an example:

   obclient -h172.30.xxx.xxx -P2883 -uroot@tenant1#obdemo -pxxxx -A
   

   For more information about how to connect to a database, see Overview (MySQL mode) or Overview (Oracle mode).

2. Query the tenant ID of the tenant.

   • sys tenant

     obclient [oceanbase]> SELECT TENANT_NAME,TENANT_ID FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME='tenant1';
     

   • User tenant

     MySQL mode

     Oracle mode

     Execute the following statement in MySQL mode:

     obclient [oceanbase]> SELECT TENANT_NAME,TENANT_ID,LOCALITY FROM oceanbase.DBA_OB_TENANTS;
     

     Execute the following statement in Oracle mode:

     obclient [SYS]> SELECT TENANT_NAME,TENANT_ID,LOCALITY FROM SYS.DBA_OB_TENANTS;
     

     A sample query result is as follows:

     +-------------+-----------+
     | TENANT_NAME | TENANT_ID |
     +-------------+-----------+
     | tenant1     |      1002 |
     +-------------+-----------+
     1 row in set
     

     The query result shows that the tenant ID is 1002.

     For more information about the fields in the DBA_OB_TENANTS view, see DBA_OB_TENANTS.

3. Query all log streams of the target tenant.

   • sys tenant

     obclient [oceanbase]> SELECT * FROM oceanbase.CDB_OB_LS WHERE TENANT_ID=1002;
     

   • User tenant

     MySQL mode

     Oracle mode

     Execute the following statement in MySQL mode:

     obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_LS;
     

     Execute the following statement in Oracle mode:

     obclient [SYS]> SELECT * FROM SYS.DBA_OB_LS;
     

     A sample query result is as follows:

     +-------+--------+--------------+---------------+-------------+---------------------+----------+---------------------+---------------------+-----------+
     | LS_ID | STATUS | PRIMARY_ZONE | UNIT_GROUP_ID | LS_GROUP_ID | CREATE_SCN          | DROP_SCN | SYNC_SCN            | READABLE_SCN        | FLAG      |
     +-------+--------+--------------+---------------+-------------+---------------------+----------+---------------------+---------------------+-----------+
     |     1 | NORMAL | z1;z2        |             0 |           0 |                NULL |     NULL | 1712455113896017202 | 1712455113896017202 |           |
     |  1001 | NORMAL | z1;z2        |          1001 |        1001 | 1712125812893680165 |     NULL | 1712455113896017202 | 1712455113896017202 |           |
     |  1002 | NORMAL | z1;z2        |          1002 |        1002 | 1712125812908098857 |     NULL | 1712455114041323052 | 1712455113540551113 |           |
     |  1003 | NORMAL | z1;z2        |             0 |           0 | 1712125828880850585 |     NULL | 1712455113896017202 | 1712455113896017202 | DUPLICATE |
     +-------+--------+--------------+---------------+-------------+---------------------+----------+---------------------+---------------------+-----------+
     4 rows in set
     

     The query result shows that the tenant1 tenant has log streams whose IDs are respectively 1, 1001, and 1002, as well as a broadcast log stream whose ID is 1003.

     For more information about the fields in the DBA_OB_LS view, see DBA_OB_LS.

4. Query the replica distribution of each log stream.

   The following example queries the replica distribution and the value of the paxos_replica_num parameter of log stream 1002.

   • sys tenant

     obclient [oceanbase]> SELECT * FROM oceanbase.CDB_OB_LS_LOCATIONS WHERE LS_ID=1002 AND TENANT_ID=1002;
     

     For more information about the fields in the CDB_OB_LS_LOCATIONS view, see CDB_OB_LS_LOCATIONS.

   • User tenant

     MySQL mode

     Oracle mode

     Execute the following statement in MySQL mode:

     obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_LS_LOCATIONS WHERE LS_ID=1002;
     

     Execute the following statement in Oracle mode:

     obclient [SYS]> SELECT * FROM SYS.DBA_OB_LS_LOCATIONS WHERE LS_ID=1002;
     

     A sample query result is as follows:

     +----------------------------+----------------------------+-------+----------------+----------+----------+------+----------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------+--------------+--------------+---------+
     | CREATE_TIME                | MODIFY_TIME                | LS_ID | SVR_IP         | SVR_PORT | SQL_PORT | ZONE | ROLE     | MEMBER_LIST                                                                                                                          | PAXOS_REPLICA_NUMBER | REPLICA_TYPE | LEARNER_LIST | REBUILD |
     +----------------------------+----------------------------+-------+----------------+----------+----------+------+----------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------+--------------+--------------+---------+
     | 2024-01-31 16:50:06.856652 | 2024-01-31 16:52:54.618093 |  1002 | 100.xx.xxx.012 |     5070 |     5105 | z1   | LEADER   | 100.xx.xxx.012:5070:1,100.xx.xxx.001:5071:1706691024376341,100.xx.xxx.003:5073:1706691171162545,100.xx.xxx.004:5074:1706691096303187 |                    5 | FULL         |              | FALSE   |
     | 2024-01-31 16:50:24.450775 | 2024-01-31 16:52:54.760939 |  1002 | 100.xx.xxx.001 |     5071 |     5106 | z1   | FOLLOWER | NULL                                                                                                                                 |                 NULL | FULL         |              | FALSE   |
     | 2024-01-31 16:52:51.216095 | 2024-01-31 16:52:57.135393 |  1002 | 100.xx.xxx.003 |     5073 |     5108 | z2   | FOLLOWER | NULL                                                                                                                                 |                 NULL | FULL         |              | FALSE   |
     | 2024-01-31 16:51:36.356401 | 2024-01-31 16:52:54.686229 |  1002 | 100.xx.xxx.004 |     5074 |     5109 | z3   | FOLLOWER | NULL                                                                                                                                 |                 NULL | FULL         |              | FALSE   |
     +----------------------------+----------------------------+-------+----------------+----------+----------+------+----------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------+--------------+--------------+---------+
     4 rows in set
     

     The query result shows that log stream 1002 has four full-featured replicas but its PAXOS_REPLICA_NUMBER value is 5. You must change the value of the PAXOS_REPLICA_NUMBER parameter to 4.

5. Execute the ALTER SYSTEM MODIFY statement to modify the paxos_replica_num parameter.

   Here is a sample statement:

   ALTER SYSTEM MODIFY LS [=] ls_id PAXOS_REPLICA_NUM [=] paxos_replica_num [TENANT [=] 'tenant_name'];
   

   The parameters in the statement are described as follows:

   • ls_id: the ID of the log stream for which you want to modify the parameter.

   • paxos_replica_num: the number of Paxos replicas of the log stream, which is the number of full-featured replicas specified in the locality of the tenant.

     When you specify the paxos_replica_num parameter, take note of the following considerations:

     • After you modify the value of the paxos_replica_num parameter, both the Paxos replicas and the members in the MEMBER_LIST field of the leader meet the majority principle.

     • The value of the paxos_replica_num parameter must be greater than or equal to the number of members in the MEMBER_LIST of the leader. You can query the MEMBER_LIST field from the CDB_OB_LS_LOCATIONS view in the sys tenant or from the DBA_OB_LS_LOCATIONS view in a user tenant.

     • You can only decrease the value of the paxos_replica_num parameter, and the decrease cannot exceed 1. In this example, you can only change the value to 4.

     If any one of the preceding conditions is not met, the system returns an error.

   • tenant_name: the name of the target tenant. You can specify another tenant in the sys tenant and specify only the current tenant in a user tenant. If this parameter is not specified, the name of the current tenant is used. You cannot use the all, all_user, or all_meta option in this statement to specify all tenants, all user tenants, or all meta tenants.

   Here is an example:

   obclient> ALTER SYSTEM MODIFY LS = 1002 paxos_replica_num = 4;
   

6. Query the replica distribution of the log stream again.

   • sys tenant

     obclient [oceanbase]> SELECT * FROM oceanbase.CDB_OB_LS_LOCATIONS WHERE LS_ID=1002 AND TENANT_ID=1002;
     

   • User tenant

     MySQL mode

     Oracle mode

     Execute the following statement in MySQL mode:

     obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_LS_LOCATIONS WHERE LS_ID=1002;
     

     Execute the following statement in Oracle mode:

     obclient [SYS]> SELECT * FROM SYS.DBA_OB_LS_LOCATIONS WHERE LS_ID=1002;
     

     A sample query result is as follows:

     +----------------------------+----------------------------+-------+----------------+----------+----------+------+----------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------+--------------+--------------+---------+
     | CREATE_TIME                | MODIFY_TIME                | LS_ID | SVR_IP         | SVR_PORT | SQL_PORT | ZONE | ROLE     | MEMBER_LIST                                                                                                                          | PAXOS_REPLICA_NUMBER | REPLICA_TYPE | LEARNER_LIST | REBUILD |
     +----------------------------+----------------------------+-------+----------------+----------+----------+------+----------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------+--------------+--------------+---------+
     | 2024-01-31 16:50:06.856652 | 2024-01-31 17:17:23.032797 |  1002 | 100.xx.xxx.012 |     5070 |     5105 | z1   | LEADER   | 100.xx.xxx.012:5070:1,100.xx.xxx.001:5071:1706691024376341,100.xx.xxx.003:5073:1706691171162545,100.xx.xxx.004:5074:1706691096303187 |                    4 | FULL         |              | FALSE   |
     | 2024-01-31 16:50:24.450775 | 2024-01-31 17:17:22.976381 |  1002 | 100.xx.xxx.001 |     5071 |     5106 | z1   | FOLLOWER | NULL                                                                                                                                 |                 NULL | FULL         |              | FALSE   |
     | 2024-01-31 16:52:51.216095 | 2024-01-31 17:17:23.113112 |  1002 | 100.xx.xxx.003 |     5073 |     5108 | z2   | FOLLOWER | NULL                                                                                                                                 |                 NULL | FULL         |              | FALSE   |
     | 2024-01-31 16:51:36.356401 | 2024-01-31 17:17:23.715470 |  1002 | 100.xx.xxx.004 |     5074 |     5109 | z3   | FOLLOWER | NULL                                                                                                                                 |                 NULL | FULL         |              | FALSE   |
     +----------------------------+----------------------------+-------+----------------+----------+----------+------+----------+--------------------------------------------------------------------------------------------------------------------------------------+----------------------+--------------+--------------+---------+
     4 rows in set
     

     The query result shows that the value of the PAXOS_REPLICA_NUMBER parameter of log stream 1002 is changed to 4.

References

• Add replicas

• Remove replicas

• Convert the type of a replica

• Migrate replicas