Skip to content

PATTERN Cited by 1 source

Settings-aware connection pool

What it is

A settings-aware connection pool is a connection pool whose entries are indexed by the session-settings profile they carry, rather than treated as fungible. On borrow, the pool matches the caller's session-settings profile against an existing connection (fast path) or applies the settings on demand (slow path, one-time per unique profile). The connection returns to the pool afterwards — still carrying its settings — so the pool keeps rotating connections across callers without leaking state.

Canonical instance: the Vitess v15 settings pool in VTTablet, behind the queryserver-enable-settings-pool flag (Source: sources/2026-04-21-planetscale-connection-pooling-in-vitess).

Problem

A connection-multiplexing proxy pools upstream database connections across many client callers. Most of the time, pool fungibility holds: any connection can serve any caller. But when a caller issues a session-level SET statement (SET unique_checks = 0, SET time_zone = '+00:00', SET sql_mode = '...'), the connection becomes tainted. Returning it to the pool would leak that setting to unrelated subsequent callers.

The classical answers — Vitess used all three in different eras — have real failure modes:

Answer Failure mode
Drop SET statements (Vitess pre-v7) ORM-incompatible. Rails, Hibernate, Django all send SET on connection open.
Close on taint Every taint costs a fresh ~50 ms MySQL SSL handshake.
Restore on return Not all settings have clean resets. Error-prone at scale.
Reserve the connection (Vitess v7–v14) Unbounded growth. Reserved connections bypass the pool and subtract from the fixed max_connections budget until the session ends. Multi-ORM workloads rapidly exhaust MySQL.
SET_VAR hint rewriting Only covers SET_VAR-eligible variables. Partial mitigation, not complete.

What's needed: a way to keep pool rotation through setting mutations, not around them.

Solution shape

Instead of treating connections as fungible, make the pool settings-aware:

  1. Track per-connection settings profile — each pooled connection carries metadata describing what SETs have been applied to it.
  2. On caller query, consult the caller's session-settings state (which the proxy tracks from the client's SET history).
  3. Match in pool — pick a pooled connection whose settings profile equals the caller's.
  4. Fast path: exact match. Use it directly.
  5. Slow path: no match. Take any available connection, apply the missing SETs (or RESETs), update its profile metadata, use it.
  6. Return to pool — connection goes back with its updated profile. Next caller with the same profile gets a fast-path hit.

From the caller's perspective this is transparent: queries run as if the connection were dedicated. From the pool's perspective, no connection is ever taken out — the pool population stays bounded at the configured size.

"Vitess now tracks and manages connections in which system settings have been modified. This process is transparent to the application but provides all the advantages of connection pooling while still allowing per-connection settings. When an application submits a query to Vitess for execution, Vitess can retrieve the correct connection from the connection pool, with or without settings applied, based on the settings specified by that application on that session, and then execute the query." — Harshit Gangal, sources/2026-04-21-planetscale-connection-pooling-in-vitess

Why it works

The insight is that settings profiles have low cardinality in practice. A given application (and its ORM) typically uses a handful of distinct profiles. A PlanetScale cluster hosting a Rails app + a Django app + a Hibernate app might have three dominant profiles plus a few variants — not thousands.

This means:

  • The fast path fires nearly every time after a brief warm-up.
  • Slow-path applications (applying missing SETs) are one-time costs per new profile; the connection then serves every subsequent caller with the same profile at fast-path speed.
  • No connection is reserved — the pool stays rotating, the max_connections ceiling stays stable.

Contrast with reservation: reservation has one reserved connection per active session (cardinality O(sessions)). Settings-aware pooling has one connection per unique profile currently in use (cardinality O(distinct profiles)). For ORM-heavy workloads this is a reduction of multiple orders of magnitude.

Consequences

Positive:

  • Keeps pool benefits under session-setting mutations. No pool-bypass, no uncontrolled growth, stable max_connections ceiling regardless of client SET volume.
  • ORM-compatible. Rails, Django, Hibernate, Sequelize all work without customisation — their startup SETs just become cheap profile lookups.
  • Production outcome (PlanetScale 2023): "improvements in query latency and load on Vttablet for customers who previously relied on reserved connections due to their application ORMs." (Source: sources/2026-04-21-planetscale-connection-pooling-in-vitess.)

Negative:

  • Per-connection metadata — each connection now carries a settings-profile tag + applied-state. Memory cost is small but non-zero.
  • Lookup/match algorithm — the pool's borrow operation is no longer "any connection" — it's "match profile, else mutate". Slightly more CPU per borrow.
  • Profile-explosion risk — if an application genuinely uses thousands of distinct settings profiles, the settings pool degenerates toward one-connection-per-profile, approaching reservation semantics. PlanetScale hasn't reported this in practice, but it is a theoretical failure mode for pathological workloads.
  • Cold-start penalty persists for new profiles — first query with a never-seen profile takes the slow path.
  • Feature-gated rollout — Vitess ships the feature behind queryserver-enable-settings-pool; not default-on as of 2023-03-27.

Relationship to other mitigations

The settings pool composes with SET_VAR-hint rewriting, not replaces it. Vitess still uses SET_VAR where the variable is SET_VAR-eligible (cheaper — no pool bookkeeping at all) and falls back to the settings pool for ineligible variables. The three mechanisms form a ladder:

Mechanism Pool bookkeeping Scope of setting
SET_VAR hint rewrite None Single query
Settings-aware pool Per-connection metadata + match/mutate Whole session
Reserved connection (fallback) None (bypasses pool) Whole session

Vitess picks the cheapest applicable option per variable.

Is this unique to Vitess?

At publication time (2023-03-27) it is the specific Vitess v15 shape. PgBouncer addresses the same problem differently: by exposing three discrete pooling modes (session / transaction / statement) that make the taint-tolerance trade-off explicit per-deployment. RDS Proxy uses "pinning", which is effectively reservation (a detected session-state mutation "pins" the client to its connection for the rest of the session).

The wiki canonicalises settings-aware pooling as the Vitess design point specifically: keep pool rotation through setting mutations, not around them via pinning / reservation or behind them via discrete pooling modes.

Seen in

  • sources/2026-04-21-planetscale-connection-pooling-in-vitess — canonical wiki first citation. Harshit Gangal (Vitess core maintainer, PlanetScale, 2023-03-27) canonicalises the v15 settings pool as the structural fix for the reserved-connection problem that v7.0 introduced to support ORM SET statements. The post's key framing: "Vitess now tracks and manages connections in which system settings have been modified. This process is transparent to the application but provides all the advantages of connection pooling while still allowing per-connection settings." Production outcome: query-latency + Vttablet-load drops for customers previously on the reserved-connection path, attached as two graphs in the post without numerical annotations. Feature gate: queryserver-enable-settings-pool Vttablet flag. Completes Vitess's three-era connection-pooling-design narrative (Era 1 drop-SETs / Era 2 reserved-connections / Era 3 settings pool).
Last updated · 517 distilled / 1,221 read