A production field guide for running Vitess on sharded MySQL — designing horizontal topologies, coordinating online schema change across shards without downtime, and automating the routing, migration, and failover machinery that holds it all together.
🔗 Live site: www.shardedtopology.org
Scaling MySQL horizontally with Vitess is not a single decision — it is a stack of them: how you partition a keyspace, how VTGate routes a query, how a schema change reaches every shard in lockstep, and how you see any of it when the pager goes off at 3am. Most of that knowledge is scattered across source code, mailing-list threads, and hard-won incidents.
Sharded Topology collects it into one place: rigorous, operator-grade references written for the people who own the outcome. Every guide moves from concept → architecture → runnable configuration → failure modes → verification, the way an SRE actually debugs and builds. Each page carries hand-drawn architecture diagrams, real vtctldclient / VSchema / Python snippets, parameter tables with production-ready defaults, and a verification step you can run.
- Database platform engineers designing and scaling Vitess topologies
- MySQL SREs who own availability, latency, and schema-change safety
- Python orchestration builders automating VSchema, migrations, and failover
- Distributed-systems teams reasoning about routing, consistency, and resharding under live traffic
The library is organized into four in-depth areas:
- Sharding Architecture & Topology Design — keyspace partitioning models, horizontal shard layout and failure domains,
VTGaterouting internals, resharding workflows and shard splits, fallback routing, and multi-tenant isolation. - VSchema & Routing Rule Management — VSchema syntax and structure, vindex selection and tuning, lookup vindexes for cross-shard joins, dynamic routing rules, sequence tables, and async validation pipelines.
- Online DDL Orchestration & Migration Coordination — coordinating multi-shard migrations, throttling and cutover control, the global cutover barrier, migration state machines, native Online DDL vs. external tools, and Python-driven DDL pipelines.
- Observability & Operations — monitoring
VTGatequery latency, replication-lag and throttler signals, keyVTTabletPrometheus metrics, Grafana dashboards, and alerting on scatter-query ratios and DDL lag.
Every page is cross-linked, so you are always one or two clicks from the neighbouring concept, the parent overview, or the deep-dive beneath it.
- Eleventy static-site generator — content authored as Markdown under
content/, rendered through Nunjucks templates insrc/. - Hand-authored inline SVG diagrams that adapt to light and dark themes via CSS variables.
- Prism syntax highlighting and KaTeX math, both self-hosted for a fully offline-capable PWA (service worker + web manifest).
- JSON-LD structured data (TechArticle + BreadcrumbList) on every page.
- Deployed on Cloudflare Workers.
npm install
npm run build # generate the static site into _site/
npm run serve # local dev server with live reload
npm run deploy # build and publish to CloudflareBuilt for database platform engineers, MySQL SREs, and Python orchestration teams. Explore the full library at www.shardedtopology.org.