Skip to content

SYSTEM Cited by 4 sources

Vitess throttler

What it is

The Vitess throttler is the in-tree implementation of a database throttler used by Vitess and by PlanetScale MySQL clusters to push back on asynchronous / batch / massive operations when a MySQL cluster is unhealthy. Authored and maintained by Shlomi Noach — who also authored gh-ost and pt-online-schema-change-style tooling at GitHub — the Vitess throttler is the canonical instance of the collaborative multi-metric shape described in Noach's throttler-design series.

Shape

Consumers

Tools that integrate with the Vitess throttler include:

  • VReplication / VDiff / MoveTables — the Vitess data-motion subsystem (see sources/2026-02-16-planetscale-zero-downtime-migrations-at-petabyte-scale). Long-running copy + catch-up workflows must throttle per subtask so that the migration traffic never takes down production.
  • Online DDL — Vitess's managed schema-change executor.
  • Bulk operations — customer-scheduled mass updates / purges.

Why Noach wrote the throttler-design series here

PlanetScale and Vitess both expose this throttler to customers directly. Shlomi Noach's Anatomy of a Throttler series on the PlanetScale blog is the first canonical wiki-referenced articulation of the design thinking behind it. Part 1 frames the language (what a throttler is, why replication lag, why combinations of metrics), establishing shared vocabulary for later posts in the series (singular vs distributed throttler, throttler impact on the environment).

Relationship to PlanetScale Traffic Control

Two distinct throttler-shaped systems live under the PlanetScale umbrella:

System Substrate Metric shape Granularity
Vitess throttler MySQL via Vitess Replication lag + multi-metric Per-tablet, per-subtask check
systems/planetscale-traffic-control Postgres (via PlanetScale Insights) Per-workload-class resource budgets SQLCommenter-tagged query class

The two serve different workload scopes: Vitess throttler operates on massive long-running ops pushing against cluster health; Traffic Control operates on arbitrary mixed OLTP + analytics workloads pushing against per-class resource budgets. Both are instances of the more general patterns/workload-class-resource-budget pattern, at different engine tiers.

Client identity scheme (part 3)

Part 3 of the series discloses the Vitess tablet throttler's hierarchical client identity format. Each client presents a 4-level identifier on every check:

<uuid>:<flow>:<subsystem>:<job-category>

Canonical example:

d666bbfc_169e_11ef_b0b3_0a43f95f28a3:vcopier:vreplication:online-ddl

The scheme lets operators write rules at any level — exempt all vcopier flows, de-prioritise all online-ddl, pause one specific UUID — and makes per-identity rejection-rate analysis (patterns/probabilistic-rejection-prioritization) practical.

Prioritisation levers (part 3)

The cooperative Vitess tablet throttler supports the full part-3 prioritisation toolkit on top of its base patterns/multi-metric-throttling shape:

These compose with the earlier parts' content: identity is the key on which prioritisation, exemption, and time bounds all key; metric-scope (concepts/throttler-metric-scope) still applies inside the metric-gate that every non- dice-rolled check still consults.

Relationship to the Vitess transaction throttler

The Vitess cooperative tablet throttler and the Vitess transaction throttler are the canonical wiki instance of cooperative + enforcement coexistence on the same substrate. The cooperative throttler covers internal batch subsystems (VReplication, VDiff, online DDL, bulk ops); the transaction throttler covers OLTP application traffic that won't cooperate. Both consult the same metric substrate (replication lag, load average, configurable probes); they differ only in client participation — cooperative is opt-in, enforcement is unavoidable.

Seen in

  • sources/2026-04-21-planetscale-anatomy-of-a-throttler-part-1 — Noach's Part 1 establishes the design language (target workload shape, collaborative-vs-barrier, multi-metric, symptom-vs-cause, sampling math, threshold-becomes-standard, observability shift). Part 1 does not walk Vitess implementation internals — that is deferred to later posts in the series.
  • sources/2026-04-21-planetscale-anatomy-of-a-throttler-part-2 — Part 2 opens the deployment-topology design space and names the Vitess tablet-throttler-plus-shard-primary aggregator as the canonical per-host-plus-shard-roll-up instance (patterns/throttler-per-shard-hierarchy); covers fail-open/closed, hibernation, replication heartbeats, and layered polling staleness.
  • sources/2026-04-21-planetscale-anatomy-of-a-throttler-part-3 — Part 3 discloses the tablet throttler's hierarchical client-identity scheme (<uuid>:vcopier:vreplication:online-ddl) and names the full prioritisation toolkit the throttler supports: probabilistic rejection, global-default + favoured override, time-bounded rules, and the three justified exemption cases. Also introduces the transaction throttler as the enforcement-mode sibling system.

  • sources/2026-02-16-planetscale-zero-downtime-migrations-at-petabyte-scale — Matt Lord mentions the Vitess throttler as the gate controlling copy-phase and catch-up-phase traffic rate during VReplication workflows; the petabyte-scale migration feature depends on it.

  • sources/2026-04-21-planetscale-announcing-vitess-21 — Vitess 21 ships multi-metric throttler support as the production primitive: "the throttler now handles more than just replication lag or custom queries, but instead can work with multiple metrics at the same time, and check for different metrics for different clients or for different workflows." Canonical shipping-primitive datum paired with the design-space exposition in the three-part Anatomy of a Throttler series (same publication day). v20 wire-format backward compatibility preserved (v20 primary ↔ v21 replica interop), slated for removal in v22 — canonical wiki datum on a major-version-gap backward-compat window for a throttler protocol evolution. Deprecations in v21: --check-as-check-self / --check-as-check-shard sub-flags, SHOW VITESS_THROTTLER STATUS, SHOW VITESS_THROTTLED_APPS, and all /throttler/ API access points except /throttler/check. Throttler check response now includes a human-readable rejection summary — self- describing rejection UX. "When enabled, the throttler ensures it leases heartbeat updates, even if heartbeat configuration is otherwise unset. In other words, the throttler overrides the configuration when it requires heartbeat information." First canonical wiki datum on the throttler forcing heartbeat injection when its own correctness requires it, independent of operator-specified heartbeat config — design rule: subsystems with correctness-critical dependencies on observability primitives should override operator configuration when their own guarantees require it.

Caveats

  • Series is language-establishing; implementation details (control-plane topology, storage of per-metric thresholds, dice-roll RNG seeding, rule-TTL persistence, distributed- coordination mechanism across shards, the transaction throttler's internals) are partially covered across parts 1-3 but none walked at code granularity.
  • Code reference: the Vitess throttler lives in the vt/throttle tree of the vitessio/vitess repository.
  • Client-identification inference in the cooperative model is free (client self-reports); in the transaction throttler it is an inference problem on connection/query attributes — part 3 calls out the cost but doesn't enumerate the mechanisms.
Last updated · 319 distilled / 1,201 read