PostgreSQL flexible server operations — read replicas and virtual endpoints, in-place major version upgrades, elastic clusters

Running PostgreSQL flexible server beyond one server — read replicas (five per primary, cascading to 30, cross-region, no Burstable, no HA or backups on replicas), virtual endpoints and promotion, in-place major version upgrades with pg_upgrade (precheck, extensions that block it, replicas to delete first, no rollback except point-in-time restore), and elastic clusters (Citus on flexible server), which replace Azure Cosmos DB for PostgreSQL.

markdownreferencev1ZCB1-GMFRstage: operatetrust: officialservice: postgresqlinterface: cliPostgreSQL flexible server read replicafive read replicascascading read replicas 30cross-region read replicavirtual endpointspromote to primary serverpromote to independent serverreplication lagBurstable no read replicasaz postgres flexible-server replica createin-place major version upgradepg_upgradeupgrade precheckupgrade blocked extensions session_variable anon agepg_repack hypopg pg_partman drop before upgradeSCRAM before upgrading from 11upgrade no rollback point-in-time restore10-20% free storage upgradeaz postgres flexible-server upgradeelastic clustersCitusAzure Cosmos DB for PostgreSQL retirement pathmigrate Cosmos DB for PostgreSQL to elastic cluster

Created 21 Oct 2026 · Modified 23 Oct 2026 · 1 version

PostgreSQL flexible server operations

Read replicas

  • Up to five replicas per primary; cascading (each replica with up to five of its own) reaches 30. Same region or other regions.
  • General Purpose and Memory Optimized only (not Burstable). Replicas have no high availability and no backups.
  • Lag is usually seconds to minutes, and can reach hours under heavy load or across regions: don't read your own writes from a replica.
  • Virtual endpoints give a stable read-write name and a read-only name that keep pointing at the right servers after promotion (not available for cascading replicas).
  • Promote either to primary server (roles swap, the old primary becomes a replica) or to independent server (it leaves replication). Promotion syncs planned (waits for the replica to catch up) or forced (immediate, may lose data).
  • az postgres flexible-server replica create -g <rg> --source-server <primary> --name <replica>.

In-place major version upgrades

  • The service runs a precheck; if it passes, it stops the server, takes an implicit backup, and runs pg_upgrade. Versions can be skipped (for example 13 → 16) as long as the target is supported. HA servers lose HA during the upgrade and need capacity to re-create the standby.
  • Before you start: delete read replicas (all of them, cascading too) and re-create them afterwards; keep 10–20% storage free; from 11, switch to SCRAM authentication first; avoid long-running transactions.
  • Extensions: drop session_variable, anon and age (they block every upgrade path) and the utility extensions pg_repack, hypopg and pg_partman (drop and re-create); some block only certain targets (azure_ai, azure_storage and pg_diskann for 18, semver for 16 and 17, pg_hint_plan for 14). Views that depend on pg_stat_activity block it too.
  • Other checks look for logical replication slots, prepared transactions, event triggers and pending restart-required parameters: run the validation before the maintenance window.
  • There's no undo: to go back, restore a point in time before the upgrade onto a new server.
  • az postgres flexible-server upgrade -g <rg> -n <server> --version 17 --validate-only runs the checks without upgrading (CLI 2.91 help); drop --validate-only to upgrade.

Elastic clusters (distributed PostgreSQL)

Azure Cosmos DB for PostgreSQL is on a retirement path: new deployments are blocked; existing clusters stay supported. Its replacement is elastic clusters of Azure Database for PostgreSQL flexible server: several flexible-server nodes running Citus, queryable from any node, with managed identity, PgBouncer, up to 3,000 connections per node and the normal compute tiers. Not (yet) available there: VNet integration, TimescaleDB in cluster mode, storage autogrow, long-term retention. Microsoft's snapshot-based migration from Cosmos DB for PostgreSQL usually completes in under 10 minutes with a 5–8 minute read-only window, then you switch connection strings.

Versions, extended support and Entra sign-in: reference/postgresql/flexible-server.md.

Read this document as markdown — the same bytes an agent receives.