Updating a Sharded PostgreSQL cluster

Written by

Yandex Cloud

Updated at January 22, 2026

Note

This feature is at the Preview stage.

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

Management console

REST API

gRPC API

Navigate to the folder dashboard and select Yandex Managed Service for Sharded PostgreSQL.
Select your cluster and click Edit in the top panel.
Under Basic parameters:
- Edit the cluster name and description.
- Delete or add new labels.
Under Network settings, select security groups for the cluster.
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. If employing a coordinator, update the coordinator host configuration 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 disk type and storage size.
Change additional cluster settings:
- Password from Sharded PostgreSQL console. It may be from 8 to 128 characters long.
- 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 level 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 window: Maintenance window settings:
  - To enable maintenance at any time, select arbitrary (default).
  - To specify the preferred maintenance start time, select by schedule and specify the desired day of the week and UTC hour. For example, you can choose a time when the cluster is least loaded.
  Maintenance operations are carried out both on enabled and disabled clusters. They may include updating the DBMS, applying patches, and so on.
- DataLens access: Enables you to analyze cluster data in Yandex DataLens.
- WebSQL access: Enables SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL.
- Access from Data Transfer: Enable this option to allow cluster access from Yandex Data Transfer.
- 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.
Under DBMS settings, click Settings and change the cluster-level DBMS settings.
Click Save changes.

Get an IAM token for API authentication and put it into an environment variable:
```
export IAM_TOKEN="<IAM_token>"
```
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_against_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>",
          "diskTypeId": "<disk_type>"
        }
      },
      "coordinator": {
        "resources": {
          "resourcePresetId": "<coordinator_host_class>",
          "diskSize": "<storage_size_in_bytes>",
          "diskTypeId": "<disk_type>"
        }
      },
      "infra": {
        "resources": {
          "resourcePresetId": "INFRA_host_class",
          "diskSize": "<storage_size_in_bytes>",
          "diskTypeId": "<disk_type>"
        },
        "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 take their defaults unless explicitly provided in the request. To avoid this, list the settings you want to change in the updateMask parameter.
- name: Cluster name.
- securityGroupIds: Security group IDs.
- 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 following values are used by default: "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.
        
        diskTypeId: Disk type.
      - coordinator: For advanced sharding, configure the following coordinator settings:
        
        resources: Resource parameters:
        
        resourcePresetId: Host class.
        
        diskSize: Disk size, in bytes.
        
        diskTypeId: Disk type.
      - infra: For standard sharding, set the following INFRA host settings:
        
        resources: Resource parameters:
        
        resourcePresetId: Host class.
        
        diskSize: Disk size, in bytes.
        
        diskTypeId: Disk type.
        
        router: Router configuration:
        
        showNoticeMessages: Show information notifications, true or false.
        
        timeQuantiles: Array of time quantile strings for displaying statistics. The following values are used by default: "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: From 0 to 23 hours.
    - minutes: From 0 to 59 minutes.
    - seconds: From 0 to 59 seconds.
    - nanos: From 0 to 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.

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"

View the server response to make sure your request was successful.

Get an IAM token for API authentication and put it into an 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 that the repository contents reside in the ~/cloudapi/ directory.

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

{
  "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_against_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>",
          "disk_type_id": "<disk_type>"
        }
      },
      "coordinator": {
        "resources": {
          "resource_preset_id": "<coordinator_host_class>",
          "disk_size": "<storage_size_in_bytes>",
          "disk_type_id": "<disk_type>"
        }
      },
      "infra": {
        "resources": {
          "resource_preset_id": "INFRA_host_class",
          "disk_size": "<storage_size_in_bytes>",
          "disk_type_id": "<disk_type>"
        },
        "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:

update_mask: List of settings you want 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 take their defaults unless explicitly provided in the request. To avoid this, list the settings you want to change in the update_mask parameter.
name: Cluster name.
security_group_ids: Security group IDs.
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.
      - disk_type_id: Disk type.
    - coordinator: For advanced sharding, configure the following coordinator settings:
      - resources: Resource parameters:
        
        resource_preset_id: Host class.
        
        disk_size: Disk size, in bytes.
        
        disk_type_id: Disk type.
    - infra: For standard sharding, set the following INFRA host settings:
      - resources: Resource parameters:
        
        resource_preset_id: Host class.
        
        disk_size: Disk size, in bytes.
        
        disk_type_id: Disk type.
      - 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: From 0 to 23 hours.
  - minutes: From 0 to 59 minutes.
  - seconds: From 0 to 59 seconds.
  - nanos: From 0 to 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.

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

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

Updating a Sharded PostgreSQL cluster

Was the article helpful?