Perform self-service maintenance

You can perform self-service maintenance if you need to apply the latest AlloyDB for PostgreSQL updates to your clusters as soon as possible. Updating to the latest version can unlock AlloyDB features, apply patches, and let you set a deny period to prevent disruption during sensitive time periods.

For more information, see Maintenance overview.

Self-maintenance use cases

AlloyDB typically applies maintenance to your clusters for you, performing maintenance operations to upgrade the database software in clusters. By default, AlloyDB performs maintenance outside of regional business hours. You can optionally set a maintenance window to define a preferred scheduled maintenance time and receive notifications of upcoming scheduled maintenance. For a given release and PostgreSQL version, maintenance is completed first for clusters without maintenance windows, then scheduled for clusters with maintenance windows.

You might decide to perform self-service maintenance for the following reasons:

  • Your cluster skipped maintenance. This occurs if you set up a deny period, or if your cluster was in a bootstrapping state during migration.
  • Your cluster requires an update before scheduled maintenance occurs.
  • You need to set a deny period on a cluster that isn't up to date. Clusters with instances on earlier versions don't always support setting deny periods.
  • You want to run maintenance on a customized or irregular cadence. In this case, you can set a deny period and then perform self-service maintenance when you need it. Deny periods don't block self-service maintenance.

Resource granularity during updates

AlloyDB only supports maintenance at the cluster level. Within the cluster, AlloyDB determines the order of instance updates. AlloyDB attempts and completes maintenance for each instance independently, so it's possible for instances to be on different releases. For example, a cluster might skip maintenance on existing instances due to a deny period and then create an instance on the latest version afterwards.

View the latest available version

See the AlloyDB maintenance changelogs for the latest version. The changelog is updated after maintenance is applied to clusters in all regions. For more information about how latest versions are applied to regions, see Latest version.

View an instance's current version

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

Viewing the version is supported only on the instance level.

  1. To view the instance's current maintenance version, run the gcloud alloydb instances describe command:

    gcloud alloydb instances describe INSTANCE_ID \
--cluster CLUSTER_ID \
--region LOCATION_ID

    Replace the following:

    • INSTANCE_ID: the ID of the instance you are viewing the version for.
    • CLUSTER_ID: the ID of the cluster where the instance is placed.
    • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.

  2. In the response, find the maintenanceVersionName field to see the version that the instance is running. For example:

    "maintenanceVersionName": "POSTGRES_16.20251015.04_00"

Update the cluster to the latest available version

gcloud

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

To update the cluster to the latest version, run the gcloud alloydb clusters update command with the maintenance-version flag:

gcloud alloydb clusters update CLUSTER_ID \
--region LOCATION_ID \
--maintenance-version=latest

Replace the following:

  • CLUSTER_ID: the ID of the cluster to update to the latest version.
  • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.

Example response:

Operation ID: operation-1746645915198-63490b152e3c8-2aed1bd1-3fd73867
Updating cluster...done.

REST v1

This example updates this cluster to the latest version. For a complete list of parameters for this call, see Method: projects.locations.clusters.patch.

Before you use any of the request data, make the following replacements:

  • CLUSTER_ID: the cluster to update to the latest version.
  • PROJECT_ID: the ID of the project where the cluster is placed.
  • LOCATION_ID: the Google Cloud region that this cluster is located in—for example, us-central1.

To update your cluster to the latest version, use the following PATCH request:

PATCH https://alloydb.googleapis.com/v1/{cluster.name=projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID?update_mask=maintenance_version_selection_policy}

The maintenance_version_selection_policy query parameter specifies the version to which to update the cluster's instances.

The request JSON body looks as follows:

{
  "maintenanceVersionSelectionPolicy": "MAINTENANCE_VERSION_SELECTION_POLICY_LATEST",
}

What's next