Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Updating a Sharded PostgreSQL cluster

Written by
Updated at September 23, 2026
View in Markdown

After creating a cluster, you can edit its basic and advanced settings.

  1. In the management console, select the folder where you want to update a Sharded PostgreSQL cluster.

  2. Navigate to Yandex Managed Service for Sharded PostgreSQL.

  3. Select your cluster and click Edit in the top panel.

  4. Under Basic parameters:

    • Edit the cluster name and description.
    • Delete or add new labels.

  5. Under Network settings, select security groups for the cluster.

    Warning

    For the router to be able to connect to your shard hosts, the Managed Service for Sharded PostgreSQL cluster and the shards and must be in the same security group that allows incoming and outgoing TCP connections to port 6432.

  6. Update the computing resource configuration:

    • For standard sharding, update the infrastructure host configuration under Infrastructure.
    • For advanced sharding, update the router host configuration under Router and the configuration of coordinator hosts under Coordinator.

    To update your computing resource configuration:

    1. Change platform in the Platform field.
    2. Change Type for the VM the hosts are deployed on.
    3. Change the Host class.
    4. Under Storage, change the storage size.

  7. Configure advanced cluster settings:

    • Min. logging level: Execution log will register logs of this or higher level. The available levels are DEBUG, INFO, WARN, ERROR, FATAL, and PANIC. The default is INFO.

    • Backup start time (UTC): Time interval during which the cluster backup starts. Time is specified in 24-hour UTC format. The default time is 22:00 - 23:00 UTC.

    • Retention period for automatic backups, days: Automatic backups will be stored for this many days. The default value is seven days.

    • Maintenance: Maintenance window settings:

      • To allow maintenance at any time, select At any time (default).
      • To specify the preferred maintenance start time, select By schedule and specify the day of the week and the UTC time interval. For example, you can choose the cluster's least busy time.

      Both active and stopped clusters are subject to maintenance operations. These may include DBMS updates, patches, etc.

    • Deletion protection: Manages cluster protection against accidental deletion.

      Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.

  8. Under DBMS settings, click Settings and change the cluster-level DBMS settings.

  9. Click Save changes.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating 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 update cluster and host settings:

  1. View the description of the CLI command for updating a cluster:

    yc managed-sharded-postgresql cluster update --help

  2. Specify the new cluster settings in the update command. Note that our example does not contain all available settings:

    • For a cluster with standard sharding:

      yc managed-sharded-postgresql cluster update <cluster_name_or_ID>  \
 --new-name <cluster_name> \
 --security-group-ids <security_group_IDs> \      
 --infra-resource-preset <host_class> \
 --infra-disk-size <storage_size_in_GB> \
 --deletion-protection \
 --maintenance-window type=<maintenance_type>,`
                      `day=<day_of_week>,`
                      `hour=<sequence_number_of_hour_interval> \
 --websql-access=<true_or_false> \
 --backup-window-start <backup_start_time> \
 --backup-retain-period-days <automatic_backup_retention_period>

    • For a cluster with advanced sharding:

      yc managed-sharded-postgresql cluster update <cluster_name_or_ID>  \
  --new-name <cluster_name> \
  --security-group-ids <security_group_IDs> \      
  --router-resource-preset <host_class> \
  --router-disk-size <storage_size_in_GB> \
  --coordinator-resource-preset <host_class> \
  --coordinator-disk-size <storage_size_in_GB> \
  --deletion-protection \
  --maintenance-window type=<maintenance_type>,`
                         `day=<day_of_week>,`
                         `hour=<sequence_number_of_hour_interval> \
  --websql-access=<true_or_false> \
  --backup-window-start <backup_start_time> \
  --backup-retain-period-days <automatic_backup_retention_period>

      Where:

      • <cluster_name_or_ID>: Cluster name or ID which you can get with the list of clusters in the folder.

      • --new-name: New cluster name.

      • --security-group-ids: List of security group IDs.

        Warning

        For the router to be able to connect to your shard hosts, the Managed Service for Sharded PostgreSQL cluster and the shards and must be in the same security group that allows incoming and outgoing TCP connections to port 6432.

      • --infra-resource-preset, --router-resource-preset, and --coordinator-resource-preset: INFRA, ROUTER, and COORDINATOR host classes, respectively.

      • --infra-disk-size, --router-disk-size, and --coordinator-disk-size: INFRA, ROUTER, and COORDINATOR host storage sizes, respectively.

      • --deletion-protection: Cluster protection from accidental deletion, true or false.

        Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.

      • --maintenance-window: Maintenance window settings that apply to both running and stopped clusters. The type setting defines the maintenance type:

        • anytime: Any time (default).
        • weekly: On a schedule. For this value, also specify the following:

          • day: Day of week, i.e., MON, TUE, WED, THU, FRI, SAT, or SUN.

          • hour: Sequence number of UTC hour interval, from 1 to 24.

            For example, 1 stands for the interval from 00:00 to 01:00, and 5, from 04:00 to 05:00.

      • --backup-retain-period: Automatic backup retention period, in days.

      • --backup-window-start: The cluster backup start time, set in UTC format HH:MM:SS. If the time is not set, the backup will start at 22:00 UTC.

