Vitess

20.x

stableCost: highTeam: staff plusLatency: single digit msDurability: strong

Summary

MySQL sharding middleware that proxies MySQL connections, routes queries to the correct shard based on a configured vindex (sharding key), and merges results for cross-shard queries. Originally built at YouTube in 2011 to scale MySQL beyond single-instance capacity. Now a CNCF graduated project used by Slack, HubSpot, and PlanetScale.

Primary Use Case

Horizontal write scaling for MySQL workloads that have outgrown single-primary MySQL capacity. Provides application-transparent sharding without requiring application code changes to shard routing logic, assuming queries include the sharding key.

Workload Fit

transactionalhigh write throughputsharded relationalweb application

Strengths

Best for

·MySQL workloads that have outgrown single-primary write capacity and require horizontal write scaling without changing application query language
·High-scale SaaS products with natural tenant-based sharding keys where each tenant's data is isolated to a shard
·Organizations with deep MySQL operational expertise who need sharding without migrating to a distributed SQL database
·Workloads requiring live resharding (adding capacity) without downtime: Vitess's VReplication workflow handles this
·Applications at YouTube/GitHub/Slack scale where single-MySQL capacity limits have been reached and Vitess is the proven solution

Excels when

·Almost all production queries include the sharding key in their WHERE clause: scatter queries are rare, not the norm
·The sharding key is a well-distributed value (UUID, hashed customer ID) that evenly distributes load across shards
·Cross-shard transactions are infrequent: the application is designed so that most transactions touch a single shard
·Team has staff-level MySQL and distributed systems expertise to own the Vitess operational model

Architectural advantages

·Application-transparent sharding: applications connect to VTGate with a standard MySQL connection; the sharding routing is invisible to the application for on-shard queries
·Live resharding via VReplication: doubling shard count is a live operation with continuous replication and a brief cutover window; no scheduled downtime required
·Connection pooling built into VTTablet: each shard's VTTablet multiplexes application connections into a smaller pool of connections to MySQL, eliminating connection storms
·Query rewriting for shard routing: VTGate rewrites queries to target the correct shard based on the vindex without application changes
·CNCF graduated project with PlanetScale providing commercial support and a managed service version

When to Avoid

Avoid when

·Single-primary MySQL has not yet been exhausted: Vitess adds very high operational overhead that is not justified until MySQL's single-primary limits are reached
·Query patterns are inherently cross-shard (analytics, joins across tenant boundaries): scatter queries on every request negate the sharding benefit
·Team lacks staff-level distributed systems expertise: Vitess's failure modes (VTTablet failure, topology service outage, resharding stalls) require deep expertise to diagnose and recover
·The application cannot tolerate eventual consistency on cross-shard reads or the limitation that cross-shard ACID transactions are expensive

Common misuses

·Choosing Vitess before MySQL single-primary capacity is demonstrated to be insufficient: operating Vitess is significantly more complex than operating MySQL; exhaust vertical scaling and read replicas first
·Using an unsharded Vitess keyspace as a MySQL proxy without intending to shard: adds VTGate overhead without sharding benefit; use ProxySQL instead
·Running analytics workloads on Vitess-sharded MySQL: scatter queries across 10+ shards for analytical aggregations have poor performance; route analytics to a dedicated OLAP store

Consistency & Transactions

Consistency modelstrong

ACID compliantYes

Supports transactionsYes

Scaling

Characteristics

horizontal writehorizontal readsharded

Operational burdenvery high

Typical read latency3 ms

Typical write latency5 ms

Read scalability

Each shard is a standard MySQL primary + replica topology; read traffic is distributed across shards. Replicas on each shard serve read traffic via VTGate's routing rules. Cross-shard reads that don't specify the sharding key scatter to all shards and merge results: these are expensive and must be avoided in hot query paths.

Write scalability

Writes scale horizontally: each shard has its own MySQL primary. Adding shards (via the Vitess resharding workflow) doubles write capacity by splitting key ranges. Resharding is a live operation that does not require downtime, using a VReplication-based cutover workflow. Write throughput scales roughly linearly with shard count for queries that include the sharding key.

Failure Behavior

Known failure modes

·Scatter query latency amplification: queries without the sharding key are executed on all shards and results are merged in VTGate; a 20-shard cluster turns a 5ms query into 100ms+ scatter overhead
·Cross-shard transaction degradation: transactions that write to rows on multiple shards require two-phase commit across shard primaries; performance is significantly worse than single-shard transactions and success depends on all shard primaries being available
·VTTablet process failure on a shard: VTTablet is the sidecar process co-located with each MySQL instance; if VTTablet fails, Vitess can no longer route to that MySQL instance even if MySQL itself is healthy
·Topology service unavailability: if the etcd or ZooKeeper backing the Vitess topology service becomes unavailable, VTGate cannot make routing decisions for queries affecting unknown shards
·Resharding stalls: the VReplication-based resharding workflow depends on MySQL replication keeping pace with inserts; high write load during resharding can cause the replication stream to fall behind and delay cutover
·Vindex lookup table divergence: non-primary vindexes that use a lookup table can diverge from the primary vindex if the lookup table insert fails: requires reconciliation tools

