Connection pooling_

PostgreSQL creates one backend process per connection, which makes each connection relatively expensive. Serverless functions, edge runtimes, and horizontally scaled application servers can easily exhaust the connection limit of your specification. The connection pooler sits in front of your database and multiplexes many client connections onto a small pool of server connections.

The pooler runs next to your database and is reachable on port 6432 on the same hostname. Your application connects to the pooler exactly like it would connect to PostgreSQL directly, same credentials, same TLS. The pooler is available on specifications that run on dedicated compute; the smallest specifications run on shared capacity and do not include it.

Pool modes

Transaction mode gives the highest connection multiplexing but does not support session-level state. If your framework prepares statements at the session level, either switch the driver to unnamed prepared statements or use session mode.

Configure the pooler

Read the current pooler configuration with getPooler, and tune the pool mode and sizes with updatePooler. All parameters are optional; omitted values keep their current setting.

The same settings are available in the Console under Settings > Connection pooler.

Connect through the pooler

Take your normal connection string and change the port to 6432:

postgresql://admin:<password>@db-<hash>.<region>.appwrite.center:6432/<database>

Point your application's runtime traffic at the pooler port. Keep migrations and long-lived administrative sessions on the direct port 5432, schema changes and tools like pg_dump expect session semantics and can misbehave in transaction mode.

Read/write splitting

When high availability is enabled, the pooler can route read-only statements to replicas and everything else to the primary. SELECT ... FOR UPDATE and statements inside explicit transactions go to the primary. Replicas replicate asynchronously by default, so a read that immediately follows a write can be stale; use sync or quorum replication mode if you need read-your-writes consistency through the pooler.

Sizing guidance

A useful starting point for defaultPoolSize is 4 x CPU cores of your specification, and it rarely helps to go above your specification's connection cap divided by the number of databases sharing the workload. Watch the connection metrics in the Monitor tab and increase the pool only when clients queue for a connection.

When not to use the pooler

The pooler adds a network hop, and transaction mode trades session-level features for connection multiplexing. Connect to the direct port 5432 instead when any of the following applies:

• A small, fixed fleet. A few long-lived application servers that each maintain a driver-level pool, with a combined connection count that fits in your specification's limit, gain nothing from an extra hop.
• Session state. Workloads that rely on advisory locks, LISTEN/NOTIFY, session-level prepared statements, or temporary tables break in transaction mode. Use session mode or the direct port.
• Migrations and administration. Schema changes and tools like pg_dump expect one session for the whole run. Always run them against the direct port.
• Single latency-sensitive queries. A workload of few, fast queries on an idle database pays the extra hop on every round trip without ever hitting the connection limit the pooler protects against.