Vitess · VTGate · PlanetScale

vitesschange
vschema
as code.

The first migration tool that versions Vitess VSchema. Vindexes, sharding keys, and sequence tables managed in YAML migrations. Online DDL monitored per shard. Other tools fire ALTER TABLE and marks it done — vitesschange waits for every shard to confirm.

18
CLI Commands
15306
VTGate Port
per-shard
DDL Polling
vitesschange — commerce deploy
$ vitesschange deploy --profile local --tag 1.2.0
[scan] 3 forward, 2 undo
[lock] acquired rakesh-zenbook:9cc6e889
[RUN] V1.0.0__create_core_tables.sql 5031ms
[ddl] Online DDL: d2860701…0%, d286d9a6…0%
[done] All shards complete
[RUN] V1.1.0__add_vschema.yaml 30ms
[vtg] APPLY VSCHEMA keyspace=commerce
[RUN] V1.2.0__add_indexes.sql
[detect] vtcombo → direct DDL strategy
✓ 3 applied · tag=1.2.0
$
Validated on Vitess 8.x+ PlanetScale vtcombo (local dev) VTGate MySQL protocol gh-ost strategy pt-osc strategy
Why vitesschange

VSchema is
not SQL.

Other tools have no concept of VSchema. They connect to VTGate and fire SQL statements — which means vindexes, sharding configuration, and sequence tables are never versioned, never audited, and never rolled back.

Key Differentiator
VSchema as YAML Migrations
VSchema defines how Vitess shards data — which tables are sharded, which columns are shard keys, and how lookup vindexes route queries. vitesschange versions VSchema in YAML migration files using ALTER VSCHEMA DDL, applied to the correct keyspace in the correct order. Every VSchema change is checksummed, timestamped, and audit-logged.
Key Differentiator
Online DDL Per-Shard Monitoring
When Vitess runs ALTER TABLE with ddl_strategy=vitess, it creates background jobs per shard with unique UUIDs. Other tools fire the statement and mark the migration done immediately. vitesschange polls SHOW VITESS_MIGRATIONS until every shard reports complete — and surfaces the exact failure reason per shard UUID if anything fails.
VSchema Migrations

Sharding config
versioned.

VSchema is the brain of Vitess routing. vitesschange is the only tool that treats it as source-controlled infrastructure.

# V1.1.0__add_vschema.yaml
# VSchema migration — Other tools have zero VSchema support
 
vschema:
  keyspace: commerce
  sharded: true
  vindexes:
    hash:
      type: hash
  tables:
    orders:
      column_vindexes:
        - column: customer_id
          name: hash
 
sequences:
  - name: order_seq
    keyspace: commerce_unsharded
Capabilities

Every command
Vitess-aware.

🗺
VSchema Versioning
Version vindexes, shard keys, and lookup tables as YAML migration files. Every VSchema change checksummed, audited, and rollbackable.
YAML NATIVE
Online DDL Monitoring
Polls SHOW VITESS_MIGRATIONS per shard until completion. Reports failure reason, shard UUID, and retry command when jobs fail. vtcombo auto-detected → direct DDL fallback.
PER-SHARD
🏗
Dedicated History Keyspace
Tracking tables (history, lock, audit, capacity) live in a separate vitesschange_history keyspace — never in your application keyspace. VTGate is single-keyspace-per-connection.
ISOLATED
🔧
vtcombo Auto-Detection
vtcombo (local dev Vitess) doesn't support Online DDL. vitesschange detects vtcombo from the error message and automatically retries with direct DDL — no config change needed.
LOCAL DEV
🔍
Drift Detection
Excludes Vitess-internal tables (_vt_*, Online DDL shadow tables) and VSchema sequence tables from drift reports — only flags tables that genuinely lack a migration.
VTTABLE AWARE
🩺
Doctor Command
Diagnose keyspace split-brain: checks that applied migration tables exist in the correct keyspace. Detects when DDL ran against the wrong database due to session switching.
DIAGNOSTICS
Rollback with direct DDL
Undo scripts always use direct DDL strategy — DROP INDEX and DROP TABLE are instant metadata operations. Rollbacks never block on Online DDL polling.
Seeder excludes internals
The seed command skips _vt_* Online DDL shadow tables, VSchema sequence tables (_seq suffix), and vitesschange tracking tables — seeds only your application tables.
Capacity in history keyspace
Capacity snapshots stored in vitesschange_history, never in commerce. Row counts queried from commerce, projections stored separately. No tooling tables pollute your application schema.
Release tagging
--tag 1.2.0 acts as both a version ceiling (stops after V1.2.0) AND a release stamp. Per-file -- tag: comments in SQL files used as automatic stamps when no CLI tag is given.
Comparison

vitesschange vs
alternatives

Other tools see Vitess as MySQL. vitesschange sees the sharding layer underneath.

CapabilityvitesschangeOther toolsPlain MySQL client
SQL DDL migrationsmanual
VSchema migrations (vindexes, sharding)✓ YAML
Online DDL per-shard monitoring✓ SHOW VITESS_MIGRATIONS
Online DDL failure details per shard✓ UUID + reason
vtcombo auto-detection + fallback✓ from error msg
Dedicated history keyspace✓ isolated
Sequence table lifecycle✓ YAML
Doctor — keyspace split-brain detection
Drift detection (excl. _vt_* tables)
Immutable audit logbasic
Installation

Start in
two minutes.

$ pip install vitesschange
Python 3.9+ · pymysql · pyyaml · Vitess 8+
# VTGate MySQL endpoint — default port 15306 (not 3306)
# vitesschange.yml — local profile
profiles:
  local:
    host: localhost
    port: 15306    # ← VTGate port
    database: commerce  # ← keyspace name
    ddl_strategy: vitess