> sharding & workflows
When one MySQL primary stops being enough, Vitess sharding is how PlanetScale scales horizontally: keyspaces hold your tables (sharded or unsharded), the VSchema tells Vitess how rows distribute across shards, and workflows move tables between keyspaces online with verification and reversible traffic switching. These are power-user commands — most databases never need them, but when you do, the CLI drives the whole migration.
// sharding & workflows
9 commands$ pscale keyspace list mydb main$ pscale keyspace create mydb main sharded-ks --shards 2 --cluster-size PS-40 --wait$ pscale keyspace resize mydb main my-keyspace --cluster-size PS-80$ pscale keyspace vschema show mydb main sharded-ks$ pscale workflow create mydb main --name move-events --source-keyspace mydb --target-keyspace sharded-ks --tables events,event_properties$ pscale workflow list mydb main$ pscale workflow verify-data mydb main 1$ pscale workflow switch-traffic mydb main 1 --replicas-only$ pscale workflow cutover mydb main 1// faq
What is a keyspace and when do I need more than one?
A keyspace is a logical schema that maps to one or more physical shards. Every Vitess database starts with a single unsharded keyspace. You add keyspaces when a table group outgrows a single primary — typically creating a sharded keyspace and moving the hot tables into it with a workflow.
How does moving tables between keyspaces avoid downtime?
A workflow (Vitess MoveTables) copies the tables, keeps them in sync via replication, and lets you switch traffic in stages — replicas first with --replicas-only, then primaries. Every stage is reversible with reverse-traffic until you run cutover, and verify-data checks consistency before you commit.
What's the difference between switch-traffic and cutover?
switch-traffic re-routes queries to the target keyspace while replication continues back to the source — you can still bail out with reverse-traffic. cutover is the point of no return: it deletes the moved tables from the source and stops replication. Only cutover after verify-data is clean and the app has run quietly on the target.