Deployment patterns =================== PGD offers several deployment patterns, from a single high-availability (HA) group to globally distributed multi-region clusters. The pattern you choose determines where your data lives, which locations accept writes, and how the cluster recovers from failures. The key dimensions are the number of active write locations, the level of disaster recovery you need, and whether regulatory requirements constrain where data can be stored. Each choice carries implications for write latency, conflict handling, and operational complexity. Choosing a pattern ------------------ Most PGD deployments start from one of four goals, each mapping to one or more patterns. Maintaining continuous availability ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PGD keeps the database available through node failures, data center (DC) failures, and rolling maintenance operations including major Postgres version upgrades. Within a single location, the :ref:`Single data group, global read scaling ` pattern provides HA across two or more nodes. For datacenter-level protection without the cost of a full second active site, the :ref:`Primary active group, DR group ` pattern adds a reduced-capacity DR site that takes over if the primary DC fails. Writing across multiple regions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Applications serving users in multiple geographies benefit from placing write capacity close to those users. Both the :ref:`Two data groups, active-active ` and :ref:`Three data groups, active-active-active ` patterns run active-active: all locations accept writes and replicate to each other. The two data groups pattern suits a primary and secondary location. A witness-only third location achieves Raft majority without a full third data site, and three full data groups take Raft majority further by surviving an entire region failure without interrupting the remaining regions. Active-active replication across regions makes write conflicts possible. PGD resolves conflicts automatically using configurable conflict resolution policies, but schemas and application writes need to be designed with conflict-awareness in mind. Enforcing data locality ^^^^^^^^^^^^^^^^^^^^^^^ Regulations such as GDPR and CCPA require that personal and sensitive data stays within specific jurisdictions. The :ref:`Multiple locations, data residency ` pattern implements selective replication by data classification. Local-only data, including personally identifiable information (PII), financial records, and healthcare data, replicates only within its region. Global reference data, such as product catalogs and configuration, replicates everywhere. Each region runs independently with its own HA group. Scaling out reads ^^^^^^^^^^^^^^^^^ Read-heavy workloads can overwhelm a write cluster if not isolated. The :ref:`Single data group, global read scaling ` pattern offloads analytics, reporting, and API read traffic to subscriber-only nodes. Subscriber-only nodes receive all changes from the write group but don’t participate in writes or consensus, so adding them doesn’t affect write performance or commit scope quorum. They can be placed in additional regions to reduce read latency for local users. .. csv-table:: :header: Pattern,Locations,Active write locations,Disaster recovery :widths: 15,12,12,20 :align: left :class: longtable :ref:`Single data group, global read scaling` ,1,1,Node failure only ":ref:`Two data groups, active-active` ",2,2,DC failure ":ref:`Three data groups, active-active-active` ",3+,3+,Region failure ":ref:`Single data group, global read scaling` ",1+,1,Node failure ":ref:`Primary active group, DR group` ",2,1,DC failure (manual) ":ref:`Multiple locations, data residency` ",3+,3+,Region failure Architectural elements ---------------------- Each node in a PGD cluster is a Postgres instance running the PGD extension. Nodes are organized into groups, and each group elects a write leader to coordinate writes. Connection Manager runs on each node and routes client connections to the current write leader, enabling automatic failover without changes to the application connection string. Node types ^^^^^^^^^^ A PGD cluster uses three node types, each serving a different role: - **Data nodes:** Store and manage data, handle reads and writes, and participate in replication and consensus. - **Subscriber-only nodes:** Receive all changes from the write group but don’t accept writes or participate in consensus. They’re suited to read-heavy workloads like analytics and reporting. - **Witness nodes:** Participate in Raft consensus but don’t store user data. A witness in a third location resolves split-brain scenarios when two data locations lose contact with each other. Node roles ^^^^^^^^^^ Data nodes take on transient roles that transfer automatically between nodes as conditions change: - **Write leader:** The current target for all write operations when applications connect through Connection Manager. If the write leader fails, another node is elected in seconds. - **Raft leader:** Manages consensus decisions across the group, including write leader election and schema change coordination. Commit scopes ^^^^^^^^^^^^^ Commit scopes control the durability guarantees PGD provides for each transaction. The default is asynchronous replication with eventual consistency. Stronger options, from majority protect through Quorum Commit, add synchronous coordination at the cost of added write latency. Quorum Commit provides the strictest consistency guarantees, coordinating the commit decision across all participating nodes before any node commits locally. Each pattern page notes the commit scopes recommended for that topology. For the full reference, see :ref:`Migration to commit scopes ` . .. toctree:: :maxdepth: 3 planning--deployment-patterns--single-data-group planning--deployment-patterns--two-data-groups planning--deployment-patterns--three-data-groups planning--deployment-patterns--read-scaling planning--deployment-patterns--primary-dr planning--deployment-patterns--data-residency