Contact UsTry it for free
© 2025 Direct Cursus Technology L.L.C.

Managing PostgreSQL cluster hosts

Written by
Updated at December 5, 2025

You can add and remove cluster hosts, as well as manage their settings. To learn how to move cluster hosts to a different availability zone, see this guide.

Getting a list of cluster hosts

  1. Go to Managed Service for PostgreSQL.
  2. Click the name of the cluster you need and select the Hosts tab.

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

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

To get a list of cluster hosts, run this command:

yc managed-postgresql host list \
  --cluster-name <cluster_name>

Result:

+----------------------------+----------------------+---------+--------+--------------------+
|            NAME            |      CLUSTER ID      |  ROLE   | HEALTH |      ZONE ID       |
+----------------------------+----------------------+---------+--------+--------------------+
| rc1b***mdb.yandexcloud.net | c9qp71dk1dfg******** | MASTER  | ALIVE  | ru-central1-b      |
| rc1a***mdb.yandexcloud.net | c9qp71dk1dfg******** | REPLICA | ALIVE  | ru-central1-a      |
+----------------------------+----------------------+---------+--------+--------------------+

You can request the cluster name with the list of clusters in the folder.

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

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.ListHosts method, e.g., via the following cURL request:

    curl \
  --request GET \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --url 'https://mdb.api.cloud.yandex.net/managed-postgresql/v1/clusters/<cluster_ID>/hosts'

    You can request 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 the repository contents are stored in the ~/cloudapi/ directory.

  3. Call the ClusterService.ListHosts 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/postgresql/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>"
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.postgresql.v1.ClusterService.ListHosts

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

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

Creating a host

The number of hosts in Managed Service for PostgreSQL clusters is limited by the CPU and RAM quotas allocated to database clusters in your cloud. To review your resource usage, open the Quotas page and find the Managed Databases section.

To create a host:

  1. Go to Managed Service for PostgreSQL.

  2. Click the name of your cluster and open the Hosts tab.

  3. Click Create host.

  4. Specify the following host settings:

    • Availability zone.
    • Subnet (select a subnet from the list or create a new subnet).
    • Replication source (if you use cascading replication).
    • If needed, select Public access to enable external access to the host from outside Yandex Cloud.

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

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

To create a host:

  1. To choose a subnet for your new host, first get the list of all cluster subnets:

    yc vpc subnet list

    Result:

    +----------------------+-----------+----------------------+---------------+-------------------+
|          ID          |   NAME    |      NETWORK ID      |      ZONE     |      RANGE        |
+----------------------+-----------+----------------------+---------------+-------------------+
| b0cl69q1w2e3******** | default-d | enp6rq71w2e3******** | ru-central1-d | [172.16.**.**/20] |
| e2lkj9q1w2e3******** | default-b | enp6rq71w2e3******** | ru-central1-b | [10.10.**.**/16]  |
| e9b0phq1w2e3******** | a-2       | enp6rq71w2e3******** | ru-central1-a | [172.16.**.**/20] |
| e9b9v2q1w2e3******** | default-a | enp6rq71w2e3******** | ru-central1-a | [172.16.**.**/20] |
+----------------------+-----------+----------------------+---------------+-------------------+

    If the required subnet is not on the list, create it.

  2. See the description of the CLI command for adding a host:

    yc managed-postgresql host add --help

  3. Run the command for adding a host:

    yc managed-postgresql host add \
  --cluster-name <cluster_name> \
  --host zone-id=<availability_zone>,subnet-id=<subnet_ID>

    If your availability zone contains multiple subnets, make sure to specify the subnet ID; otherwise, Managed Service for PostgreSQL will select the subnet automatically. You can request the cluster name with the list of clusters in the folder.

    You can specify extra options in the --host parameter to manage public access to the host and cluster replication:

    • Use the host’s replication-source option for manual replication stream management.
    • Use the assign-public-ip option to make the host accessible from outside Yandex Cloud:
      • true: Public access enabled.
      • false: Public access disabled.

Managed Service for PostgreSQL will start the host addition process.

