To swap the replica and primary server in Azure Database for PostgreSQL Flexible Server with zero application downtime, the best practice is to use planned failover with a private DNS alias. This allows your application to seamlessly switch to the new primary without needing code or configuration changes.
Table of Contents
Use DNS Alias
Ensure your Flexible Server is using VNet integration with private access (not public endpoint).
privatelink.postgres.database.azure.com
Create a DNS alias pointing to your current primary server.
az postgres flexible-server dns-alias create \
--name my-alias \
--server-name current-primary \
--resource-group my-rg
In your application, connect to my-alias.postgres.database.azure.com, not the real server name.
Do a Planned Failover. This swaps roles between primary and replica without data loss:
az postgres flexible-server replica promote \
--name replica-server \
--resource-group my-rg
This makes the replica a new standalone primary. (Old primary becomes stale unless reconfigured.)
Re-point DNS Alias to New Primary. Update the DNS alias to now point to the promoted replica:
az postgres flexible-server dns-alias set \
--name my-alias \
--server-name replica-server \
--resource-group my-rg
DNS alias now points to the new primary. The app continues using my-alias... and sees no change or downtime.
Swapping Roles Explanation
What happens during replica promotion
When you promote a replica to primary in Azure PostgreSQL Flexible Server, role swapping is not automatic or seamless for the application unless you've prepared properly.
az postgres flexible-server replica promote --name my-replica
This command stops replication between primary and replica. Promotes the replica to a standalone read-write server. Does not automatically demote or shut down the original primary. DNS entries remain unchanged (unless you manage them)
Application impact without DNS alias
If your application connects to:
current-primary.postgres.database.azure.com
It will still try to connect to the old primary. That server is still running but not replicating anymore (data becomes stale). The promoted replica gets no traffic until you reconfigure the app or DNS.
So promoting the replica alone will not notify the application — you'll need to explicitly redirect traffic.
When you promote the replica, use az postgres flexible-server dns-alias set to point the alias to the new primary. Azure DNS changes are nearly instant (within seconds inside Azure VNet). Application keeps using the same host → no disconnect needed, unless: a transaction is mid-flight or the client has pinned old TCP connection (some retry may occur).
Does the app get disconnected? Yes, briefly — during promotion or alias switch, active TCP connections may break. But with proper retry logic (typical in most DB clients), reconnection is automatic. Duration: ~1–5 seconds if you're using Azure VNet and alias properly.
Automation
#!/bin/bash
set -euo pipefail
# Required parameters
RESOURCE_GROUP="my-rg"
ALIAS_NAME="app-db-alias" # DNS alias without domain
ALIAS_FQDN="${ALIAS_NAME}.postgres.database.azure.com"
CURRENT_PRIMARY="product-primary"
REPLICA="product-replica"
# Step 1: Create alias on current primary (safe to re-run)
echo "Creating DNS alias '${ALIAS_NAME}' for primary server '${CURRENT_PRIMARY}'..."
az postgres flexible-server dns-alias create \
--name "$ALIAS_NAME" \
--server-name "$CURRENT_PRIMARY" \
--resource-group "$RESOURCE_GROUP" \
--only-show-errors
echo "Alias '${ALIAS_FQDN}' now points to current primary."
# Step 2: Promote the replica to new primary
echo "Promoting replica '${REPLICA}' to primary..."
az postgres flexible-server replica promote \
--name "$REPLICA" \
--resource-group "$RESOURCE_GROUP" \
--only-show-errors
echo "Replica '${REPLICA}' promoted successfully."
# Step 3: Move alias to the new primary
echo "Re-pointing alias '${ALIAS_NAME}' to new primary '${REPLICA}'..."
az postgres flexible-server dns-alias set \
--name "$ALIAS_NAME" \
--server-name "$REPLICA" \
--resource-group "$RESOURCE_GROUP" \
--only-show-errors
echo "Alias now points to new primary '${REPLICA}'."
echo "Your application will automatically follow the alias '${ALIAS_FQDN}' with minimal downtime."