Skip to content

SYSTEM Cited by 1 source

Vitess transaction throttler

What it is

The Vitess transaction throttler is Vitess's enforcement-mode throttler: a query-path barrier that actively delays database query execution when system performance degrades, rather than asking clients to respect an advisory check.

It is the canonical wiki instance of the patterns/enforcement-throttler-proxy pattern.

"The Vitess transaction throttler … can actively delay database query execution when system performance degrades. Clients cannot bypass the throttler, and may not even be aware of its existence."

— Shlomi Noach, Anatomy of a Throttler, part 3

Location in the Vitess stack

Embedded in the VTTablet query-execution path — the last in-Vitess hop before MySQL. Clients (application code going through VTGate, replication streams, admin tools) reach MySQL only via VTTablet, and VTTablet's transaction throttler gates that hop.

application ─▶ vtgate ─▶ vttablet ─▶ mysql
                         │
                         └─ transaction throttler
                            (delays queries under overload)

Role vs. the cooperative tablet throttler

Two distinct Vitess-throttler systems with complementary roles:

System Substrate Shape Target workload
Tablet throttler (parts 1-2) — systems/vitess-throttler Out-of-band /throttler/check API Cooperative (patterns/collaborative-throttler-check-api) Internal batch subsystems (VReplication, VDiff, online DDL, bulk ops)
Transaction throttler (this page, part 3) In-path VTTablet query interceptor Enforcement / barrier (patterns/enforcement-throttler-proxy) OLTP application traffic (unmodified application code)

The two coexist in production. Both consult system-health metrics (replication lag, load average, custom probes). The difference is client participation: cooperative clients opt in via the check API; OLTP traffic is subject to the transaction throttler whether or not the application understands there's a throttler at all.

Why enforcement is needed separately

The cooperative model has a structural hole: a rogue or malfunctioning client can simply skip the check. For internal tooling (VReplication, online DDL) PlanetScale / Vitess can audit client behaviour — if VReplication doesn't honour the throttler, that's a bug.

For OLTP application traffic there is no such audit lever. An application that queries too aggressively during overload cannot be asked to back off via an API it doesn't call. The transaction throttler is the answer: make the backpressure invisible to the client, delivered as latency.

"An alternative throttling enforcement design puts the throttler between the client and the system."

Enforcement mechanism

The post describes the shape without revealing internals:

  • Sits in the query path — every VTTablet-executed query is subject to it.
  • Reads system metrics — same metric substrate as the cooperative throttler (replication lag, load average, plus configurable probes).
  • Acts as active delay — queries are held until metrics recover, not rejected outright. Callers see latency, not errors.

Client-identification cost

The wiki's canonical example of the enforcement-mode identity-inference cost:

"It's more complicated to identify the clients, and the throttler must rely on domain-specific attributes made available by the client/connection/query to be able to distinguish between clients and implement any needed prioritization."

The cooperative tablet throttler gets its 4-level <uuid>:vcopier:vreplication:online-ddl identity for free from the client. The transaction throttler has to reconstruct whatever identity it can from SQL comments, connection attributes, auth scope, or query shape — with no guarantee the application provides useful signals.

Relationship to PlanetScale

PlanetScale inherits the transaction throttler via its Vitess substrate. For managed MySQL clusters, the transaction throttler is the backstop for application traffic that the customer's code doesn't cooperate with explicitly.

Seen in

  • sources/2026-04-21-planetscale-anatomy-of-a-throttler-part-3 — canonical wiki introduction. Shlomi Noach introduces the transaction throttler specifically as the answer to the cooperative-model rogue-client structural hole, and calls out the client-identification inference cost compared to the cooperative tablet throttler.

Caveats

  • No internals in the post. Control loop, threshold logic, queue management, and integration details with VTTablet's connection pool are named but not walked. Future-ingest surface from Vitess docs / source.
  • Specific metrics consulted not disclosed. The post refers to "system performance" in general terms.
  • No production-tuning numbers. No typical delay distributions, no queue-depth policies, no customer- visible latency SLO framing.
  • Client-identification mechanisms not enumerated. SQLCommenter, connection attributes, session variables are all plausible but unspecified.
  • Interaction with VTGate query buffering undocumented in this post. The 2026-02-16 migrations post canonicalised VTGate query buffering for cutover; how that composes with transaction throttling under non-migration overload is not covered.
Last updated · 319 distilled / 1,201 read