To create a host:

  1. Open the current Terraform configuration file describing your infrastructure.

    To learn how to create this file, see Creating a cluster.

    For a complete list of configurable Managed Service for PostgreSQL cluster fields, refer to the Terraform provider guides.

  2. Add a host section to the Managed Service for PostgreSQL cluster description:

    resource "yandex_mdb_postgresql_cluster" "<cluster_name>" {
  ...
  host {
    name                    = "<host_name>"
    zone                    = "<availability_zone>"
    subnet_id               = "<subnet_ID>"
    replication_source_name = "<replication_source>"
    assign_public_ip        = <public_access_to_host>
  }
}

    Where:

    • name: Host name.
    • zone: Availability zone.
    • subnet_id: Subnet ID.
    • replication_source_name: Replication source, i.e., the name attribute of the corresponding host section.
    • assign_public_ip: Public access to the host, true or false.

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

    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
  }
}

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

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.AddHosts 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-postgresql/v1/clusters/<cluster_ID>/hosts:batchCreate' \
  --data '{
            "hostSpecs": [
              {
                "zoneId": "<availability_zone>",
                "subnetId": "<subnet_ID>",
                "assignPublicIp": <allow_public_access_to_host>,
                "replicationSource": "<host_FQDN>",
                "priority": "<host_priority>",
                "configSpec": {
                  "postgresqlConfig_<PostgreSQL_version>": {
                    <PostgreSQL_settings>
                  }
                }
              },
              { <similar_settings_for_new_host_2> },
              { ... },
              { <similar_settings_for_new_host_N> }
            ]
          }'

    Where hostSpecs is the array of new hosts. Each array element contains the configuration for a single host and has the following structure:

    • zoneId: Availability zone.

    • subnetId: Subnet ID.

    • assignPublicIp: Internet access to the host via a public IP address, true or false.

    • replicationSource: Host’s replication source for manual replication stream management. Specify the FQDN of the host that will be used as the replication source.

    • priority: Host priority relative to all other hosts.

    • configSpec.postgresqlConfig_<PostgreSQL_version>: PostgreSQL settings. Specify each setting on a separate line, separated by commas.

      See the method description for the list of PostgreSQL versions available for this parameter. See PostgreSQL settings for descriptions and possible values of the settings.

    You can request 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 the repository contents are stored in the ~/cloudapi/ directory.

  3. Call the ClusterService.AddHosts 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/postgresql/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>",
        "host_specs": [
          {
            "zone_id": "<availability_zone>",
            "subnet_id": "<subnet_ID>",
            "assign_public_ip": <allow_public_access_to_host>,
            "replication_source": "<host_FQDN>",
            "priority": "<host_priority>",
            "config_spec": {
              "postgresql_config_<PostgreSQL_version>": {
                <PostgreSQL_settings>
              }
            }
          },
          { <similar_settings_for_new_host_2> },
          { ... },
          { <similar_settings_for_new_host_N> }
        ]
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.postgresql.v1.ClusterService.AddHosts

    Where host_specs is an array of new hosts. Each array element contains the configuration for a single host and has the following structure:

    • zone_id: Availability zone.

    • subnet_id: Subnet ID.

    • assign_public_ip: Internet access to the host via a public IP address, true or false.

    • replication_source: Host’s replication source for manual replication stream management. Specify the FQDN of the host that will be used as the replication source.

    • priority: Host priority relative to all other hosts.

    • config_spec.postgresql_config_<PostgreSQL_version>: PostgreSQL settings. Enter each setting on a new line, separated by commas.

      See the method description for the list of PostgreSQL versions available for this parameter. See PostgreSQL settings for descriptions and possible values of the settings.

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

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

Warning

If you cannot connect to the host you added, check that the cluster security group is properly configured for the subnet containing your host.

Updating a host

In a Managed Service for PostgreSQL cluster, you can configure the replication source and public access for each host.

To change the cluster host settings:

  1. Go to Managed Service for PostgreSQL.

  2. Click the name of your cluster and open the Hosts tab.

  3. Find the host you need in the list, click in its row, then select Edit.

  4. Specify new host settings:

    1. Select the host’s replication source for manual replication stream management.

    2. If needed, check Public access to enable external access to the host from outside Yandex Cloud.

  5. Click Save.

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

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

To update the cluster host’s settings, run the following command:

yc managed-postgresql host update <host_name> \
  --cluster-name <cluster_name> \
  --replication-source <source_host_name> \
  --assign-public-ip=<public_access_to_host>

Where:

  • cluster-name: Cluster name.
  • replication-source: Source host name.
  • assign-public-ip: Public access to the host, true or false.

You can get the host name with the list of cluster hosts, and the cluster name, with the list of clusters in the folder.

For manual replication stream management within your cluster, change the value of the host's --replication-source parameter.

To change the cluster host settings:

  1. Open the current Terraform configuration file describing your infrastructure.

    To learn how to create this file, see Creating a cluster.

    For a complete list of configurable Managed Service for PostgreSQL cluster fields, refer to the Terraform provider guides.

  2. In the Managed Service for PostgreSQL cluster description, change the attributes of the host block referring to the host you want to update.

    resource "yandex_mdb_postgresql_cluster" "<cluster_name>" {
  ...
  host {
    replication_source_name = "<replication_source>"
    assign_public_ip        = <public_access_to_host>
  }
}

