Connection Manager overview v6.5.0

About Connection Manager

Connection Manager is a new background worker for EDB Postgres Distributed (PGD) 6.0 that simplifies the process of connection to PGD clusters by providing a single point of entry for client applications. It replaces the PGD 5.x proxy solution with a tightly integrated approach that exposes read-write, read-only, and HTTP status network interfaces in PGD.

Connection Manager is fully integrated into PGD and is designed to work seamlessly with the existing PGD architecture. Every PGD data node has a Connection Manager instance that listens for incoming connections and routes them to the appropriate node in the cluster, specifically the current write leader in the cluster. It also provides a read-only interface for applications that only need to read data from the cluster.

Starting in PGD 6.3.0, Connection Manager starts by default on subscriber-only nodes, ensuring that even nodes dedicated primarily to receiving replicated data have access to advanced connection pooling and session management features.

Connection Manager consolidates three capabilities that previously required separate tools. It routes writes to the current leader, distributes read traffic across nodes, and pools backend connections. Because it runs inside PGD, authentication is configured once in pg_hba.conf and applies to both the proxy layer and the database, with no separate user list to maintain.

Starting in PGD 6.5, Connection Manager runs on a multi-threaded engine instead of a single thread. Client traffic, pooling, and authentication are handled across multiple threads, so connection capacity scales with the number of CPU cores available to the node. Configuration and routing updates are processed on a separate thread, off the traffic path, so they don't add latency to client connections. The number of worker threads is controlled by bdr.conn_mgr_worker_threads, which defaults to sizing itself automatically as the number of CPU cores divided by 4, clamped between 2 and 8.

Using Connection Manager

Connection Manager follows the Postgres server's configuration by default. There are three ports, the read-write port, the read-only port, and the HTTP port. The read-write port is used for write operations, while the read-only port is used for read operations. The HTTP port is used for monitoring and management purposes.

The read-write port is, by default, set to the Postgres port + 1000 (usually 6432). The read-only port is set to the Postgres port + 1001 (usually 6433). The HTTP port is set to the Postgres port + 1002 (usually 6434).

To use Connection Manager, configure your client applications to connect to its read-write or read-only port on the data node. Connection Manager routes the connection to the appropriate node in the cluster.

Connecting to the read-only port restricts the connection to read-only operations, similar to SET TRANSACTION READ ONLY, except that it's not possible to change it to read-write. The transaction_read_only configuration parameter correctly reports on in these connections.

Understanding write leader failover

Write leader failover applies to any PGD cluster that uses Connection Manager routing, whether it runs in one location or several.

The Raft leader of each group that has enable_routing set to on selects the write leader. It keeps the current write leader as long as that node is routable and connected.

The Raft leader checks whether it has received a message from each node within the election timeout window, and treats a node it hasn't heard from in that window as failed. The window depends on which group elects the write leader. You choose that group with the enable_routing group option, which sets up either local or global routing. See Configuring routing for the settings.

A node counts as failed when it stops sending messages, whether the cause is a crashed node, a stopped Postgres instance, or a network failure.

When the write leader fails either check, PGD selects a replacement in five steps.

1. Exclude nodes that can't take writes. A node is excluded when it isn't active, is a witness node, is a subscriber-only node, has route_fence set, or has route_writes disabled.
2. Exclude nodes the Raft leader hasn't received a message from within the election timeout window.
3. Exclude nodes that exceed the route_writer_max_lag group option, if you set it.
4. Keep only the nodes with the highest route_priority. When more than one remains, choose the node that has replayed the most changes from the previous write leader. The Raft leader node is the last choice, because failing over to it after a Raft leader loss takes additional time for the election.
5. Publish the new write leader as a routing record through Raft. Connection Manager on each node then routes new connections to it.

Because the Raft leader selects the write leader, failover takes longer when the failed node held both roles. The remaining nodes must elect a new Raft leader before PGD can select a new write leader.

See Understanding failure scenarios for the behavior in other failure cases.

Authentication

Connection Manager performs TLS termination and pre-authentication using the same pg_hba.conf configuration as Postgres, with no separate user list to maintain. See Authentication for supported methods and constraints.

Connection pooling

Connection Manager includes built-in connection pooling, removing the need for a separate pooler such as pgBouncer in most deployments. Pooling reduces the number of backend Postgres connections by sharing them across many client connections, lowering memory and process overhead on the database server. See Connection pooling for reference details, Configuring connection pooling for DBA setup guidance, and Using connection pooling in your application for developer guidance.

Load balancing

Connection Manager isn't a replacement for a load balancer. Use an external load balancer to distribute client traffic across Connection Manager instances running on different nodes. See Load balancing for configuration details and HAProxy examples.

Configuration

Connection Manager is configured through PGD group options, including ports, connection limits, consensus timeouts, and pool mode. See Configuring Connection Manager for the full option reference.

Monitoring

Connection Manager exposes connection counts and pool utilization through catalog views and HTTP endpoints. See Monitoring for available metrics.