Implement "Tablet Targeting" RFC #18809

nickvanw · 2025-10-25T15:36:01Z

Description

This PR adds the ability for a user to target a specific tablet by alias when doing USE, instead of only being able to pick a type for a shard. This means that a user can get "stable" routing, which is extremely useful when they don't have access to the underlying MySQL instance and need to do things like debug.

Related Issue(s)

Fixes: RFC: Tablet Targeting #18808

Checklist

"Backport to:" labels have been added if this change should be back-ported to release branches
If this change is to be back-ported to previous releases, a justification is included in the PR description
Tests were added or are not required
Did the new or modified tests pass consistently locally and on CI?
Documentation was added or is not required

AI Disclosure

This PR was written hand-in-hand with Claude Code, which absolutely got the initial few approaches extremely incorrect and required a lot of human help. Robot isn't going to take my job any time soon.

vitess-bot · 2025-10-25T15:36:04Z

codecov · 2025-10-25T16:01:08Z

Codecov Report

❌ Patch coverage is 94.02985% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.90%. Comparing base (cd546ab) to head (c8edb0b).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
go/vt/vtgate/executorcontext/vcursor_impl.go	83.33%	2 Missing ⚠️
go/vt/topo/topoproto/destination.go	96.00%	1 Missing ⚠️
go/vtbench/client.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #18809      +/-   ##
==========================================
- Coverage   69.91%   69.90%   -0.01%     
==========================================
  Files        1613     1613              
  Lines      216071   216124      +53     
==========================================
+ Hits       151073   151089      +16     
- Misses      64998    65035      +37

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Signed-off-by: Nick Van Wiggeren <[email protected]>

…re it is not valid to set Signed-off-by: Nick Van Wiggeren <[email protected]>

Signed-off-by: Nick Van Wiggeren <[email protected]>

nickvanw · 2025-12-10T11:51:45Z

I believe this is ready for another review @harshit-gangal! Let me know if you have any questions.

timvaillancourt · 2025-12-11T18:39:55Z

changelog/24.0/24.0.0/summary.md


 For examples and more details, see the [documentation](https://vitess.io/docs/24.0/reference/compatibility/mysql-compatibility/#window-functions).

+#### <a id="tablet-targeting"/>Tablet targeting via USE statement</a>


@nickvanw let's say I use this feature to write rows to a PRIMARY that doesn't align with the VSchema, am I creating any data correctness/etc risks we should detail here?

I'm wondering if that would cause query failures or potentially-surprising results. But at the same time, I guess you can only use this feature with intention 🤔

And on a similar track, could vReplication get upset about rows in the wrong shard? One dreamed-up scenario I can think of is merging shards, and the same primary key exists in both, etc

None of what I'm thinking means changing the code here I think (it looks good so far), maybe just documentation

let's say I use this feature to write rows to a PRIMARY that doesn't align with the VSchema, am I creating any data correctness/etc risks we should detail here?

I don't think the introduction of this feature changes this - you can already target specific shards and side-step any validation that Vitess would normally do against the queries you are executing (like ensuring inserts only are routed to the "correct" shard).

github-actions · 2026-01-11T01:36:05Z

This PR is being marked as stale because it has been open for 30 days with no activity. To rectify, you may do any of the following:

Push additional commits to the associated branch.
Remove the stale label.
Add a comment indicating why it is not stale.

If no action is taken within 7 days, this PR will be closed.

nickvanw · 2026-01-12T01:42:02Z

I'm still working on this! If you have time for review @harshit-gangal, I would appreciate it 😁

mattlord

LGTM! Just some minor comments/questions/suggestions.

go/vt/topo/topoproto/destination.go

mattlord · 2026-01-15T18:35:55Z

go/vt/vtgate/executorcontext/safe_session.go


 		logging *ExecuteLogger

+		// targetTabletAlias is set when using tablet-specific routing via USE keyspace@tablet-alias.


It must contain the shard too, no? keyspace:shard@tablet-alias

I'm also not sure when/why you would specify the tablet type in this context from the changelog info. When I read that, I thought that the shard AND tablet type would be required and we would confirm that it still matches when doing the routing.

Yes! This was an older comment, the shard and the tablet type are required (in part, to avoid accidentally trying to write to a replica, etc)

mattlord · 2026-01-15T18:40:20Z

go/vt/vtgate/executorcontext/safe_session_test.go

 }