Where:

  • replication_source_name: Replication source, i.e., the name attribute of the corresponding host section.
  • assign_public_ip: Public access to the host, true or false.

  1. Check if 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.

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

    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
  }
}

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

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.UpdateHosts method, e.g., via the following cURL request:

    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.

    curl \
  --request POST \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://mdb.api.cloud.yandex.net/managed-postgresql/v1/clusters/<cluster_ID>/hosts:batchUpdate' \
  --data '{
            "updateHostSpecs": [
              {
                "updateMask": "assignPublicIp,replicationSource,priority,configSpec.postgresqlConfig_<PostgreSQL>_version",
                "hostName": "<host_FQDN>",
                "assignPublicIp": <allow_public_access_to_host>,
                "replicationSource": "<host_FQDN>",
                "priority": "<host_priority>",
                "configSpec": {
                  "postgresqlConfig_<PostgreSQL_version>": {
                    <PostgreSQL_settings>
                  }
                }
              },
              { <similar_settings_for_host_2_being_changed> },
              { ... },
              { <similar_settings_for_host_N_being_changed> }
            ]
          }'

    Where updateHostSpecs is the array of hosts you are updating. Each array element contains the configuration for a single host and has the following structure:

    • updateMask: Comma-separated list of settings you want to update.

    • hostName: FQDN of the host being updated.

    • assignPublicIp: Internet access to the host via a public IP address, true or false.

    • replicationSource: Host’s replication source for manual replication stream management. Specify the FQDN of the host that will be used as the replication source.

    • priority: Host priority relative to all other hosts.

    • configSpec.postgresqlConfig_<PostgreSQL_version>: PostgreSQL settings. Enter each setting on a new line, separated by commas.

      See the method description for the list of PostgreSQL versions available for this parameter. See PostgreSQL settings for descriptions and possible values of the settings.

    You can request 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 the repository contents are stored in the ~/cloudapi/ directory.

  3. Call the ClusterService.UpdateHosts method, e.g., via the following gRPCurl request:

    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.

    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_host_specs": [
          {
            "update_mask": {
                "paths": [
                  "assign_public_ip",
                  "replication_source",
                  "priority",
                  "config_spec.postgresql_config_16"
                ]
            },
            "host_name": "<host_FQDN>",
            "assign_public_ip": <allow_public_access_to_host>,
            "replication_source": "<host_FQDN>",
            "priority": "<host_priority>",
            "config_spec": {
              "postgresql_config_<PostgreSQL_version>": {
                <PostgreSQL_settings>
              }
            }
          }
        ]
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.postgresql.v1.ClusterService.UpdateHosts

    Where update_host_specs is an array of hosts you want to update. Each array element contains the configuration for a single host and has the following structure:

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

    • host_name: FQDN of the host being updated.

    • assign_public_ip: Internet access to the host via a public IP address, true or false.

    • replication_source: Host’s replication source for manual replication stream management. Specify the FQDN of the host that will be used as the replication source.

    • priority: Host priority relative to all other hosts.

    • config_spec.postgresql_config_<PostgreSQL_version>: PostgreSQL settings. Enter each setting on a new line, separated by commas.

      See the method description for the list of PostgreSQL versions available for this parameter. See PostgreSQL settings for descriptions and possible values of the settings.

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

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

Warning

If you cannot connect to the host after the update, check that the cluster security group is properly configured for the subnet containing your host.

Deleting a host

You can delete a host from a PostgreSQL cluster as long as it is not the only host in the cluster. In order to replace a sole host, you must first create a new host and then delete the old one.

If you are deleting the master host, Managed Service for PostgreSQL will automatically promote the highest priority replica to master.

To delete a host from a cluster:

  1. Go to Managed Service for PostgreSQL.
  2. Click the name of your cluster and open the Hosts tab.
  3. Find the host you need in the list, click in its row, select Delete, and confirm the deletion.

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

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

To delete a host from the cluster, run this command:

yc managed-postgresql host delete <host_name> \
  --cluster-name <cluster_name>

You can get the host name with the list of cluster hosts, and the cluster name, with the list of clusters in the folder.

To delete a host from a cluster:

  1. Open the current Terraform configuration file describing your infrastructure.

    To learn how to create this file, see Creating a cluster.

    For a complete list of configurable Managed Service for PostgreSQL cluster fields, refer to the Terraform provider guides.

  2. Delete the host section referring to the host you want to delete from the Managed Service for PostgreSQL cluster description.

  3. Check if 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. Type yes and press Enter.

    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.

    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
  }
}

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

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.DeleteHosts 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-postgresql/v1/clusters/<cluster_ID>/hosts:batchDelete' \
  --data '{
            "hostNames": [
              "<host_FQDN>"
            ]
          }'

    Where hostNames is an array of strings, each containing an FQDN of the host targeted for deletion.

    You can request 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 the repository contents are stored in the ~/cloudapi/ directory.

  3. Call the ClusterService.DeleteHosts 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/postgresql/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>",
        "host_names": [
          "<host_FQDN>"
        ]
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.postgresql.v1.ClusterService.DeleteHosts

    Where host_names is an array of strings, each containing an FQDN of the host targeted for deletion.

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

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

Previous
Stopping and starting a cluster
Next
Migrating hosts to a different availability zone