Skip to content

CONCEPT Cited by 1 source

Reserved admin connection budget

Definition

The reserved admin connection budget is the operational discipline of never letting PgBouncer consume all of Postgres's max_connections — always keeping a handful of direct-to-Postgres connection slots available for admin tasks, superuser work, and emergency scenarios.

Two mechanisms

Two distinct layers enforce the reserve:

  1. PgBouncer-side: max_connections − max_db_connections slack. Configure max_db_connections strictly less than Postgres's max_connections. The gap is the reserve.
  2. Postgres-side: superuser_reserved_connections. Postgres reserves a fixed number of slots specifically for the superuser, regardless of what PgBouncer requests. Postgres docs.

(Source: sources/2026-04-21-planetscale-scaling-postgres-connections-with-pgbouncer.)

Canonical framing

Ben Dicken, verbatim: "The total server connections must stay below this number. We should always keep a few available direct connections reserved for admin tasks and other emergency scenarios. We NEVER want PgBouncer to use all of the connections!"

Dicken's capitalised "NEVER" is load-bearing: the discipline is non-negotiable, not a best-effort margin. An operator who cannot connect directly to Postgres during a crisis has no escape hatch.

Why the reserve matters

  • Emergency connections: a failing application is often the same cause as a saturated PgBouncer pool; the operator needs to connect outside PgBouncer to diagnose.
  • Admin tasks: VACUUM, REINDEX, backup orchestration, log collection, schema migrations applied via direct connection — all benefit from bypassing the pooler.
  • Features incompatible with transaction pooling: LISTEN, session-level SET/RESET, SQL PREPARE/DEALLOCATE, advisory locks. PlanetScale's advice: "If you absolutely need features that are incompatible with transaction pooling, like LISTEN, session-level SET/RESET, or SQL PREPARE/DEALLOCATE, use a direct connection."
  • Superuser reserved: Postgres reserves slots via superuser_reserved_connections so that even if all regular connections are exhausted, the superuser can still log in.

Dicken's three scenarios as reserve examples

  • PS-80: max_connections=50, max_db_connections=40 → 10-slot reserve.
  • M-2650: max_connections=500, max_db_connections=450 → 50-slot reserve.
  • M-1280: max_connections=400, max_db_connections=2 per pool × 200 pools = 400 → zero reserve at pool cap; superuser_reserved_connections carries the reserve.

The single-tenant M-1280 scenario exposes an interesting corner: the aggregate num_pools × default_pool_size = max_connections with no slack. Only superuser_reserved_connections protects admin access. A real deployment might trade one default_pool_size=2 slot for default_pool_size=1.975 worth of reserved slots — but since per-pool is integer, the trade is to lower max_connections to num_pools × default_pool_size + slack.

Relationship to reserved_connection

The Postgres / Vitess concept of reserved connection (a connection taken out of the pool for session-state reasons) is adjacent but distinct:

  • Reserved admin connection budget: direct-to-Postgres slot reserved for admin / superuser / emergency use.
  • Reserved connection (Vitess VTTablet): a connection pinned to a caller because it carries modified session state (SET-tainted).

Both reduce pool availability, but for different reasons and with different operator intent.

Seen in

Last updated · 470 distilled / 1,213 read