Upgrading the PostgreSQL version
You can upgrade a Managed Service for PostgreSQL cluster to any supported version.
Note
You cannot upgrade a regular cluster version to versions optimized for 1С:Enterprise (e.g., from version 14 to version 14-1c).
You can only upgrade to a version that immediately follows the current one, e.g., from version 11 to 12. Upgrades to higher versions are performed in steps. For example, upgrading the PostgreSQL version from 11 to 15 is performed in the following sequence: 11 → 12 → 13 → 14 → 15.
You can upgrade to version 16 only using Yandex Data Transfer. To do so, create a version 16 cluster and transfer data to it from the cluster you want to upgrade.
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 upgrading the version 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.
Upgrading a cluster to PostgreSQL 16
- Create a cluster with PostgreSQL 16.
- Use Data Transfer to transfer data to it from the cluster you want to upgrade.
Upgrading a cluster to PostgreSQL 15 or lower
- Go to the folder page and select Managed Service for PostgreSQL.
- Select the cluster you need from the list and click
Edit. - 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.
To upgrade a cluster to PostgreSQL 15 or lower:
-
Get a list of your PostgreSQL clusters using this command:
yc managed-postgresql cluster list
-
Get information about the cluster you need 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 creating this file, see Creating clusters.
For a complete list of available Managed Service for PostgreSQL cluster configuration fields, see the [Terraform provider documentation](https://terraform-provider.yandexcloud.net/Resources/mdb_postgresql_cluster).
-
In the
cluster_config
section of the required Managed Service for PostgreSQL cluster, add theversion
field or edit the existing one: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 } }
-
-
Get an IAM token for API authentication and place it in the environment variable:
export IAM_TOKEN="<IAM_token>"
-
Use the Cluster.update method and make a request, e.g., via cURL
: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).curl \ --request PATCH \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.cloud.yandex.net/managed-postgresql/v1/clusters/<cluster_ID>' \ --data '{ "updateMask": "configSpec.version", "configSpec": { "version": "<PostgreSQL_version>" } }'
Where:
-
updateMask
: List of parameters to update as a single string, separated by commas.In this case, only one parameter is provided.
-
configSpec.version
: New PostgreSQL version.
You can get the cluster ID with a list of clusters in the folder.
-
-
View the server response to make sure the request was successful.
-
Get an IAM token for API authentication and place it in the environment variable:
export IAM_TOKEN="<IAM_token>"
-
Clone the cloudapi
repository:cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
Below, we assume the repository contents are stored in the
~/cloudapi/
directory. -
Use the ClusterService/Update call and make a request, e.g., via gRPCurl
:Warning
This API method will assign default values to all object parameters not explicitly set in the request. To avoid this, list the settings you want to change in the
update_mask
parameter as an array ofpaths[]
strings.Format for listing settings
"update_mask": { "paths": [ "<setting_1>", "<setting_2>", ... "<setting_N>" ] }
grpcurl \ -format json \ -import-path ~/cloudapi/ \ -import-path ~/cloudapi/third_party/googleapis/ \ -proto ~/cloudapi/yandex/cloud/mdb/postgresql/v1/cluster_service.proto \ -rpc-header "Authorization: Bearer $IAM_TOKEN" \ -d '{ "cluster_id": "<cluster_ID>", "update_mask": { "paths": [ "config_spec.version" ] }, "config_spec": { "version": "<PostgreSQL_version>" } }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.postgresql.v1.ClusterService.Update
Where:
-
update_mask
: List of parameters to update as an array ofpaths[]
strings.In this case, only one parameter is provided.
-
config_spec.version
: New PostgreSQL version.
You can get the cluster ID with a list of clusters in the folder.
-
-
View the server response to make sure the request was successful.
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 following 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