Skip to content

CONCEPT Cited by 1 source

Reserved connection

Definition

A reserved connection is a database connection that has been taken out of a shared connection pool and dedicated to a single caller's session for the session's lifetime. It bypasses the pool — no other caller can borrow it — and it counts against the backing database's fixed connection budget (MySQL's max_connections) until the session ends.

In Vitess's vttablet, reserved connections are the mechanism that Vitess introduced in v7.0 to honour client SET statements without violating the pool's fungibility invariant (Source: sources/2026-04-21-planetscale-connection-pooling-in-vitess).

Why it exists

A connection pool's correctness depends on connections being fungible. If a caller modifies per-session state (by issuing SET @@session.unique_checks = 0 or opening a transaction), the connection becomes a tainted connection — returning it to the pool would leak state to unrelated subsequent callers. The pool has three options: restore the setting, close the connection, or reserve it.

Reservation is the option that:

  • Preserves the caller's expected semantics (the setting persists for the whole session, matching what the caller asked for).
  • Avoids per-query overhead (no restore, no re-handshake, no rewrite).
  • Trades against the global connection budget: every reserved connection subtracts from the backing database's total available connections.

Why it's a scaling problem

"As these kinds of reserved connections are no longer part of the connection pool, they can grow without any upper limit on their numbers, eventually leading to MySQL running out of connections and making the database unavailable for application use." — Harshit Gangal, sources/2026-04-21-planetscale-connection-pooling-in-vitess

The failure mode is:

  1. An application opens a session and issues a SET that taints the connection.
  2. Vitess reserves the connection, taking it out of the pool for the session's duration.
  3. The session is long-lived (web server worker, ORM session pinned to a request thread, etc.).
  4. Many concurrent sessions do this in parallel. Each occupies one MySQL connection permanently.
  5. Vitess's shared pool shrinks as reservations accumulate; aggregate MySQL connection count approaches RDS's 16,000-connection ceiling (or whatever max_connections is).
  6. MySQL refuses new connections. Database is unavailable even though most reserved connections may be idle most of the time.

This is exactly the class of connection-pool-exhaustion failure that a centralised pool is supposed to prevent — reservation reintroduces it through a pool-bypass side channel. The scaling ceiling is no longer "pool size" but "pool size minus reservations," and under ORM-heavy workloads reservations can dominate.

Mitigations before the structural fix

Before the v15 settings pool (patterns/settings-aware-connection-pool), Vitess shipped two complementary mitigations documented in sources/2026-04-21-planetscale-connection-pooling-in-vitess:

  • No-op elision: when an application issues SET unique_checks = 0, Vitess first runs select 0 from dual where @@unique_checks != 0. If the variable is already at the requested value, the SET is a no-op, and the connection doesn't need to be reserved. This catches the common case where an ORM sets a variable to its MySQL default (no-op in practice).
  • SET_VAR hint rewriting: for MySQL 8.0 and SET_VAR-eligible variables, Vitess rewrites every subsequent query in the session to carry the variable as a query-scoped optimizer hint — insert /*+ SET_VAR(unique_checks=0) */ into user (id, name) values (1, 'foo'). The variable applies per query, the connection is not tainted, no reservation is needed.

Both mitigations reduce the number of reservations but don't eliminate them — many session variables are not SET_VAR-eligible, and some settings genuinely change behaviour such that the no-op elision doesn't fire.

The structural fix: settings pool (v15)

Vitess v15.0 introduced a settings pool — connections are still pooled, but the pool is indexed by settings profile and the matching logic selects (or mutates) a connection to satisfy the caller's current settings. Reservation is replaced with on-demand settings-application inside the pool. See patterns/settings-aware-connection-pool for the pattern shape. Feature is behind the queryserver-enable-settings-pool vttablet flag.

PlanetScale's reported production outcome: "we have started to roll out this feature and are already seeing improvements in query latency and load on Vttablet for customers who previously relied on reserved connections due to their application ORMs."

Seen in

  • sources/2026-04-21-planetscale-connection-pooling-in-vitess — canonical first wiki definition. Harshit Gangal walks through the Vitess v7.0 introduction of reserved connections as the answer to ORM-driven SET statements, the unbounded-growth scaling problem they create, the two pre-v15 mitigations (no-op elision + SET_VAR rewrite), and the v15 settings pool as the structural fix.
Last updated · 347 distilled / 1,201 read