Create and manage read replicas from the Azure CLI, REST API

In this article, you learn how to create and manage read replicas in Azure Database for PostgreSQL by using the Azure CLI and REST API. To learn more about read replicas, see the overview.

Azure CLI

You can create and manage read replicas using the Azure CLI.

Prerequisites

Prepare the master server

These steps must be used to prepare a master server in the General Purpose or Memory Optimized tiers.

The azure.replication_support parameter must be set to REPLICA on the master server. When this static parameter is changed, a server restart is required for the change to take effect.

  1. Set azure.replication_support to REPLICA.

    az postgres server configuration set --resource-group myresourcegroup --server-name mydemoserver --name azure.replication_support --value REPLICA
    
  2. Restart the server to apply the change.

    az postgres server restart --name mydemoserver --resource-group myresourcegroup
    

Create a read replica

The az postgres server replica create command requires the following parameters:

Setting Example value Description
resource-group myresourcegroup The resource group where the replica server will be created.
name mydemoserver-replica The name of the new replica server that is created.
source-server mydemoserver The name or resource ID of the existing master server to replicate from.

In the CLI example below, the replica is created in the same region as the master.

az postgres server replica create --name mydemoserver-replica --source-server mydemoserver --resource-group myresourcegroup

To create a cross region read replica, use the --location parameter. The CLI example below creates the replica in West US.

az postgres server replica create --name mydemoserver-replica --source-server mydemoserver --resource-group myresourcegroup --location westus

Note

To learn more about which regions you can create a replica in, visit the read replica concepts article.

If you haven't set the azure.replication_support parameter to REPLICA on a General Purpose or Memory Optimized master server and restarted the server, you receive an error. Complete those two steps before you create a replica.

A replica is created by using the same compute and storage settings as the master. After a replica is created, several settings can be changed independently from the master server: compute generation, vCores, storage, and back-up retention period. The pricing tier can also be changed independently, except to or from the Basic tier.

Important

Before a master server setting is updated to a new value, update the replica setting to an equal or greater value. This action helps the replica keep up with any changes made to the master.

List replicas

You can view the list of replicas of a master server by using az postgres server replica list command.

az postgres server replica list --server-name mydemoserver --resource-group myresourcegroup 

Stop replication to a replica server

You can stop replication between a master server and a read replica by using az postgres server replica stop command.

After you stop replication to a master server and a read replica, it can't be undone. The read replica becomes a standalone server that supports both reads and writes. The standalone server can't be made into a replica again.

az postgres server replica stop --name mydemoserver-replica --resource-group myresourcegroup 

Delete a master or replica server

To delete a master or replica server, you use the az postgres server delete command.

When you delete a master server, replication to all read replicas is stopped. The read replicas become standalone servers that now support both reads and writes.

az postgres server delete --name myserver --resource-group myresourcegroup

REST API

You can create and manage read replicas using the Azure REST API.

Prepare the master server

These steps must be used to prepare a master server in the General Purpose or Memory Optimized tiers.

The azure.replication_support parameter must be set to REPLICA on the master server. When this static parameter is changed, a server restart is required for the change to take effect.

  1. Set azure.replication_support to REPLICA.

    PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/servers/{masterServerName}/configurations/azure.replication_support?api-version=2017-12-01
    
    {
     "properties": {
     "value": "replica"
     }
    }
    
  2. Restart the server to apply the change.

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/servers/{masterServerName}/restart?api-version=2017-12-01
    

Create a read replica

You can create a read replica by using the create API:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/servers/{replicaName}?api-version=2017-12-01
{
  "location": "southeastasia",
  "properties": {
    "createMode": "Replica",
    "sourceServerId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/servers/{masterServerName}"
  }
}

Note

To learn more about which regions you can create a replica in, visit the read replica concepts article.

If you haven't set the azure.replication_support parameter to REPLICA on a General Purpose or Memory Optimized master server and restarted the server, you receive an error. Complete those two steps before you create a replica.

A replica is created by using the same compute and storage settings as the master. After a replica is created, several settings can be changed independently from the master server: compute generation, vCores, storage, and back-up retention period. The pricing tier can also be changed independently, except to or from the Basic tier.

Important

Before a master server setting is updated to a new value, update the replica setting to an equal or greater value. This action helps the replica keep up with any changes made to the master.

List replicas

You can view the list of replicas of a master server using the replica list API:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/servers/{masterServerName}/Replicas?api-version=2017-12-01

Stop replication to a replica server

You can stop replication between a master server and a read replica by using the update API.

After you stop replication to a master server and a read replica, it can't be undone. The read replica becomes a standalone server that supports both reads and writes. The standalone server can't be made into a replica again.

PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/servers/{masterServerName}?api-version=2017-12-01
{
  "properties": {
    "replicationRole":"None"  
   }
}

Delete a master or replica server

To delete a master or replica server, you use the delete API:

When you delete a master server, replication to all read replicas is stopped. The read replicas become standalone servers that now support both reads and writes.

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/servers/{serverName}?api-version=2017-12-01

Next steps