RFC: Tablet Targeting

[nickvanw]

RFC: Tablet-Specific Routing in VTGate

Problem Statement

Vitess users need a way to route queries to specific tablets for operational and observability purposes. Currently, VTGate routes queries based on keyspace, shard, and tablet type (PRIMARY, REPLICA, RDONLY), but there's no standardized way to target an individual tablet within a shard.

Current Limitations

• Monitoring Tools: Database monitoring and profiling tools often need to maintain persistent connections to specific tablets to collect per-tablet metrics accurately. Without tablet-specific routing, metrics get aggregated or inconsistently attributed across tablet replicas.

• Troubleshooting: When investigating performance issues or debugging query behavior on a specific tablet, operators have no simple way to send test queries directly to that tablet through VTGate.

• Operational Tasks: Tasks like warming up a specific replica's cache, testing a particular tablet's behavior, or validating tablet-specific configurations require workarounds or direct MySQL connections, bypassing VTGate's connection pooling and query rewriting.

Use Cases

1. Per-Tablet Observability: Monitoring tools that collect query performance metrics, slow query logs, or profiling data need to maintain stable connections to individual tablets to ensure metrics are correctly attributed.

2. Targeted Debugging: When a specific tablet exhibits unusual behavior (high CPU, slow queries, lock contention), operators need to send diagnostic queries directly to that tablet to investigate.

3. Selective Testing: Before promoting a replica to primary or after configuration changes, operators may want to test queries against a specific tablet without affecting production traffic patterns.

4. Cache Warming: After a tablet restart or failover, operators may want to send specific queries to warm up that tablet's query cache or buffer pool.

5. Development & QA: Developers testing sharded applications may need to target specific tablets to verify data distribution or test edge cases.

Proposed Solution

Extend VTGate's USE statement syntax to support tablet-specific routing:

USE commerce:-80@primary|zone1-0000000100;

Where tablet-alias follows the standard Vitess format: cell-uid (e.g., zone1-0000000100).

Behavior

• Sticky Connection: Once set, all subsequent queries in the session route to the specified tablet until cleared or changed
• Clear Targeting: Standard USE keyspace or USE keyspace@tablet-type clears tablet-specific routing

Syntax Examples

-- Target a specific tablet
USE commerce:-80@primary|zone1-0000000100;
SELECT * FROM products;  -- Routes to zone1-0000000100

-- Transactions work as expected
BEGIN;
INSERT INTO orders VALUES (...);
COMMIT;  -- All operations go to the same tablet

-- Clear tablet targeting, return to normal routing
USE commerce;
SELECT * FROM products;  -- Routes normally (load-balanced across replicas)

-- Switch to tablet type routing
USE commerce@replica;
SELECT * FROM products;  -- Routes to any replica (clears tablet-specific routing)

• Vitess already supports shard-specific routing: USE keyspace:shard@tablet_type
• Transactions already use tablet-specific routing internally via shardSession.TabletAlias
• This feature extends existing patterns to expose tablet-level control to users