What is a connection pooler?

What it is

PostgreSQL handles each connection with its own server process, which costs memory and setup time, and the max_connections setting caps how many can exist at once. Applications that open a connection per request, especially serverless functions that scale to hundreds of copies, can hit that cap quickly. A connection pooler accepts client connections cheaply and maps them onto a limited pool of real database connections. PgBouncer is the long standing open source pooler; managed platforms often run their own, such as Supabase's Supavisor.

How it works

The client connects to the pooler as if it were the database, with the same protocol. In session mode the client keeps one server connection until it disconnects, which preserves everything a session can do but saves little. In transaction mode the client borrows a server connection only for each transaction and returns it immediately after, so hundreds of mostly idle clients can share a few dozen connections. Supabase's documentation, for example, offers a transaction pooler on port 6543 for serverless and edge functions and a session pooler as an IPv4 alternative to a direct connection on port 5432.

When it matters

A pooler matters when many short lived clients talk to one database: serverless API routes, background jobs scaling up, or a platform hosting many small sites against one database cluster. It matters less for a single long running server that keeps a small fixed pool of its own. Many website owners never touch it directly, because their framework or database provider uses one behind the scenes, but connection limit errors under load are usually the sign that one is needed or misconfigured.

Common mistakes

Pointing serverless functions at the direct database address instead of the pooler, then hitting too many connections errors during a traffic spike. Using transaction mode with code that relies on session features, such as prepared statements without support for them, temporary tables or session level settings. Setting the pool size larger than the database's own connection limit. Running migrations through a transaction pooler when the migration tool needs session mode. And forgetting that a pooler adds a network hop, so placing it far from the database adds latency.

Where it shows up in OneCraft

A OneCraft site that needs data gets a schema of its own in OneCraft's pool project, with a login role that can reach no other site, or a project on the owner's own Supabase account. Visitors reach the data through Supabase's APIs with row level security on every table, so site owners do not manage database connections or pool sizes themselves. Hosted schemas are available on every plan, or owners can connect their own Supabase account.

Questions people ask