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

Migrating PostgreSQL cluster hosts to a different availability zone

Written by
Updated at December 5, 2025

Managed Service for PostgreSQL cluster hosts reside in Yandex Cloud availability zones. To migrate hosts from one availability zone to another, do the following:

  1. Create a subnet in your target availability zone.

  2. Add a host to your cluster:

    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:

      • Target availability zone for your hosts.
      • New subnet.
      • Select Public access to make the host accessible from outside Yandex Cloud, if required.

    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.

    Run this command:

    yc managed-postgresql host add \
   --cluster-name <cluster_name> \
   --host zone-id=<availability_zone>,`
         `subnet-id=<new_subnet_ID>,`
         `assign-public-ip=<allow_public_access_to_host>

    You can get the cluster name with the list of clusters in the folder. In the zone-id parameter, specify the target availability zone for your hosts.

    1. Add a host resource to the Terraform configuration file describing your infrastructure:

      resource "yandex_mdb_postgresql_cluster" "<cluster_name>" {
  ...
  host {
    zone             = "<availability_zone>"
    subnet_id        = "<new_subnet_ID>"
    assign_public_ip = <allow_public_access_to_host>
  }
}

      In the zone parameter, specify the target availability zone for your hosts.

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

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

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

      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>
             }
          ]
       }' \
   mdb.api.cloud.yandex.net:443 \
   yandex.cloud.mdb.postgresql.v1.ClusterService.AddHosts

      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.

  3. To connect to the database after migration, specify your new host's FQDN in your backend or client, e.g., in your application code or a GUI IDE. Delete the original host’s FQDN in your source availability zone.

    To get the FQDN, request the list of hosts in the cluster:

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

    You will see your host’s FQDN in the command output under NAME. Alternatively, you can connect using a special FQDN.

  4. Delete the hosts in the source availability zone:

    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.

    Run the following command for each host:

    yc managed-postgresql host delete <host_FQDN> --cluster-name <cluster_name>

    1. In your Terraform infrastructure configuration file, delete the host resource sections with the source availability zone from your cluster’s description.

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

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

    1. 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 the array containing the host you want to delete.

      You can provide only one host FQDN per request. If you need to delete multiple hosts, make a separate request for each of them.

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

    1. 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 the array containing the host you want to delete.

      You can only specify one host FQDN per request. If you need to delete multiple hosts, make a separate request for each of them.

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

  5. Wait for the cluster status to change to Alive. In the management console, go to Managed Service for PostgreSQL. You can see the cluster status in the Availability column.

Note

Not available for clusters with hosts residing in the ru-central1-d availability zone:

  • Intel Broadwell platform
  • Local SSD storage if using Intel Cascade Lake

Specifics of migration in Yandex Data Transfer

If your cluster is used as an endpoint when transferring data with Data Transfer, and the transfer type is Replication or Snapshot and increment, restart the transfer after migrating the cluster. This way, the transfer will get data about the cluster's new topology.

You do not need to restart Snapshot transfers, as information about the new topology is provided automatically while activating them.

To restart a transfer, choose one of the two methods:

For more information, see Migrating a Data Transfer transfer and endpoints to a different availability zone.

Note

Enable the pg_tm_aux extension for your PostgreSQL cluster. This will allow replication to continue following a replacement of the master host. In some cases, a transfer may end in an error after you replace a master in your cluster. For more information, see Troubleshooting.

Previous
Managing PostgreSQL hosts
Next
Managing replication slots