[Yandex Cloud documentation](../../index.md) > [Yandex Managed Service for PostgreSQL](../index.md) > [Step-by-step guides](index.md) > Clusters > Updating the PostgreSQL version

# PostgreSQL version update

{% note warning %}

Starting August 12, 2026, existing PostgreSQL clusters version 14 will be automatically upgraded to version 15. We recommend that you do the upgrade yourself in advance.

{% endnote %}

You can upgrade the PostgreSQL version in your Managed Service for PostgreSQL cluster to `18` or lower. Note that you can only upgrade a major version step by step, one version at a time.

How long an upgrade takes depends on the number of affected databases and the number of objects in each of them. The more databases and objects there are, the longer your upgrade will take.

For more information about version upgrades, see [Updating the PostgreSQL major version in Managed Service for PostgreSQL](../concepts/upgrade.md).

To learn about upgrades within the same version and host maintenance, see [Maintenance](../concepts/maintenance.md).

{% note info %}

Upgrade from a standard version to a _1C:Enterprise_ version (e.g., `14` to `14-1c`) is not supported.

{% endnote %}

## Before a version upgrade {#before-update}

Make sure the upgrade will not disrupt your applications:

1. Check the PostgreSQL [release notes](https://www.postgresql.org/docs/release/) to learn how upgrades may affect your applications or installed [extensions](extensions/cluster-extensions.md).
1. Try upgrading a test cluster. You can [deploy](cluster-backups.md#restore) it from a backup of the main cluster.
1. [Back up](cluster-backups.md#create-backup) your main cluster before upgrading.

## Upgrading the PostgreSQL version {#start-update}

{% note warning %}

To upgrade a major version, the following must be free:

* For disks with a capacity of 100 GB or less: At least 10% of the storage volume.
* For disks with a capacity of more than 100 GB: At least 10 GB.

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. Navigate to **Managed Service for PostgreSQL**.
  1. Select your cluster from the list and click ![image](../../_assets/console-icons/pencil.svg) **Edit**.
  1. In the **Version** field, select the new version number.
  1. Click **Save changes**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To upgrade a cluster to PostgreSQL version 15 or lower:

  1. Get a list of your PostgreSQL clusters using this command:

     ```bash
     yc managed-postgresql cluster list
     ```

  1. Get the target cluster details and check its PostgreSQL version in the `config.version` setting:

     ```bash
     yc managed-postgresql cluster get <cluster_name_or_ID>
     ```

  1. Start the PostgreSQL upgrade:

     ```bash
     yc managed-postgresql cluster update <cluster_name_or_ID> \
        --postgresql-version <new_version_number>
     ```

- Terraform {#tf}

    1. Open the current Terraform configuration file with the infrastructure plan.

       To learn how to create this file, see [Creating a cluster](cluster-create.md).

       For the complete list of configurable Managed Service for PostgreSQL cluster fields, see [this Terraform provider guide](../../terraform/resources/mdb_postgresql_cluster.md).

    1. Add the `version` field to the `cluster_config` section of the target Managed Service for PostgreSQL cluster, or update its value if it already exists:

       ```hcl
       resource "yandex_mdb_postgresql_cluster" "<cluster_name>" {
         ...
         cluster_config {
           version = "<PostgreSQL_version>"
         }
       }
       ```

    1. Make sure the settings are correct.

         1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
         1. Run this command:
         
            ```bash
            terraform validate
            ```
         
            Terraform will show any errors found in your configuration files.

    1. Confirm updating the resources.

         1. Run this command to view the planned changes:
         
            ```bash
            terraform plan
            ```
         
            If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
         
         1. If everything looks correct, apply the changes:
            1. Run this command:
         
               ```bash
               terraform apply
               ```
         
            1. Confirm updating the resources.
            1. Wait for the operation to complete.

         {% note warning "Timeouts" %}
         
         The Terraform provider sets the following timeouts for Managed Service for PostgreSQL cluster operations:
         
         * Creating a cluster, including restoration from a backup: 30 minutes.
         * Updating a cluster: 60 minutes.
         * Deleting a cluster: 15 minutes.
         
         Operations exceeding the timeout are aborted.
         
         {% cut "How can I change these timeouts?" %}
         
         Add a `timeouts` section to the cluster description, e.g.:
         
         ```hcl
         resource "yandex_mdb_postgresql_cluster" "<cluster_name>" {
           ...
           timeouts {
             create = "1h30m" # 1 hour 30 minutes
             update = "2h"    # 2 hours
             delete = "30m"   # 30 minutes
           }
         }
         ```
         
         {% endcut %}
         
         {% endnote %}

- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Call the [Cluster.Update](../api-ref/Cluster/update.md) method, e.g., via the following [cURL](https://curl.se/) request:

     {% note warning %}
     
     The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `updateMask` parameter as a single comma-separated string.
     
     {% endnote %}

     ```bash
     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`: Comma-separated string of settings to update.

       Here, we provide only one setting.

     * `configSpec.version`: New PostgreSQL version.

     You can get the cluster ID from the [folder’s cluster list](cluster-list.md#list-clusters).

  1. Check the [server response](../api-ref/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
  1. Call the [ClusterService.Update](../api-ref/grpc/Cluster/update.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

     {% note warning %}
     
     The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `update_mask` parameter as an array of `paths[]` strings.
     
     {% cut "Format for listing settings" %}
     
     ```yaml
     "update_mask": {
         "paths": [
             "<setting_1>",
             "<setting_2>",
             ...
             "<setting_N>"
         ]
     }
     ```
     
     {% endcut %}
     
     {% endnote %}

     ```bash
     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 settings you want to update as an array of strings (`paths[]`).

       Here, we provide only one setting.

     * `config_spec.version`: New PostgreSQL version.

     You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

  1. Check the [server response](../api-ref/grpc/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

Once you launch the upgrade, the cluster status changes to **UPDATING**. Wait for the operation to complete and then check the cluster version.

Cluster upgrade time depends on the database size.

{% note tip %}

Contact [support](https://center.yandex.cloud/support) if you have issues upgrading to version 18.

{% endnote %}

## Examples {#examples}

Suppose you need to upgrade a cluster from version 14 to 15.

{% list tabs group=instructions %}

- CLI {#cli}

   1. To get a list of clusters with their IDs and names, run this command:

      ```bash
      yc managed-postgresql cluster list
      ```

      ```text
      +----------------------+---------------+---------------------+--------+---------+
      |          ID          |     NAME      |     CREATED AT      | HEALTH | STATUS  |
      +----------------------+---------------+---------------------+--------+---------+
      | c9q8p8j2gaih******** |   postgre406  | 2021-10-23 12:44:17 | ALIVE  | RUNNING |
      +----------------------+---------------+---------------------+--------+---------+
      ```

   1. To get information about a cluster named `postgre406`, run the following command:

      ```bash
      yc managed-postgresql cluster get postgre406
      ```

      ```text
        id: c9q8p8j2gaih********
        ...
        config:
          version: "14"
          ...
      ```

   1. To upgrade the `postgre406` cluster to version 15, run this command:

      ```bash
      yc managed-postgresql cluster update postgre406 --postgresql-version 15
      ```

{% endlist %}