Upgrading PostgreSQL version
You can upgrade a Managed Service for PostgreSQL cluster to any supported version.
Note
- Upgrades are unavailable for Managed Service for PostgreSQL clusters optimized for
1C:Enterprise
. The names of these versions end with-1c
. - You cannot upgrade a regular cluster version to a version optimized for
1C:Enterprise
(e.g., from version 14 to version 14-1c).
You can only upgrade to a version that immediately follows the current one, such as version 11 to 12. Upgrades to higher versions are performed in steps. To upgrade PostgreSQL from version 11 to version 13, for instance, follow the steps: 11 → 12 → 13.
In single-host clusters, the only master host is brought out of its running state for upgrades. During an upgrade, these clusters will be unavailable for reading and writing.
In multi-host clusters, upgrades follow the procedure below:
-
The master is unavailable during upgrades. During this time, the replicas continue running in read-only mode. No failover occurs. After an upgrade, the master is not returned to a running state until all the replicated hosts are upgraded. It is temporarily unavailable even for reading.
-
The replicas are sequentially made unavailable and upgraded. The replicas are queued randomly. Following an upgrade, the replicas are returned to a running state in read-only mode.
A two-host cluster is unavailable while its replica is upgrading. In a cluster of three or more hosts, at least one replica will be available for reading.
-
The master returns to a running state.
To learn more about updates within a single version and host maintenance, see Maintenance.
Before a version upgrade
Make sure this does not affect your applications:
- See the PostgreSQL changelog
to see how upgrades may affect your applications or installed extensions. - Try a version upgrade on a test cluster. You can deploy it from a backup of the main cluster.
- Create a backup of the main cluster directly before the version upgrade.
Upgrading a cluster
Alert
- Once your DBMS is upgraded, you cannot roll a cluster back to the previous version.
- The success of a PostgreSQL version upgrade depends on multiple factors, including cluster settings and data stored in databases. We recommend that you begin by upgrading a test cluster that has the same data and settings.
- Go to the folder page and select Managed Service for PostgreSQL.
- Select the cluster from the list and click
- In the Version field, select a new version number.
- Click Save changes.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
-
Get a list of your PostgreSQL clusters using this command:
yc managed-postgresql cluster list
-
Get information about a cluster and check the PostgreSQL version in the
config.version
parameter:yc managed-postgresql cluster get <cluster_name_or_ID>
-
Run the PostgreSQL upgrade:
yc managed-postgresql cluster update <cluster_name_or_ID> \ --postgresql-version <new_version_number>
-
Open the current Terraform configuration file with an infrastructure plan.
For more information about how to create this file, see Creating clusters.
For a complete list of available Managed Service for PostgreSQL cluster configuration fields, see the Terraform provider documentation
. -
Under
cluster_config
of the required Managed Service for PostgreSQL cluster, add theversion
field or edit it if it already exists:resource "yandex_mdb_postgresql_cluster" "<cluster_name>" { ... cluster_config { version = "<PostgreSQL_version>" } }
-
Make sure the settings are correct.
-
Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.
-
Run the command:
terraform validate
If there are errors in the configuration files, Terraform will point to them.
-
-
Confirm updating the resources.
-
Run the command to view planned changes:
terraform plan
If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
-
If you are happy with the planned changes, apply them:
-
Run the command:
terraform apply
-
Confirm the update of resources.
-
Wait for the operation to complete.
-
Time limits
A Terraform provider sets the timeout for Managed Service for PostgreSQL cluster operations:
- Creating a cluster, including restoring from a backup: 30 minutes.
- Editing a cluster: 60 minutes.
- Deleting a cluster: 15 minutes.
Operations exceeding the set timeout are interrupted.
How do I change these limits?Add the
timeouts
block to the cluster description, for example:resource "yandex_mdb_postgresql_cluster" "<cluster_name>" { ... timeouts { create = "1h30m" # 1 hour 30 minutes update = "2h" # 2 hours delete = "30m" # 30 minutes } }
-
To upgrade a cluster to a specific PostgreSQL version, use the update REST API method for the Cluster resource or the ClusterService/Update gRPC API call and provide the following in the request:
- Cluster ID in the
clusterId
parameter. To find out the cluster ID, get a list of clusters in the folder. - PostgreSQL version number in the
configSpec.version
parameter. - List of cluster configuration fields to update in the
UpdateMask
parameter.
Warning
This API method overrides all parameters of the object being modified that were not explicitly passed in the request to the default values. To avoid this, list the settings you want to change in the updateMask
parameter (one line separated by commas).
As soon as you run the upgrade, the cluster enters the UPDATING status. Wait for the operation to complete and then check the cluster version.
Cluster upgrade time depends on the database size.
Examples
Let's assume that you need to upgrade your cluster from version 11 to version 12.
-
To get a list of clusters and find out their IDs and names, run this command:
yc managed-postgresql cluster list
+----------------------+---------------+---------------------+--------+---------+ | ID | NAME | CREATED AT | HEALTH | STATUS | +----------------------+---------------+---------------------+--------+---------+ | c9q8p8j2gaih******** | postgre406 | 2021-10-23 12:44:17 | ALIVE | RUNNING | +----------------------+---------------+---------------------+--------+---------+
-
To get information about a cluster named
postgre406
, run the command:yc managed-postgresql cluster get postgre406
id: c9q8p8j2gaih******** ... config: version: "11" ...
-
To upgrade the
postgre406
cluster to version 12, run this command:yc managed-postgresql cluster update postgre406 --postgresql-version 12