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

Managing PostgreSQL cluster hosts

Written by
Updated at March 19, 2026

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 your cluster and select the Hosts tab.

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 set a different folder for any specific command using the --folder-name or --folder-id options.

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 get the cluster name from 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 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.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 get 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. Navigate to the Managed Service for PostgreSQL service.

  2. Click the cluster name and navigate to the Hosts tab.

  3. Click Create host.

  4. Specify the following host settings:

    • Availability zone.
    • Subnet (if the required subnet is not on the list, create it).
    • Replication source (if you use cascading replication).
    • To make the host accessible from outside Yandex Cloud, select Public access.

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 set a different folder for any specific command using the --folder-name or --folder-id options.

To create a host:

  1. To choose a subnet for your new host, 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 more than one subnet, make sure to specify the subnet ID; otherwise, Managed Service for PostgreSQL will automatically select a single subnet. You can get the cluster name from the list of clusters in the folder.

    You can specify extra options in the --host argument 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.

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

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

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

    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.

    How can I change these timeouts?

    Add a timeouts section to the cluster description, e.g.:

    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: Controls whether the host is accessible 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 the parameter. See PostgreSQL settings for descriptions and possible values of the settings.

    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.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: Controls whether the host is accessible 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 the parameter. See PostgreSQL settings for a description and possible values for each setting.

    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.

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. Navigate to the Managed Service for PostgreSQL service.

  2. Click the name of your cluster and select 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. Enable Public access if you want the host to be accessible from outside of Yandex Cloud.

  5. Click Save.

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 set a different folder for any specific command using the --folder-name or --folder-id options.

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

To change the cluster host settings:

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

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

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

  2. In the Managed Service for PostgreSQL cluster description, change the attributes of the host section 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. 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.

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

    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.

    How can I change these timeouts?

    Add a timeouts section to the cluster description, e.g.:

    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 string of settings to update.

    • hostName: FQDN of the host being updated.

    • assignPublicIp: Controls whether the host is accessible 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 the parameter. See PostgreSQL settings for a description and possible values for each setting.

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

    • host_name: FQDN of the host being updated.

    • assign_public_ip: Controls whether the host is accessible 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 the parameter. See PostgreSQL settings for a description and possible values for each setting.

    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.

Warning

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

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. Navigate to the Managed Service for PostgreSQL service.
  2. Click the name of your cluster and select 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 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 set a different folder for any specific command using the --folder-name or --folder-id options.

To delete a host from a 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.

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

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

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

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

    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.

    How can I change these timeouts?

    Add a timeouts section to the cluster description, e.g.:

    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 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.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 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
Stopping and starting a cluster
Next
Migrating hosts to a different availability zone