CONCEPT Cited by 3 sources

Keyspace¶

A keyspace in Vitess is a logical database that holds a group of tables, optionally sharded, presenting a single SQL surface to the application. It is Vitess's unit of sharding, routing, and schema ownership — the level at which shard count, shard boundaries, Vindexes, and VSchema are defined.

Shape¶

Unsharded keyspace — one MySQL primary (plus replicas) holds every table in the keyspace. Equivalent to a single MySQL database from the application's perspective.
Sharded keyspace — the same set of tables, but rows are spread across N shards by a shard key declared in the VSchema. Each shard is a MySQL primary (plus replicas) owning a contiguous range of keyspace_id values.

A Vitess cluster can contain multiple keyspaces simultaneously — some sharded, some not. VTGate routes queries to the correct keyspace based on the table referenced + the VSchema; cross-keyspace JOINs are planned at the VTGate tier.

Why it's the right unit¶

Keyspace is coarser than a single table and finer than a whole cluster, which is the right granularity for the two architectural moves it supports:

Vertical sharding is "moving one keyspace to its own servers" — isolate a domain (or single hot table) to a dedicated MySQL cluster without sharding it internally. Canonical worked example: split musclemaker into musclemaker_main (users + exercises) and musclemaker_log (exercise_log, the hot table) — each becomes its own keyspace with its own sizing (Source: sources/2026-04-21-planetscale-dealing-with-large-tables).
Horizontal sharding is "growing one keyspace from 1 shard to N" — the Reshard workflow operates entirely inside a single keyspace, splitting its shard count while preserving its table set and VSchema.

Both moves are keyspace-scoped operations, which is what lets MoveTables cross keyspaces (for vertical sharding) while Reshard stays inside one (for horizontal sharding).

Schema ownership¶

Each keyspace owns its own:

VSchema — declares which tables are sharded, which column is the primary Vindex, which tables are reference tables (replicated to every shard), sequence tables for ID generation.
Schema — table DDL is applied per-keyspace; a schema change in one keyspace doesn't affect another.
Shard topology — shard count, shard-range boundaries (e.g. -40, 40-80, 80-c0, c0-), replica placement.

This separation is why keyspace ops compose cleanly: you can vertically shard a domain by moving tables to a new keyspace without touching the old keyspace's VSchema, then horizontally shard the new keyspace without touching the old one's shard topology.

Relation to MySQL's `database`¶

Inside each shard, the keyspace is realised as a MySQL database of the same name — so SHOW DATABASES on a single tablet shows the keyspace name. The mapping is 1 keyspace = 1 MySQL database per shard; N shards = N MySQL primaries each owning a subset of rows in that database.

Seen in¶

sources/2026-04-21-planetscale-dealing-with-large-tables — Ben Dicken's canonical three-rung scaling ladder walks keyspace operations end-to-end: vertical scaling (single keyspace grows vertically), vertical sharding (split one keyspace into two, downsize the cold one), horizontal sharding (grow one keyspace from 1 shard to 4 via Reshard). Canonical wiki worked example: musclemaker_main (16 vCPU / 32 GB RAM) + musclemaker_log (32 vCPU / 64 GB RAM / 4 TB) as the vertical-sharding shape. Also names the Vitess shard-range naming convention -40 / 40-80 / 80-c0 / c0- as the per-shard keyspace_id range ownership inside a sharded keyspace.
sources/2026-04-21-planetscale-what-makes-up-a-planetscale-vitess-database — broader Vitess-primitives primer that names keyspace as one of the load-bearing Vitess primitives alongside VTGate, VTTablet, VSchema, and topo server.
sources/2026-04-21-planetscale-temporal-workflows-at-scale-sharding-in-production — Savannah Longoria (2022-12-14) canonicalises the two-keyspace split for Temporal: small metadata tables in one unsharded keyspace, 13 write-hot tables in a sharded keyspace with xxhash on shard_id / range_hash. Worked production VSchema + migration path via MoveTables + SwitchTraffic.