Skip to content

SYSTEM Cited by 3 sources

VTCtld

What it is

VTCtld is the cluster-management / administrative-control process of a Vitess cluster. It is the third named Vitess primitive alongside VTGate (query router) and VTTablet (MySQL sidecar). Its job is to expose an administrative interface — historically a daemon with a gRPC API (the vtctld server), driven by the vtctl / vtctldclient CLI — through which operators (human or automated) perform cluster-level operations: schema changes, tablet reparenting, keyspace creation, backup orchestration, resharding, workflow control, topology edits.

From PlanetScale's own pedagogy-101 description:

"The entire cluster is controlled by a vtctld instance, a management interface that our internal systems communicate with to perform administrative operations." (Source: sources/2026-04-21-planetscale-what-makes-up-a-planetscale-vitess-database)

Role in the Vitess architecture

The three Vitess primitives divide responsibility along a control-plane / data-plane axis:

Primitive Plane Responsibility
VTGate Data Accept MySQL-protocol queries, route to tablets
VTTablet Data Connection pool + health-check the local mysqld
VTCtld Control Administrative operations on the cluster

VTCtld sits out of the query path. No customer query ever touches it. It only runs administrative verbs against the cluster — read topo-server, write topo-server, invoke per-tablet RPCs for operations like PlannedReparentShard, EmergencyReparentShard, ApplySchema, Backup, Restore, MoveTables, Reshard, VDiff. This is a canonical control-plane / data-plane separation: the data plane (VTGate + VTTablet) keeps serving queries even if VTCtld is unreachable; VTCtld failure caps blast radius to "cannot perform admin operations right now" rather than "database is down."

VTCtld in PlanetScale's branching substrate

Morrison II's 2023-08-23 What-makes-up-a-PlanetScale-Vitess-database post canonicalises a load-bearing fact about PlanetScale's database branching model: every branch is an independent Vitess cluster, and branch creation is a vtctld-to-vtctld operation:

"when you create a branch, we'll spin up a new Vitess cluster for it and (using the vtctld component of the two clusters) apply the schema of the source database branch with the one you just created!"

Translation: to clone the schema from source branch → new branch, PlanetScale signals Kubernetes to provision a new Vitess cluster (new VTTablet pods, new VTGate pods, new VTCtld pod), then the new cluster's vtctld pulls the schema from the source cluster's vtctld and applies it. Schema-clone is a control-plane-to-control-plane operation; no data-plane involvement.

Fleet topology

In PlanetScale's multi-tenant Kubernetes fleet (see patterns/custom-operator-over-statefulset):

  • One vtctld pod per Vitess cluster (where "Vitess cluster" = "PlanetScale database branch")
  • Co-located with the per-branch VTGate + VTTablet pods
  • Driven by PlanetScale's internal control plane (not customer-facing)
  • Customer never sees vtctld directly — admin operations the customer can initiate (deploy requests, schema changes, branch creation, shard operations via Workflows) are mediated by PlanetScale's product surface that calls into vtctld on the customer's behalf

What VTCtld does NOT do

  • Does not proxy queries — that is VTGate's job.
  • Does not hold MySQL connections — that is VTTablet's job.
  • Is not on the customer's hot path — customer applications never connect to VTCtld.
  • Is not durable state storage — cluster state (tablet roles, keyspace topology, VSchema, routing rules) lives in the topo-server (etcd or ZooKeeper). VTCtld reads and writes topo but is not itself the source of truth.
  • Is not leader-elected — VTCtld is effectively stateless from the cluster's perspective. Multiple vtctld processes can coexist (and historically did: the older UI-serving vtctld vs the RPC-serving vtctld split before the mid-2022 vtctldclient unification; PlanetScale's naming collapses that distinction at pedagogy altitude).

Seen in

Last updated · 470 distilled / 1,213 read