Vitess
Understand how Vitess shards MySQL so you can design PlanetScale-style schemas, routing, and scaling without guessing what VTGate and VTTablet do.
Overview
Vitess is an agent skill most often used in Build (also Operate) that explains PlanetScale’s Vitess stack—VTGate, VTTablet, and topology—so solo builders can design and run sharded MySQL correctly.
Install
npx skills add https://github.com/planetscale/database-skills --skill vitessWhat is this skill?
- Explains VTGate as the stateless MySQL-protocol proxy for query routing, scatter-gather, and transaction modes
- Covers VTTablet sidecars, tablet types, connection pooling, Online DDL, and resharding operations
- Documents Topology Service metadata, shard targeting syntax, and OLTP vs OLAP workload switching
- Notes multi-shard 2PC transactions as production-ready in Vitess v22+ for distributed ACID
- Links to official Vitess 23.0 architecture documentation as the source of truth
- Vitess v22+ emphasizes production-ready multi-shard 2PC for distributed transactions
- Architecture reference targets Vitess docs 23.0 overview
Adoption & trust: 869 installs on skills.sh; 484 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need to scale MySQL horizontally but only know single-instance mysqld, not how proxies, tablets, and topology actually route your SQL.
Who is it for?
Indie SaaS backends on PlanetScale or Vitess who are defining keyspaces, shard ranges, or tablet roles for the first time.
Skip if: Teams on a single managed Postgres instance with no MySQL sharding path, or anyone who only needs generic SQL tuning without clustering concepts.
When should I use this skill?
You are designing, deploying, or debugging a Vitess or PlanetScale MySQL cluster and need VTGate, VTTablet, topology, and tablet-type behavior explained.
What do I get? / Deliverables
You can map application connections, sharding, failovers, and DDL to the right Vitess components and official architecture docs before you commit schema or infra changes.
- Accurate mental model of Vitess components
- Shard targeting and workload-mode decisions aligned with official docs
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build because Vitess architecture is what you learn while designing a horizontally scalable MySQL-backed product, not after launch analytics. Backend is where connection routing, keyspaces, sharding, and tablet types directly affect API and data-layer decisions.
Where it fits
Choose keyspace and shard boundaries before writing migrations for a multi-tenant SaaS.
Decide when to switch workload to OLAP mode versus strict OLTP timeouts before load testing.
Interpret tablet health and replication-lag throttling during an incident on a sharded cluster.
How it compares
Reference architecture for sharded MySQL clusters—not a generic ORM or migration CLI skill.
Common Questions / FAQ
Who is vitess for?
Solo and indie builders shipping MySQL-backed APIs who use PlanetScale or Vitess and need a clear picture of VTGate, VTTablet, and topology before changing scale or failover behavior.
When should I use vitess?
During Build when designing schemas and shard strategy; during Ship when validating failover and cutover behavior; during Operate when investigating routing, replication lag throttling, or tablet health in production.
Is vitess safe to install?
It is documentation-style procedural knowledge with no built-in shell or network actions in the skill itself; review the Security Audits panel on this Prism page before trusting the upstream package source.
SKILL.md
READMESKILL.md - Vitess
# Vitess Architecture Vitess is a database clustering system for horizontal scaling of MySQL. Applications connect to **VTGate** (stateless MySQL-protocol proxy), which routes queries through **VTTablet** (sidecar alongside each mysqld) based on metadata in the **Topology Service**. Reference: https://vitess.io/docs/23.0/overview/architecture/ ## VTGate Stateless proxy. Load-balance across multiple instances. Handles: - **Query routing**: parses SQL, consults VSchema, routes to correct shard(s) - **Cross-shard execution**: scatter-gather, joins, aggregations, ORDER BY/LIMIT merging - **Transaction management**: single-shard (full ACID) and multi-shard transactions (atomic distributed transactions via 2PC, production-ready in v22+) - **Query buffering**: buffers queries during PlannedReparentShard failovers and MoveTables/Reshard traffic switches Shard targeting: `USE 'keyspace:-80';` or `USE 'keyspace:80-@replica';` OLTP (default, strict timeouts) vs OLAP mode: `SET workload = 'olap';` ## VTTablet Sidecar process alongside each mysqld. A VTTablet + mysqld pair = a **tablet**. Handles connection pooling (multiplexes many client connections to fewer MySQL backend connections), query rewriting, health reporting, Online DDL execution, throttling (based on replication lag), backup/restore, and resharding operations. ### Tablet types A tablet in the database cluster can take any one of the following roles at a time: | Type | Role | Notes | | --- | --- | --- | | `primary` | MySQL primary for shard | Reads and writes | | `replica` | MySQL replica, promotable | Live user-facing reads | | `rdonly` | MySQL replica, not promotable | Analytics, backups, background jobs | | `backup` | Taking a consistent backup | Returns to previous type after | | `restore` | Restoring from backup | Becomes replica/rdonly | | `drained` | Taken out of use | e.g. tablet with errant GTIDs | VTGate uses health checks (replication lag, serving state) to route to healthy, low-lag tablets. ## Topology Service Metadata store (etcd recommended) with two tiers: 1. **Global topology**: keyspaces, shards, VSchemas, cells, routing rules (single instance for cluster) 2. **Cell-local topology**: tablet metadata, health (per data center/AZ; cell outage doesn't affect others) A **cell** is a collocated group of servers (DC or AZ). VTGate serves reads from the local cell; cross-cell traffic includes writes to the primary (when it resides in another cell), VReplication streams, and global topo reads. ## vtctld and vtctldclient Cluster management server and CLI. Key commands: | Command | Purpose | | --- | --- | | `ApplySchema` / `ApplyVSchema` | Execute DDL / update VSchema | | `GetVSchema` / `GetTablets` | View VSchema / list tablets | | `PlannedReparentShard` | Graceful primary promotion | | `EmergencyReparentShard` | Force-promote during outage | | `MoveTables` / `Reshard` | Data migration workflows | | `VDiff` / `Backup` | Verify consistency / take backup | ## VTOrc Automatic failover manager. Detects primary failure, promotes best replica, re-points other replicas. Supports planned reparenting, emergency reparenting, and fully automatic promotion. ## Query lifecycle 1. Client sends MySQL query to VTGate 2. VTGate parses SQL → consults VSchema → generates execution plan 3. Routes to VTTablet(s) → VTTablet forwards to mysqld 4. Results flow back; VTGate merges multi-shard results (sort, aggregate, limit) **Execution plan types** (check with `VEXPLAIN PLAN`; shown as `Route` operator `Variant` values). For deeper debugging, `VEXPLAIN ALL` includes the MySQL query plans from each tablet, and `VEXPLAIN TRACE` includes metrics on how many rows are passed between parts of the query. Route variants as of v22+: | Route Variant | Meaning | | --- | --- | | `Unsharded` | Unsharded keyspace, single backend | | `Local` | Sin