v2.25 Preview Preview release - not for production v2024.2 LTS Stable release with long-term support v2024.1 STS Stable release with standard-term support v2.20 LTS Stable release with long-term support Unsupported versions

Planned switchover YSQL

Switch application traffic to the standby universe without data loss

Planned switchover is the process of switching write access from the Primary universe to the Standby universe without losing any data (zero RPO). This operation primarily involves updating metadata and typically completes within 30 seconds. However, because application traffic needs to be redirected to the new universe, it is advisable to perform this operation during a maintenance window.

Perform switchover

Assuming universe A is the Primary and universe B is the Standby, use the following steps to perform a planned switchover to change the replication direction from A->B to B->A.

Precheck

  • Check existing replication group health

    To minimize disruptions and the duration of the switchover, ensure that the existing replication is healthy and the lag is under 5 seconds. For information, refer to Monitor xCluster.

  • Check prerequisites

    Ensure that all prerequisites for setting up xCluster are satisfied for the new replication direction. For more information, refer to the xCluster prerequisites.

Automatic mode requirements

If you are performing a switchover in automatic mode, you must not run any DDLs while the switchover is being done. Stop submitting any DDLs and wait for any previously submitted DLLs to be replicated before proceeding. Checking xCluster safe time (see Monitor xCluster) will tell you the latest time up to which DDLs have been replicated. See #26028.

Set up replication in the reverse direction

Set up xCluster Replication from the Standby universe (B) to Primary universe (A) by following the steps in Set up transactional xCluster.

Skip the bootstrap (backup/restore) step, as the data is already present in both universes.

Ensure that the mode of replication used matches the original setup. Continuously monitor the health of the new replication to prevent any unexpected issues post-switchover.

This step puts both universes in read-only mode, allowing universe B to catch up with universe A.

Wait for replication to catch up

Wait for any pending updates to propagate to B:

  1. Get the current time on A.

  2. Wait until the xCluster safe time on B is a few seconds greater than the time obtained in the previous step.

Note

The lag and skew values might be non-zero as they are estimates based on the last time the tablets were polled. Because no new writes can occur during this period, you can be certain that no data is lost within this timeframe.

Fix up sequences and serial columns

Skip this step if you are using xCluster replication automatic mode.

xCluster only replicates sequence data in automatic mode. If you are not using automatic mode, you need to manually synchronize the sequence next values on universe B to match those on universe A. This ensures that new writes on universe B do not conflict with existing data.

Use the nextval function to set the sequence next values appropriately.

Delete the old replication group

Run the following command against A to delete the old replication group.

To drop a replication group, use the following command:

./bin/yugabyted xcluster delete_replication \
    --replication_id <replication_id> \
    --target_address <ip_of_any_target_cluster_node>

To drop a replication group, use the following command:

./bin/yb-admin \
-master_addresses <primary_master_addresses> \
drop_xcluster_replication <replication_group_id> <standby_master_addresses>

You should see output similar to the following:

Outbound xCluster Replication group rg1 deleted successfully

Switch applications to the new Primary universe (B)

The old Standby (B) is now the new Primary universe, and the old Primary (A) is the new Standby universe. Update the application connection strings to point to the new Primary universe (B).