CONCEPT Cited by 1 source
Schema routing rules¶
Definition¶
Schema routing rules are a Vitess feature (docs) that let operators declare, at the keyspace / table / workflow level, which backing storage a given query should be routed to. For a table participating in a migration, a routing rule says "queries for this table currently go to keyspace A" — and can be atomically updated to "queries for this table now go to keyspace B" without the application knowing or caring about the difference.
From the application's perspective, it connects to
Vitess (a vtgate endpoint or
PlanetScale URL). The routing rule
then determines whether a query for table orders is
forwarded to the external MySQL instance (during migration)
or resolved inside the Vitess-managed keyspace
(post-cutover). The application's connection string and
SQL don't change.
Why it matters for cutovers¶
Atomic query-level routing is the mechanical primitive that
makes application-invisible cutover possible. The other
moving parts of a migration (data copy, replication
catch-up, verification, query buffering, reverse workflow
setup) all converge on a single point: "change the routing
rule from orders → source-keyspace to orders → target-
keyspace" — at which point every subsequent query
(including the ones being held in
query buffer) goes to
the new backend.
This is the load-bearing piece of the routing-rule-swap cutover pattern. Without it, cutover is done by rotating the application's connection string — which is (a) coordinated across every client process, (b) visible as a brief reconnection storm, (c) not atomic across tables. With it, cutover is a single topology-server transaction.
Mechanics in Vitess MoveTables¶
At migration start (via
MoveTables Create):
- Schema routing rules are inserted for each participating table, pointing all queries at the source keyspace.
- Application connects to Vitess / PlanetScale; Vitess forwards queries back to the external source via an unmanaged tablet per the routing rules.
At cutover (via MoveTables SwitchTraffic):
- Source keyspace writes are stopped + queries buffered in VTGate.
- Replication catches up fully.
- Routing rules for the migrated tables are atomically updated to point at the target keyspace.
- Buffered queries are released against the target.
- Reverse VReplication workflow keeps the source keyspace in sync for possible rollback.
If the customer calls ReverseTraffic, the routing rules
flip back to the source keyspace. On Complete, the
migration-related routing-rule artefacts are cleaned up.
(Source: sources/2026-02-16-planetscale-zero-downtime-migrations-at-petabyte-scale.)
Seen in¶
- sources/2026-02-16-planetscale-zero-downtime-migrations-at-petabyte-scale — canonical wiki description of schema routing rules as the mechanism Vitess uses to direct per-table queries to the correct backing store during a migration. Matt Lord makes the routing-rule flip the explicit moment of cutover: "Schema routing rules are put in place so that during the migration, queries against the tables being migrated will be routed to the correct destination — the external MySQL instance (old system) or the PlanetScale database (new system) depending on where we are in the migration process. When the migration starts, these rules ensure that all queries are sent to the source keyspace (old system) and they are updated accordingly when traffic is cutover along with if and when the cutover is reversed."