How VTGate Routes Queries Using Vitess Keyspace Topology

Useful answer

VTGate automatically directs each client SQL statement to the tablet that holds the data, by consulting a cached copy of the Vitess keyspace topology. This eliminates the need for application‑level sharding logic and lets Vitess handle routing, failover and table splitting transparently.

How VTGate uses cached topology

When VTGate starts, it connects to the topology service (etcd, ZooKeeper or Consul) and builds an in‑memory map of:

• keyspaces and their shards
• tablet aliases (e.g., zone1-0000000100) and their host/port
• the current serving type (master, replica, rdonly) for each tablet

This map is refreshed periodically (default 1 second) and on topology change events. When a SQL query arrives, VTGate parses it, extracts the target keyspace and (if present) the sharding key, looks up the responsible tablet in the cache, and forwards the request to that tablet’s VTTablet gRPC endpoint.

Configuration example

To enable VTGate to discover tablets, you point it at the running topology service and optionally restrict it to a specific cell. The command below assumes you have Vitess binaries in $VTROOT/bin and a topology service reachable at etcd://localhost:2379:

# Run as the vitess user (or a user with read access to the topology)
$VTROOT/bin/vtgate \
  -topo_implementation etcd2 \
  -topo_global_server_addresses etcd://localhost:2379 \
  -topo_global_root /vitess/global \
  -tablet_types_to_wait PRIMARY,REPLICA \
  -port 15001 \
  -grpc_port 15991 \
  -service_map 'grpc-queryservice,grpc-tabletmanager,grpc-updateservice' \
  -pid_file /var/run/vtgate.pid \
  -log_dir /var/log/vitess

Key flags:

-topo_implementation Chooses the backend for the topology store (etcd2, zk2, consul). -topo_global_server_addresses List of topology service endpoints. -tablet_types_to_wait VTGate will not route to a tablet until at least one tablet of each listed type is known (helps avoid routing to a shard that has no master yet).

Limits

VTGate’s routing works per‑statement and assumes the data needed for the query lives in a single keyspace (or a single shard within a keyspace). Consequently:

• Cross‑keyspace joins are not supported; the query must be rewritten or executed via an external tool that can merge results.
• Queries that reference tables split across multiple shards (via VSchema table splitting) are routed to the appropriate shard per table, but VTGate cannot perform a join that spans those shards.
• Unsupported SQL features such as subqueries that reference tables in different shards will return an error (vttablet: unsupported query).

Common mistakes

Misconfigured tablet alias

If the -tablet_types_to_wait flag lists a tablet type that does not exist in the topology, VTGate will wait indefinitely for that tablet and appear to hang. Verify that the aliases you expect (e.g., zone1-0000000100) match those shown by vtctlclient ListTablets.

Stale topology cache

When the topology service is unreachable, VTGate falls back to the last known cache. Routing errors then occur because the cache may point to a tablet that has been removed or failed. Ensure the topology service is highly available and monitor VTGate logs for messages like Failed to connect to topology.

Verification steps

After starting VTGate, you can confirm it sees the expected topology:

1. List keyspaces as VTGate sees them:

   $VTROOT/bin/vtctlclient -server localhost:15999 ListKeyspaces

   Expected output includes the keyspace you configured (e.g., commerce).
2. Run a simple SELECT and inspect the tablet ID in the response header (visible via the VTGate debug endpoint or by enabling query logging):

   SELECT 1;

   The returned tablet ID should match one of the tablets listed for the target keyspace.
3. Test failover: stop the tablet currently serving as master for a shard (vtctlclient TabletExternallyReparented or kill the VTTablet process) and re‑run the SELECT. VTGate should route the next query to the new master tablet within a second.

Practical decision: reduce read lag with semi‑sync replication

Because VTGate routes read queries to replicas, you may notice stale reads if replication lag is high. Enabling semi‑synchronous replication on the VTTablet masters (via -semi_sync_master_enabled and -semi_sync_replica_enabled flags) ensures that a replica only acknowledges a transaction after the master has written it to its relay log, dramatically cutting lag. After enabling semi‑sync, verify lag with vtctlclient ReplicationStatus; the SecondsBehindMaster column should read 0 or a low value during normal load.