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

  • Article

APPLIES TO: Azure Database for PostgreSQL - Single Server

Important

Azure Database for PostgreSQL - Single Server is on the retirement path. We strongly recommend that you upgrade to Azure Database for PostgreSQL - Flexible Server. For more information about migrating to Azure Database for PostgreSQL - Flexible Server, see What's happening to Azure Database for PostgreSQL Single Server?.

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 replication support

Read replicas and logical decoding both depend on the Postgres write ahead log (WAL) for information. These two features need different levels of logging from Postgres. Logical decoding needs a higher level of logging than read replicas.

To configure the right level of logging, use the Azure replication support parameter. Azure replication support has three setting options:

  • Off - Puts the least information in the WAL. This setting is not available on most Azure Database for PostgreSQL servers.
  • Replica - More verbose than Off. This is the minimum level of logging needed for read replicas to work. This setting is the default on most servers.
  • Logical - More verbose than Replica. This is the minimum level of logging for logical decoding to work. Read replicas also work at this setting.

Note

When deploying read replicas for persistent heavy write-intensive primary workloads, the replication lag could continue to grow and may never be able to catch-up with the primary. This may also increase storage usage at the primary as the WAL files are not deleted until they are received at the replica.

Azure CLI

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

Prerequisites

Prepare the primary server

  1. Check the primary server's azure.replication_support value. It should be at least REPLICA for read replicas to work.

    az postgres server configuration show --resource-group myresourcegroup --server-name mydemoserver --name azure.replication_support

  2. If azure.replication_support is not at least REPLICA, set it.

    az postgres server configuration set --resource-group myresourcegroup --server-name mydemoserver --name azure.replication_support --value REPLICA

  3. 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 primary server to replicate from. Use the resource ID if you want the replica and primary's resource groups to be different.

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

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

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

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 primary server and restarted the server, you receive an error. Complete those two steps before you create a replica.

Important

Review the considerations section of the Read Replica overview.

Before a primary 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 primary.

List replicas

You can view the list of replicas of a primary 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 primary server and a read replica by using az postgres server replica stop command.

After you stop replication to a primary 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 primary or replica server

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

When you delete a primary 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 primary server

  1. Check the primary server's azure.replication_support value. It should be at least REPLICA for read replicas to work.

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

  2. If azure.replication_support is not at least REPLICA, set it.

    PUT https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/servers/{masterServerName}/configurations/azure.replication_support?api-version=2017-12-01

    {
 "properties": {
 "value": "replica"
 }
}

  3. Restart the server to apply the change.

    POST https://management.chinacloudapi.cn/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.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/servers/{replicaName}?api-version=2017-12-01

{
  "location": "chinaeast",
  "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 primary 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 primary. After a replica is created, several settings can be changed independently from the primary 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 primary 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 primary.

List replicas

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

GET https://management.chinacloudapi.cn/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 primary server and a read replica by using the update API.

After you stop replication to a primary 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.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DBforPostgreSQL/servers/{replicaServerName}?api-version=2017-12-01

{
  "properties": {
    "replicationRole":"None"  
   }
}

Delete a primary or replica server

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

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

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

Next steps