Database in-place major version upgrade overview

Preview — AlloyDB for PostgreSQL

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. You can process personal data for this feature as outlined in the Cloud Data Processing Addendum, subject to the obligations and restrictions described in the agreement under which you access Google Cloud. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This document describes AlloyDB for PostgreSQL database in-place major version upgrades, which let you upgrade a database to a newer version without migrating data or replacing the existing instance.

The PostgreSQL community periodically releases new major versions that contain new features, performance improvements, and security enhancements. After PostgreSQL releases a new major version, AlloyDB adds support for the compatible version. To keep your database up to date, you can upgrade your AlloyDB cluster by upgrading to a higher major version. You can upgrade your cluster by using this in-place upgrade feature or by migrating your data to a new AlloyDB cluster.

For more information, see Database version policies.

In-place major version upgrades are an efficient way to upgrade your cluster's major version for the following reasons:

• AlloyDB retains cluster and instance details and database settings like the instance name, IP address, and database flags after the upgrade.
• You don't need to change application connection strings.
• All the cluster instances (primary and read pool) are upgraded as part of the same operation.

Note: To verify the upgrade process and to check for incompatibilities, we recommend that you verify the upgrade process on a cloned cluster before you upgrade your actual cluster.

In-place major version upgrade workflow

When you start an upgrade on your cluster, AlloyDB performs the following actions:

1. Runs pre-upgrade checks to find incompatibilities that can impact the upgrade.
2. Prepares for the major version upgrade, which includes creating an internal clone of the cluster.
3. Makes the primary instance unavailable. Downtime starts. Reads can still be done through read pools.
4. Initiates a pre-upgrade backup.
5. Upgrades the primary instance.
6. Makes the read pool instances unavailable.
7. Makes the primary instance available. Downtime ends.
8. Initiates a post-upgrade backup.
9. Upgrades read pool instances.

Note: When you perform an in-place major version upgrade, version-specific default values of the database flags might change. For more information, see Configure an instance's database flags.

After the pre-upgrade checks pass, your cluster is cloned to an internal cluster in the same project. The backup and restore needed to clone the cluster might take some time to complete, depending on the size of the database. The following are examples of database size and corresponding backup and restore durations:

• 1TB takes about 30 minutes to clone your cluster.
• 10TB takes about 2 hours to clone your cluster.

During the clone operation, you can continue to use your original cluster. After the clone operation is complete, the upgrade process starts. The primary instance is unavailable for both reads and writes until the primary instance is upgraded. Expected downtime is typically 20 minutes to one hour, and primarily depends on your database schema and the number of objects.

Note: You can continue to use the read pool instances while the primary instance is being upgraded.

If the major version upgrade fails at any step before the primary instance is upgraded, AlloyDB automatically rolls back all changes.

After the primary instance is upgraded, the cluster version is upgraded to the target version and no rollbacks are triggered for any failure after this point. For example, AlloyDB doesn't roll back the cluster if one or more read pool instance upgrades fail. In these situations, contact Google Cloud CLI Support.

For more information, see Upgrade a database in-place major version.

Upgrade status

You can monitor the status of an in-place database major version upgrade operation while it's in progress.

The upgrade process includes the following stages:

• ALLOYDB_PRECHECK
• PG_UPGRADE_CHECK
• PREPARE_FOR_UPGRADE
• PRIMARY_INSTANCE_UPGRADE
• READ_POOL_INSTANCES_UPGRADE
• ROLLBACK(only in case of failure before read pool upgrades)
• CLEANUP

The possible states of these stages include the following:

• NOT_STARTED
• IN_PROGRESS
• SUCCESS
• FAILED
• CANCEL_IN_PROGRESS
• CANCELLED

Upgrade cancellations

You can cancel the upgrade operation until a certain point during the primary instance upgrade. Once that point is crossed, you can't cancel an upgrade.

In the Google Cloud console, the operation isn't cancelable if the Cancel upgrade button is grayed out. Using the Google Cloud CLI or the REST API, you can determine if you can cancel the upgrade by checking upgradeClusterStatus in the upgrade status:

• If cancellable is true, you can cancel the upgrade.
• If cancellable is false or is missing in the status, you can't cancel the upgrade.

Automatic pre- and post-upgrade backups

When you perform a major version upgrade, AlloyDB automatically creates the following continuous backups, where XX is the source major version and YY is the target major version.

• The pre-upgrade backup is created immediately before the upgrade starts. This backup is named using the format pre-upgrade-bkp-pgXX-pgYY-<uuid>. You can use this backup to restore to the pre-upgrade state. Note that restore is not an in-place operation and that it creates a new cluster.
• The post-upgrade backup is created after the primary instance is upgraded. This backup is named using the format post-upgrade-bkp-pgXX-pgYY-<uuid>.

A continuous backup is incremental, which means that the backup stores only the data that changed relative to the previous continuous backup. This approach reduces the size and cost (in resources) of the backup, and speeds up the backup creation process. For more information, see Data backup and recovery overview.

When you view your list of backups, the upgrade backups are listed with type CONTINUOUS. For more information, see View a list of backups.

Performing point-in-time recovery (PITR) requires that a backup of a version is available. Recovery isn't available on the upgraded cluster until the post-upgrade backup, or another backup that is kicked off after the primary instance is upgraded, completes.

What's next

• Upgrade a database in-place major version.