+
+// TestTargetTabletAlias tests the SetTargetTabletAlias and GetTargetTabletAlias methods.
+func TestTargetTabletAlias(t *testing.T) {


This feels like overkill to me -- a test for a setter/getter -- but obviously fine too.

go/vt/vtgate/scatter_conn.go

go/vt/topo/topoproto/destination_test.go

go/vt/vtgate/scatter_conn_test.go

arthurschreiber

LGTM ❤️

- Fix comment in safe_session.go to use correct syntax - Add bounds check for empty string after @ in ParseDestination - Use require.EqualError instead of manual error checking in tests - Change %v to %s for string formatting in error message - Use require.ErrorContains instead of require.Error + require.Contains Signed-off-by: Nick Van Wiggeren <[email protected]>

Signed-off-by: Nick Van Wiggeren <[email protected]>

promptless · 2026-01-17T01:03:07Z

📝 Documentation updates detected!

New suggestion: Document tablet-specific targeting via USE statement

nickvanw added Type: Feature Component: Query Serving Component: VTGate labels Oct 25, 2025

github-actions bot added this to the v24.0.0 milestone Oct 25, 2025

nickvanw force-pushed the nickvanw/direct-access branch 5 times, most recently from f77286f to 1eb17dd Compare October 27, 2025 07:41

nickvanw force-pushed the nickvanw/direct-access branch 8 times, most recently from 84f29f0 to 6c49907 Compare October 27, 2025 14:03

nickvanw marked this pull request as ready for review October 27, 2025 14:28

nickvanw requested review from harshit-gangal and systay as code owners October 27, 2025 14:28

nickvanw added 4 commits December 7, 2025 09:07

fix tests with partial ks

1ec01a9

Signed-off-by: Nick Van Wiggeren <[email protected]>

code review feedback: test improvements & do not set target alias whe…

5fe677e

…re it is not valid to set Signed-off-by: Nick Van Wiggeren <[email protected]>

cleanup handling SetTarget

f638a62

Signed-off-by: Nick Van Wiggeren <[email protected]>

update test to properly fail while in txn

25a0e9c

Signed-off-by: Nick Van Wiggeren <[email protected]>

nickvanw force-pushed the nickvanw/direct-access branch from 5b2df7d to 25a0e9c Compare December 7, 2025 07:07

nickvanw removed request for beingnoble03, rohit-nayak-ps and shlomi-noach December 7, 2025 07:13

move test to using require.Eventually and not time.Sleep

5c0bc2d

Signed-off-by: Nick Van Wiggeren <[email protected]>

nickvanw force-pushed the nickvanw/direct-access branch from 6aa9310 to 5c0bc2d Compare December 8, 2025 06:53

nickvanw removed the NeedsWebsiteDocsUpdate What it says label Dec 8, 2025

promptless bot mentioned this pull request Dec 8, 2025

docs: Document tablet-specific targeting syntax for USE statements vitessio/website#2041

Open

add changelog information for tablet targeting

a637fc9

Signed-off-by: Nick Van Wiggeren <[email protected]>

nickvanw removed the release notes (needs details) This PR needs to be listed in the release notes in a dedicated section (deprecation notice, etc...) label Dec 8, 2025

timvaillancourt reviewed Dec 11, 2025

View reviewed changes

github-actions bot added Stale Marks PRs as stale after a period of inactivity, which are then closed after a grace period. and removed Stale Marks PRs as stale after a period of inactivity, which are then closed after a grace period. labels Jan 11, 2026

harshit-gangal approved these changes Jan 15, 2026

View reviewed changes

mattlord approved these changes Jan 15, 2026

View reviewed changes

arthurschreiber approved these changes Jan 16, 2026

View reviewed changes

nickvanw added 3 commits January 16, 2026 18:57

Merge main into nickvanw/direct-access

7259df6

Signed-off-by: Nick Van Wiggeren <[email protected]>

Update changelog: use replica example and add shard requirement note

c8edb0b

Signed-off-by: Nick Van Wiggeren <[email protected]>

nickvanw merged commit 21e1aee into main Jan 16, 2026
103 of 110 checks passed

nickvanw deleted the nickvanw/direct-access branch January 16, 2026 23:24

promptless bot mentioned this pull request Jan 17, 2026

docs: Document tablet-specific targeting via USE statement vitessio/website#2058

Open


		For examples and more details, see the [documentation](https://vitess.io/docs/24.0/reference/compatibility/mysql-compatibility/#window-functions).

		#### <a id="tablet-targeting"/>Tablet targeting via USE statement</a>


		logging *ExecuteLogger

		// targetTabletAlias is set when using tablet-specific routing via USE keyspace@tablet-alias.

Implement "Tablet Targeting" RFC #18809

Implement "Tablet Targeting" RFC #18809

Uh oh!

Conversation

nickvanw commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue(s)

Checklist

AI Disclosure

Uh oh!

vitess-bot bot commented Oct 25, 2025

Review Checklist

General

Tests

Documentation

New flags

If a workflow is added or modified:

Backward compatibility

Uh oh!

codecov bot commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

nickvanw commented Dec 10, 2025

Uh oh!

timvaillancourt Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arthurschreiber Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 11, 2026

Uh oh!

nickvanw commented Jan 12, 2026

Uh oh!

mattlord left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mattlord Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

nickvanw Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

mattlord Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

arthurschreiber left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

promptless bot commented Jan 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

nickvanw commented Oct 25, 2025 •

edited

Loading

codecov bot commented Oct 25, 2025 •

edited

Loading

timvaillancourt Dec 11, 2025 •

edited

Loading