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

Managing Sharded PostgreSQL shards

Written by
Updated at September 23, 2026
View in Markdown

Creating a shard

Sharded PostgreSQL shards are based on existing Yandex Managed Service for PostgreSQL clusters residing in the same folder and cloud network as the Sharded PostgreSQL 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.

  1. In the management console, select the folder where you want to create a shard.
  2. Navigate to Yandex Managed Service for Sharded PostgreSQL.
  3. Click the name of your cluster and select the Shards tab.
  4. Click Create shard.
  5. Specify a shard name and select the PostgreSQL cluster whose hosts will serve as data hosts in the Sharded PostgreSQL cluster.
  6. Click Create.

  1. Open the current configuration file with the Managed Service for Sharded PostgreSQL cluster description.

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

  2. Add a resource description:

    resource "yandex_mdb_sharded_postgresql_shard" "<shard_name>" {
  cluster_id = "<cluster_ID>"
  name       = "<shard_name>"
  shard_spec = {
    mdb_postgresql = "<PostgreSQL_cluster_ID>"
  }
}

    Where:

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

    • shard_spec.mdb_postgresql: Managed Service for PostgreSQL cluster ID within the shard.

    For more information, see this Terraform provider guide.

    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. Call the Cluster.AddShard method, e.g., via the following cURL request:

    curl \
  --request POST \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://mdb.api.cloud.yandex.net/managed-spqr/v1/clusters/<cluster_ID>/shards' \
  --data '{
            "shardSpec": {
              "shardName": "<shard_name>",
              "mdbPostgresql": {
                "clusterId": "<PostgreSQL_cluster_ID>"
              }
            }
          }'

    Where:

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

    • mdbPostgresql.clusterId: Managed Service for PostgreSQL cluster ID within the shard.

  3. 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. Call the ClusterService.AddShard 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 '{
        "cluster_id": <cluster_ID>
        "shard_spec": {
          "shard_name": "<shard_name>",
          "mdb_postgresql": {
            "cluster_id": "<PostgreSQL_cluster_ID>"
          }
        }
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.spqr.v1.ClusterService.AddShard

    Where:

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

    • mdb_postgresql.cluster_id: Managed Service for PostgreSQL cluster ID within the shard.

Deleting a shard

Deleting a Sharded PostgreSQL shard does not affect the Managed Service for PostgreSQL cluster.

  1. In the management console, select the folder where you want to delete a shard.
  2. Navigate to Yandex Managed Service for Sharded PostgreSQL.
  3. Click the name of your cluster and select the Shards tab.
  4. Find the shard you need in the list, click in its row, and select Delete.
  5. In the window that opens, click Delete.

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

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

  2. Delete the yandex_mdb_sharded_postgresql_shard resource with the name of the shard you want to delete.

  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 resource changes.

    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.

For more information, see this Terraform provider guide.

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. Call the Cluster.DeleteShard method, e.g., via the following cURL request:

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

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

  3. 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. Call the ClusterService.DeleteShard 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 '{
        "cluster_id": <cluster_ID>,
        "shard_name": "<shard_name>"
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.spqr.v1.ClusterService.DeleteShard

    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.

Previous
Managing cluster hosts
Next
Connecting to a database