To update the cluster service configuration:

  1. View the description of the CLI command to update the configuration:

    yc managed-sharded-postgresql cluster update-config --help

  2. Specify the new configuration settings in the update command. Note that our example does not contain all available settings:

    yc managed-sharded-postgresql cluster update-config <cluster_name_or_ID>  \
  --set router.show_notice_messages=<show_information_notifications>,`
        router.prefer_same_availability_zone=<routing_priority_to_router_availability_zone>,`
        router.default_route_behavior=<allow_multishard_requests>,`
        router.time_quantiles="<list_of_time_quantiles_for_displaying_statistics>"

    Where:

    • <cluster_name_or_ID>: Cluster name or ID which you can get with the list of clusters in the folder.
    • --set: New router configuration:
      • router.show_notice_messages: Show information notifications, true or false.
      • router.prefer_same_availability_zone: Enable priority routing of read requests to the router's availability zone, true or false.
      • router.default_route_behavior: Router's multishard request execution policy. Possible values: BLOCK or ALLOW.
      • router.time_quantiles: List of time quantiles for displaying statistics. The default value is "0.5,0.75,0.9,0.95,0.99,0.999,0.9999".

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

    For information on how to create this file, see Creating a cluster.

    For the complete list of configurable Managed Service for Sharded PostgreSQL cluster fields, see this Terraform provider guide.

  2. Change the resource descriptions:

    • For a cluster with standard sharding:

      resource "yandex_mdb_sharded_postgresql_cluster" "<cluster_name>" {
  ...
  security_group_ids = [ "<list_of_security_group_IDs>" ]
  config = {
    sharded_postgresql_config = {
      infra = {
        resources = {
          resource_preset_id = "<host_class>"
          disk_size          = <storage_size_in_GB>
        }
        router = {
          show_notice_messages = <show_information_notifications>
          prefer_same_availability_zone = <routing_priority_to_router_availability_zone>
          default_route_behavior = <allow_multishard_requests>
          time_quantiles = [ <list_of_time_quantiles_for_displaying_statistics> ]
        }
      }
    }
    deletion_protection = <protect_cluster_from_deletion>
    maintenance_window = {
      type = "<maintenance_type>"
      day  = "<day_of_week>"
      hour = <sequence_number_of_hour_interval>
    }
    backup_retain_period_days = <number_of_days>
    backup_window_start = {
      hours   = <backup_start_hour>
      minutes = <backup_start_minute>
    }
  }
}

    • For a cluster with advanced sharding:

      resource "yandex_mdb_sharded_postgresql_cluster" "<cluster_name>" {
  ...
  security_group_ids = [ "<list_of_security_group_IDs>" ]
  config = {
    sharded_postgresql_config = {
      router = {
        resources = {
          resource_preset_id = "<host_class>"
          disk_size          = <storage_size_in_GB>
        }
        config = {
          show_notice_messages = <show_information_notifications>
          prefer_same_availability_zone = <routing_priority_to_router_availability_zone>
          default_route_behavior = <allow_multishard_requests>
          time_quantiles = [ <list_of_time_quantiles_for_displaying_statistics> ]
        }
      }
      coordinator = {
        resources = {
          resource_preset_id = "<host_class>"
          disk_size          = <storage_size_in_GB>
        }
      }
    }
    deletion_protection = <protect_cluster_from_deletion>
    maintenance_window = {
      type = "<maintenance_type>"
      day  = "<day_of_week>"
      hour = <sequence_number_of_hour_interval>
    }
    backup_retain_period_days = <number_of_days>
    backup_window_start = {
      hours   = <backup_start_hour>
      minutes = <backup_start_minute>
    }
  }
}

    Where:

    • security_group_ids: Security group IDs.

      Warning

      For the router to be able to connect to your shard hosts, the Managed Service for Sharded PostgreSQL cluster and the shards and must be in the same security group that allows incoming and outgoing TCP connections to port 6432.

    • deletion_protection: Cluster deletion protection, true or false.

      Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.

    • config: Cluster settings:

      • sharded_postgresql_config: Sharded PostgreSQL settings:

        • router: Router settings:

          • config: Router configuration:

            • show_notice_messages: Show information notifications, true or false.
            • time_quantiles: Array of time quantile strings for displaying statistics. The default values are "0.5", "0.75", "0.9", "0.95", "0.99", "0.999", "0.9999".
            • default_route_behavior: Router's multishard request execution policy. Possible values: BLOCK or ALLOW.
            • prefer_same_availability_zone: Enable priority routing of read requests to the router's availability zone, true or false.

          • resources: ROUTER host resource parameters:

            • resource_preset_id: Host class.
            • disk_size: Disk size, in GB.

        • coordinator: Coordinator settings:

          • resources: Resource parameters:
            • resource_preset_id: Host class.
            • disk_size: Disk size, in GB.

        • infra: INFRA host settings:

          • resources: Resource parameters:

            • resource_preset_id: Host class.
            • disk_size: Disk size, in GB.

          • router: Router configuration:

            • show_notice_messages: Show information notifications, true or false.
            • time_quantiles: Array of time quantile strings for displaying statistics. The default values are "0.5", "0.75", "0.9", "0.95", "0.99", "0.999", "0.9999".
            • default_route_behavior: Router's multishard request execution policy. Possible values: BLOCK or ALLOW.
            • prefer_same_availability_zone: Enable priority routing of read requests to the router's availability zone, true or false.

    • backup_window_start: Backup window settings.

      Here, specify the backup start time. Allowed values:

      • hours: From 0 to 23 hours.
      • minutes: Between 0 and 59 minutes.

    • backup_retain_period_days: Cluster backup retention period in days. Possible values: between 7 and 60 days.

    • maintenance_window: Maintenance window settings:

      • type: Maintenance type. The possible values include:

        • ANYTIME: Any time.
        • WEEKLY: On a schedule.

      • day: Day of week for the WEEKLY type, i.e., MON, TUE, WED, THU, FRI, SAT, or SUN.

      • hour: UTC hour interval for the WEEKLY type, from 1 to 24.

        For example, 1 stands for the interval from 00:00 to 01:00, and 5, from 04:00 to 05:00.

  3. 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.

    2. Run this command:

      terraform validate

      Terraform will show any errors found in your configuration files.

  4. Confirm updating the resources.

    1. Run this command to view the planned changes:

      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.

    2. If everything looks correct, apply the changes:

      1. Run this command:

        terraform apply

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

    Timeouts

    The Terraform provider sets the following timeouts for Managed Service for Sharded PostgreSQL cluster operations:

    • Creating a cluster, including by restoring it from a backup: 30 minutes.
    • Updating a cluster: 60 minutes.
    • Deleting a cluster: 15 minutes.

    Operations exceeding the timeout are aborted.

    How to change these limits

    Add the timeouts section to your cluster description, such as the following:

    resource "yandex_mdb_sharded_postgresql_cluster" "<cluster_name>" {
  ...
  timeouts {
    create = "1h30m" # 1 hour 30 minutes
    update = "2h"    # 2 hours
    delete = "30m"   # 30 minutes
  }
}

  1. Get an IAM token for API authentication and put it into an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Create a file named body.json and paste the following code into it:

    {
  "updateMask": "<list_of_parameters_to_update>",
  "name": "<cluster_name>",
  "description": "<description>",
  "environment": "<environment>",
  "securityGroupIds": [
    "<security_group_1_ID>",
    "<security_group_2_ID>",
    ...
    "<security_group_N_ID>"
  ],
  "deletionProtection": <protect_cluster_from_deletion>,
  "configSpec": {
    "spqrSpec": {
      "router": {
        "config": {
          "showNoticeMessages": <show_information_notifications>,
          "timeQuantiles": [
            <list_of_time_quantiles_for_displaying_statistics>
          ],
          "defaultRouteBehavior": "<allow_multishard_requests>",
          "preferSameAvailabilityZone": <routing_priority_to_router_availability_zone>
        },
        "resources": {
          "resourcePresetId": "<router_host_class>",
          "diskSize": "<storage_size_in_bytes>"
        }
      },
      "coordinator": {
        "resources": {
          "resourcePresetId": "<coordinator_host_class>",
          "diskSize": "<storage_size_in_bytes>"
        }
      },
      "infra": {
        "resources": {
          "resourcePresetId": "INFRA_host_class",
          "diskSize": "<storage_size_in_bytes>"
        },
        "router": {
          "showNoticeMessages": <show_information_notifications>,
          "timeQuantiles": [
            <list_of_time_quantiles_for_displaying_statistics>
          ],
          "defaultRouteBehavior": "<allow_multishard_requests>",
          "preferSameAvailabilityZone": <routing_priority_to_router_availability_zone>
        }
      },
      "consolePassword": "<Sharded_PostgreSQL_console_password>",
      "logLevel": "<logging_level>"
    },
    "backupWindowStart": {
      "hours": "<hours>",
      "minutes": "<minutes>",
      "seconds": "<seconds>",
      "nanos": "<nanoseconds>"
    },
    "backupRetainPeriodDays": "<number_of_days>",
    "maintenanceWindow": {
      "weeklyMaintenanceWindow": {
        "day": "<day_of_week>",
        "hour": "<hour>"
      }
    }
  }
}

    Where:

    • updateMask: Comma-separated list of parameters to update.

      Warning

      When you update a cluster, all parameters of the object you are modifying will be reset to their defaults unless explicitly provided in the request. To avoid this, list the settings you want to change in the updateMask parameter.

    • name: New cluster name.

    • securityGroupIds: Security group IDs.

      Warning

      For the router to be able to connect to your shard hosts, the Managed Service for Sharded PostgreSQL cluster and the shards and must be in the same security group that allows incoming and outgoing TCP connections to port 6432.

    • deletionProtection: Cluster deletion protection, true or false.

      Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.

    • configSpec: Cluster settings:

      • spqrSpec: Sharded PostgreSQL settings.

        • router: For advanced sharding, configure the following router settings:

          • config: Router configuration:

            • showNoticeMessages: Show information notifications, true or false.
            • timeQuantiles: Array of time quantile strings for displaying statistics. The default values are "0.5", "0.75", "0.9", "0.95", "0.99", "0.999", "0.9999".
            • defaultRouteBehavior: Router's multishard request execution policy. Possible values: BLOCK or ALLOW.
            • preferSameAvailabilityZone: Enable priority routing of read requests to the router's availability zone, true or false.

          • resources: ROUTER host resource parameters:

            • resourcePresetId: Host class.
            • diskSize: Disk size in bytes.

          • coordinator: For advanced sharding, configure the following coordinator settings:

            • resources: Resource parameters:
              • resourcePresetId: Host class.
              • diskSize: Disk size in bytes.

          • infra: For standard sharding, set the following INFRA host settings:

            • resources: Resource parameters:

              • resourcePresetId: Host class.
              • diskSize: Disk size in bytes.

            • router: Router configuration:

              • showNoticeMessages: Show information notifications, true or false.
              • timeQuantiles: Array of time quantile strings for displaying statistics. The default values are "0.5", "0.75", "0.9", "0.95", "0.99", "0.999", "0.9999".
              • defaultRouteBehavior: Router's multishard request execution policy. Possible values: BLOCK or ALLOW.
              • preferSameAvailabilityZone: Enable priority routing of read requests to the router's availability zone, true or false.

          • consolePassword: Sharded PostgreSQL console password.

          • logLevel: Query logging level: DEBUG, INFO, WARNING, ERROR, FATAL, PANIC.

      • backupWindowStart: Backup window settings.

        Here, specify the backup start time. Allowed values:

        • hours: Between 0 and 23 hours.
        • minutes: Between 0 and 59 minutes.
        • seconds: Between 0 and 59 seconds.
        • nanos: Between 0 and 999999999 nanoseconds.

      • backupRetainPeriodDays: Number of days to retain the cluster backup. Possible values: between 7 and 60 days.

    • maintenanceWindow: Maintenance window settings:

      • day: Day of the week, in DDD format, for scheduled maintenance.
      • hour: Hour of day, in HH format, for scheduled maintenance. The valid values range from 1 to 24.

  3. Call the Cluster.Update method, e.g., via the following cURL request:

    curl \
  --request PATCH \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://mdb.api.cloud.yandex.net/managed-spqr/v1/clusters/<cluster_ID>' \
  --data "@body.json"

    You can get the cluster ID with the list of clusters in the folder.

  4. Check the server response to make sure your request was successful.

  1. Get an IAM token for API authentication and put it into an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

  3. Create a file named body.json and paste the following code into it:

    {
  "cluster_id": "<cluster_ID>",
  "update_mask": {
    "paths": [
      <list_of_settings_to_update>
    ]
  },
  "name": "<cluster_name>",
  "description": "<description>",
  "security_group_ids": [
    "<security_group_1_ID>",
    "<security_group_2_ID>",
    ...
    "<security_group_N_ID>"
  ],
  "deletion_protection": <protect_cluster_from_deletion>,
  "config_spec": {
    "spqr_spec": {
      "router": {
        "config": {
          "show_notice_messages": {
            "value": <show_information_notifications>
          },
          "time_quantiles": [
            <list_of_time_quantiles_for_displaying_statistics>
          ],
          "default_route_behavior": "<allow_multishard_requests>",
          "prefer_same_availability_zone": {
            "value": <routing_priority_to_router_availability_zone>
          }
        },
        "resources": {
          "resource_preset_id": "<router_host_class>",
          "disk_size": "<storage_size_in_bytes>"
        }
      },
      "coordinator": {
        "resources": {
          "resource_preset_id": "<coordinator_host_class>",
          "disk_size": "<storage_size_in_bytes>"
        }
      },
      "infra": {
        "resources": {
          "resource_preset_id": "INFRA_host_class",
          "disk_size": "<storage_size_in_bytes>"
        },
        "router": {
          "show_notice_messages": {
            "value": <show_information_notifications>
          },
          "time_quantiles": [
            <list_of_time_quantiles_for_displaying_statistics>
          ],
          "default_route_behavior": "<allow_multishard_requests>",
          "prefer_same_availability_zone": {
            "value": <routing_priority_to_router_availability_zone>
          }
        }
      },
      "console_password": "<Sharded_PostgreSQL_console_password>",
      "log_level": "<logging_level>"
    },
    "backup_window_start": {
      "hours": "<hours>",
      "minutes": "<minutes>",
      "seconds": "<seconds>",
      "nanos": "<nanoseconds>"
    },
    "backup_retain_period_days": "<number_of_days>"
  },
  "maintenance_window": {
    "weekly_maintenance_window": {
      "day": "<day_of_week>",
      "hour": "<hour>"
    }
  }
}

    Where:

    • cluster_id: Cluster ID which you can get with the list of clusters in the folder.

    • update_mask: List of settings to update as an array of strings (paths[]).

      Format for listing settings
      "update_mask": {
  "paths": [
    "<setting_1>",
    "<setting_2>",
    ...
    "<setting_N>"
  ]
}

      Warning

      When you update a cluster, all parameters of the object you are modifying will be reset to their defaults unless explicitly provided in the request. To avoid this, list the settings you want to change in the update_mask parameter.

    • name: New cluster name.

    • security_group_ids: Security group IDs.

      Warning

      For the router to be able to connect to your shard hosts, the Managed Service for Sharded PostgreSQL cluster and the shards and must be in the same security group that allows incoming and outgoing TCP connections to port 6432.

    • deletion_protection: Cluster deletion protection, true or false.

      Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.

    • config_spec: Cluster settings:

      • spqr_spec: Sharded PostgreSQL settings:

        • router: For advanced sharding, configure the following router settings:

          • config: Router configuration:

            • show_notice_messages: Show information notifications, true or false.
            • time_quantiles: Array of time quantiles for displaying statistics. The following values are used by default: 0.5, 0.75, 0.9, 0.95, 0.99, 0.999, 0.9999.
            • default_route_behavior: Router's multishard request execution policy. Possible values: BLOCK or ALLOW.
            • prefer_same_availability_zone: Enable priority routing of read requests to the router's availability zone, true or false.

          • resources: ROUTER host resource parameters:

            • resource_preset_id: Host class.
            • disk_size: Disk size in bytes.

          • coordinator: For advanced sharding, configure the following coordinator settings:

            • resources: Resource parameters:
              • resource_preset_id: Host class.
              • disk_size: Disk size in bytes.

          • infra: For standard sharding, set the following INFRA host settings:

            • resources: Resource parameters:

              • resource_preset_id: Host class.
              • disk_size: Disk size in bytes.

            • router: Router configuration:

              • show_notice_messages: Show information notifications, true or false.
              • time_quantiles: Array of time quantiles for displaying statistics. The following values are used by default: 0.5, 0.75, 0.9, 0.95, 0.99, 0.999, 0.9999.
              • default_route_behavior: Router's multishard request execution policy. Possible values: BLOCK or ALLOW.
              • prefer_same_availability_zone: Enable priority routing of read requests to the router's availability zone, true or false.

          • console_password: Sharded PostgreSQL console password.

          • log_level: Query logging level: DEBUG, INFO, WARNING, ERROR, FATAL, PANIC.

      • backup_window_start: Backup window settings.

        Here, specify the backup start time. Allowed values:

        • hours: Between 0 and 23 hours.
        • minutes: Between 0 and 59 minutes.
        • seconds: Between 0 and 59 seconds.
        • nanos: Between 0 and 999999999 nanoseconds.

      • backup_retain_period_days: Number of days to retain the cluster backup. Possible values: between 7 and 60 days.

    • maintenance_window: Maintenance window settings:

      • day: Day of the week, in DDD format, for scheduled maintenance.
      • hour: Hour of day, in HH format, for scheduled maintenance. The valid values range from 1 to 24.

  4. Call the ClusterService.Update method, e.g., via the following gRPCurl request:

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/spqr/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d @ \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.spqr.v1.ClusterService.Update \
  < body.json

  5. Check the server response to make sure your request was successful.

Previous
Creating a cluster
Next
Managing cluster hosts