Bottlenecks

·Scatter query fan-out: any query without the sharding key is sent to all shards and results are merged in VTGate memory; VTGate becomes the merge bottleneck for large scatter result sets
·Cross-shard two-phase commit: transactions spanning multiple shards go through Vitess 2PC coordinator; commit latency is proportional to the number of shards involved and network RTT to each
·VTGate as a single routing tier: all application traffic flows through VTGate instances; VTGate must be horizontally scaled to avoid becoming a throughput bottleneck
·Resharding I/O load: the VReplication stream during resharding copies data at near-MySQL replication speed; sustained resharding can saturate disk I/O on the source shard
·Topology service read amplification: VTGate reads tablet discovery data from etcd/ZooKeeper on startup and on topology changes; topology service latency directly impacts VTGate startup time

Degradation patterns

·Scatter query amplification under shard growth: as shard count grows, each scatter query fans out to more shards; a query that was 10ms at 4 shards becomes 40ms at 16 shards without query optimization
·VTTablet restart causes brief routing blackout: when VTTablet on a shard restarts, VTGate cannot route to that shard until VTTablet re-registers with the topology service
·Resharding stall under write pressure: if write rate to the source shard exceeds VReplication's catch-up speed during resharding, the cutover window never arrives and resharding must be paused

Recovery considerations

·Individual MySQL instance failure recovers via standard MySQL failover (MHA, Orchestrator, or manual promotion); VTTablet on the new primary re-registers with the topology service
·VTGate failure is stateless: a new VTGate instance reads routing rules from the topology service on startup; VTGate instances can be replaced without data impact
·Resharding failure mid-workflow leaves the source shard as the authoritative copy; the incomplete target shard can be discarded and resharding restarted from the beginning

Operational Pitfalls

·Not auditing all production queries for sharding key presence before deploying: scatter queries on hot paths are the most common post-migration performance surprise
·Using a monotonic or sequential sharding key: range-based sharding with a sequential key produces a hot shard at the high end of the range; use hash vindexes for even distribution
·Attempting cross-shard transactions in high-volume paths: Vitess 2PC is correct but slow; application design should avoid cross-shard writes in transaction-heavy code paths
·Not running the VTExplain tool before deploying new queries: VTExplain shows whether a query scatters to all shards or targets a single shard; scatter on a hot endpoint is a production incident waiting to happen
·Underestimating the operational complexity: Vitess requires operating MySQL, VTTablet (sidecar per MySQL instance), VTGate (query router), and a topology service (etcd/ZooKeeper) as separate processes with independent failure modes

Architecture Guidance

Common topology roles

sharded data nodetransactional backendhigh scale mysql clustermulti shard coordinator

Migration notes

·From bare MySQL: migrate using Vitess MoveTables workflow: starts VReplication from MySQL to Vitess unsharded keyspace, then applies sharding without downtime
·Schema changes in Vitess use Online DDL (gh-ost or pt-online-schema-change under the hood) to avoid table locks across all shards; always use Online DDL for production schema migrations
·To PlanetScale: PlanetScale is Vitess as a managed service with branching-based schema changes; migration reduces operational overhead at the cost of losing direct MySQL access

Advisor Guidance

Info

When: scenario requires horizontal write scaling beyond single MySQL primary capacity

Design sharding key strategy before deploying Vitess: the vindex choice is permanent and scatter query impact must be analyzed against all production query patterns

Warning

When: scenario includes queries that do not include the sharding key in their WHERE clause

Run VTExplain on all hot query paths before deploying to Vitess; scatter queries on high-traffic endpoints will degrade latency proportional to shard count

Critical

When: team does not have prior Vitess or distributed MySQL operational experience

Vitess operational complexity (VTGate, VTTablet, topology service, resharding workflows) requires staff-level expertise; evaluate PlanetScale managed service to reduce operational burden

Comparison Factors

horizontal write scalability

Strong: write throughput scales linearly with shard count for on-shard writes; the definitive solution for MySQL write scaling

high

operational complexity

Very high: requires operating MySQL, VTTablet sidecar, VTGate router, and topology service as independent process groups with complex failure interactions

high

cross shard query performance

Poor: scatter queries are expensive and degrade linearly with shard count; application schema and query design must minimize scatter

low

migration risk

High: vindex design decisions are effectively permanent; incorrect sharding key selection requires a full resharding workflow to correct

high

Managed Cloud Options

PlanetScale (Vitess as a service)

Enables Patterns

shardingread replicaread replica with routing proxyconnection pooling

Basis

Vitess architecture is publicly documented; YouTube origin and CNCF graduation provide validated at-scale operational evidence; Slack and PlanetScale production reports confirm operational characteristics

Related Architecture Knowledge

Outbound: this entity affects

Introduces RiskFailure Mode

cross shard query degradation

Grounded

Vitess enables MySQL sharding but cross-shard queries (queries without the shard key) require scatter-gather execution across all shards, with latency proportional to shard count.

Full relationship →