vitess

Vitess best practices, query optimization, and connection troubleshooting for PlanetScale Vitess databases. Load when working with Vitess databases, sharding,…

INSTALLATION
npx skills add https://github.com/planetscale/database-skills --skill vitess
Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

$27

Concept

What it is

Keyspace

Logical database mapping to one or more shards. Analogous to a MySQL schema.

Shard

A horizontal partition of a keyspace, each backed by a separate MySQL instance.

VSchema

Configuration defining how tables map to shards, vindex (sharding) keys, and routing rules.

Vindex

Sharding function mapping column values to shards (hash, unicode_loose_xxhash, lookup).

VTGate

Stateless proxy that plans and routes queries to the correct shard(s).

Online DDL

Non-blocking schema migrations. On PlanetScale, use deploy requests for production changes.

PlanetScale specifics

  • Branching: Git-like database branches for development; deploy requests for production schema changes.
  • Connections: MySQL protocol, port 3306 (direct) or 443 (serverless). SSL always required.

SQL compatibility

Vitess supports nearly all MySQL syntax — most applications work without query changes. Standard DML, DDL, joins, subqueries, CTEs (including recursive CTEs as of v21+), window functions, and common built-in functions all work as expected.

Known limitations:

  • Stored procedures / triggers / events: Not supported through VTGate.
  • **LOCK TABLES / GET_LOCK**: Not supported through VTGate.
  • **SELECT ... FOR UPDATE**: Works within a single shard; cross-shard locking is not atomic.
  • Cross-shard joins: Supported but expensive (scatter-gather). Filter by vindex column for single-shard routing.
  • Correlated subqueries: May fail or perform poorly cross-shard. Rewrite as joins when possible.
  • IDs: Use Vitess Sequences (a global counter in an unsharded keyspace) or app-generated IDs (UUIDs, snowflake) to avoid collisions on sharded tables.
  • Aggregations on sharded tables: GROUP BY/ORDER BY/LIMIT merge in VTGate memory. Large result sets can be slow.
  • Foreign keys: Limited support. Prefer application-level referential integrity on sharded keyspaces.

References

Topic

Reference

Use for

VSchema

references/vschema.md

VSchema design, vindexes, sequences, sharding strategies

Schema Changes

references/schema-changes.md

Online DDL, managed migrations, ddl strategies, migration lifecycle

VReplication

references/vreplication.md

MoveTables, Reshard, Materialize, VDiff, VStream

Architecture

references/architecture.md

VTGate, VTTablet, Topology Service, VTOrc, component interactions

Query Serving

references/query-serving.md

Query routing, MySQL compatibility, cross-shard performance, EXPLAIN

BrowserAct

Let your agent run on any real-world website

Bypass CAPTCHA & anti-bot for free. Start local, scale to cloud.

Explore BrowserAct Skills →

Stop writing automation&scrapers

Install the CLI. Run your first Skill in 30 seconds. Scale when you're ready.

Start free
free · no credit card