Skip to content

CONCEPT Cited by 4 sources

Vitess topo-server

Definition

The topo-server (topology server) is the shared state store in a Vitess cluster. It is the coupling point between the two layers of the Vitess proxy tier:

  • VTTablet writes into the topo-server: its health status, its role (primary / replica / spare), its serving / not-serving state.
  • VTGate reads from the topo-server: which tablets exist, which are healthy, which role each one has — and uses that to route queries.

From PlanetScale's canonical description:

"VTTablet will manage connection pooling and perform health checks for MySQL instances, updating its status in a topo-server. Meanwhile, VTGate determines available tablets and their roles via the topo server and reroutes traffic as needed." (Source: sources/2026-04-21-planetscale-planetscale-vs-amazon-rds)

Why it exists

Without the topo-server, VTGate would have to either (a) directly health-check every MySQL instance itself (expensive, and duplicates what VTTablet already does locally on each tablet host), or (b) hold a stateful view of tablet health that required cross-VTGate coordination. The topo-server breaks that coupling:

  • VTTablet is the authoritative health signal (co-located with MySQL, cheap local probes).
  • VTGate is a consumer (reads the shared state, makes routing decisions, stays stateless).

This is an instance of the general patterns/shared-state-store-as-topology-unifier pattern — the pattern of putting a strongly-consistent small state store between a set of producers (health publishers) and a set of consumers (routers / schedulers / load balancers) so neither side has to talk to the other directly.

Implementation

The PlanetScale blog posts read as if the topo-server is abstract, but in open-source Vitess it is a pluggable interface with implementations backed by:

  • etcd — the default in most production deployments.
  • Consul — supported.
  • ZooKeeper — supported (the original choice at YouTube).

All three are strongly-consistent small-write-volume KV stores with watch primitives — the common shape that a topo-server needs. See the Vitess topology-server docs for details.

Consumed by

Written by

  • VTTablet — its own health + role state.
  • VTOrc / Orchestrator — reparenting decisions, cluster topology changes.
  • vtctl — administrative topology mutations.

What the topo-server is NOT

  • Not a query cache: queries do not go through the topo-server. Only tablet / shard / VSchema metadata does.
  • Not a storage tier: no user data in the topo-server.
  • Not part of the hot data path: VTGate caches topo-server reads with watch-based invalidation; topo-server read latency does not add to per-query latency.

Failure modes

If the topo-server is unavailable:

  • VTGate continues serving reads using cached tablet state — degraded but not dead.
  • New tablet additions / role changes don't propagate — cluster effectively frozen.
  • VTOrc cannot orchestrate new failovers.

This is the standard small-consensus-store failure mode: transient unavailability is tolerable for short windows; sustained outage degrades the control plane but not usually the data path.

Seen in

Last updated · 470 distilled / 1,213 read