Fail over the primary instance manually

Stay organized with collections Save and categorize content based on your preferences.

This page describes how to test the high availability of an AlloyDB cluster's primary instance by manually redirecting connections to its standby.

About manual failovers

For the sake of high availability, an AlloyDB primary instance comprises two virtual machine (VM) instances: an active VM, which responds to requests, and a standby VM. If AlloyDB detects the unavailability of the active VM, it promotes the standby to act as the new active VM, routing subsequent connections to it.

You can test this high-availability feature by manually failing over your primary instance's active VM. This launches a long-running operation, during which your cluster's primary instance refuses all new connections while AlloyDB shuts off the PosgreSQL server on the active VM, preparing the standby in its stead.

When the operation exits, your cluster's primary instance resumes accepting new connections at its usual IP address. The primary instance works exactly as it did prior to the failover, even though it effectively swapped the roles of its primary and standby VMs during the manual failover operation.

You can confirm that the failover worked by noting the zones of the primary instance's VMs both before and after running this operation, and observing how the reported zones of the active and standby VMs switch places.

Before you begin

  • The Cloud project you are using must have been enabled to access AlloyDB.
  • You must have one of these IAM roles in the Cloud project you are using:
    • roles/alloydb.admin (the AlloyDB Admin predefined IAM role)
    • roles/owner (the Owner basic IAM role)
    • roles/editor (the Editor basic IAM role)

    If you don't have any of these roles, contact your Organization Administrator to request access.



  1. In the Google Cloud console, go to the Clusters page.

    Go to Clusters

  2. Click a cluster in the Resource Name column.
  3. In the Overview page, go to the Instances in your cluster section, choose the primary instance, and click Failover.
  4. In the dialog that appears, enter the instance's ID, and click Trigger failover.


To use the gcloud CLI, you can install and initialize the Google Cloud CLI, or you can use Cloud Shell.

Use the instances failover command to force a primary instance to fail over its standby.

gcloud alloydb instances failover INSTANCE_ID \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
  • INSTANCE_ID: The ID of the instance.
  • REGION_ID: The region where the instance is placed.
  • CLUSTER_ID: The ID of the cluster where the instance is placed.
  • PROJECT_ID: The ID of the project where the cluster is placed.