Update the configuration of a global table replica

Prerequisites

Before you begin, install version 5.17.7 or later of the Tablestore SDK for Java and initialize a client.

Feature description

Call updateGlobalTable to update one physical table replica in a global table. Each request identifies the replica by region, instance, and table name and sets at least one of writable and primaryEligible. Use writable in active-passive or multi-active mode to control whether the replica accepts writes. Use primaryEligible only in active-passive mode to mark a replica as eligible to become the primary replica.

public UpdateGlobalTableResponse updateGlobalTable(UpdateGlobalTableRequest request) throws TableStoreException, ClientException

Important

During an active-passive switchover, the current primary replica and the target replica are both writable until you disable writes to the current primary replica. This can cause data inconsistencies. First verify data synchronization and route application writes to the target replica. Then promptly disable writes to the current primary replica. For the complete procedure, see Global Table.

The following example marks the secondary replica in the China (Beijing) region as writable and primary eligible. After data synchronization and application write routing are ready, the example disables writes to the former primary replica in the China (Hangzhou) region to complete the primary replica switchover.

String globalTableId = "gt-01234567-89ab-cdef-0123-456789abcdef";
String globalTableName = "example_table";

GlobalTableTypes.UpdatePhyTable newPrimary =
        new GlobalTableTypes.UpdatePhyTable(
                "cn-beijing", "example-replica-instance", globalTableName);
newPrimary.setWritable(true);
newPrimary.setPrimaryEligible(true);
UpdateGlobalTableResponse prepareResponse = client.updateGlobalTable(
        new UpdateGlobalTableRequest(globalTableId, globalTableName, newPrimary));
System.out.println("Prepare request ID: " + prepareResponse.getRequestId());

// Continue only after data synchronization and application routing are ready.
GlobalTableTypes.UpdatePhyTable oldPrimary =
        new GlobalTableTypes.UpdatePhyTable(
                "cn-hangzhou", "example-primary-instance", globalTableName);
oldPrimary.setWritable(false);
UpdateGlobalTableResponse completeResponse = client.updateGlobalTable(
        new UpdateGlobalTableRequest(globalTableId, globalTableName, oldPrimary));
System.out.println("Complete request ID: " + completeResponse.getRequestId());

After the requests succeed, query the global table information. Verify that the target replica is the writable primary replica and that the former primary replica is a read-only secondary replica.

Parameters

UpdateGlobalTableRequest contains the following parameters.

Name	Type	Description
globalTableId (required)	String	The global table ID. If you did not record the ID, locate the global table by a physical table. For more information, see Query global table information.
globalTableName (required)	String	The global table name, which must match the base table name.
phyTable (required)	GlobalTableTypes.UpdatePhyTable	The physical table replica and configurations to update. Each request can update only one replica.

Physical table replica configuration

phyTable is a GlobalTableTypes.UpdatePhyTable object that contains the following parameters. writable and primaryEligible are individually optional, but you must set at least one of them. Otherwise, the service returns OTSParameterInvalid.

Name	Type	Description
regionId (required)	String	The ID of the region that contains the physical table. Example: `cn-beijing`.
instanceName (required)	String	The name of the instance that contains the physical table.
tableName (required)	String	The physical table name. All physical tables in a global table have the same name.
writable (optional)	Boolean	Specifies whether the physical table accepts writes. If you set this parameter to `false`, write requests sent to the endpoint of the physical table's instance fail.
primaryEligible (optional)	Boolean	Specifies whether the physical table is eligible to become the primary replica in active-passive mode. After a writable secondary replica becomes primary eligible, its role becomes `primary_eligible`. When you disable writes to the current primary replica, the eligible replica becomes `primary`. Do not set this parameter in multi-active mode.