Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions proto/VERSION
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
pingcap/kvproto b41e86365ce0e0fba482005c0dfa5e2ca967d74c (2026-06-22)
Matches client-go v2.0.8-0.20260708122311-01bd8f99f4da (go.mod: kvproto v0.0.0-20260622063236-b41e86365ce0).
Re-vendor: copy proto/*.proto (matching names only) and include/ from that revision, then `make generate`.
pingcap/kvproto 121875fd9777 (2026-10-06)
Go module: github.com/pingcap/kvproto v0.0.0-20261006010420-121875fd9777.
Re-vendor: copy existing proto/*.proto, any new imported schemas, and include/ from that revision, then `make generate`.
24 changes: 24 additions & 0 deletions proto/apipb.proto
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
syntax = "proto3";
package apipb;

import "gogoproto/gogo.proto";
import "rustproto.proto";

option java_package = "org.tikv.kvproto";
option (gogoproto.goproto_sizecache_all) = false;
option (gogoproto.goproto_unkeyed_all) = false;
option (gogoproto.goproto_unrecognized_all) = false;
option (gogoproto.marshaler_all) = true;
option (gogoproto.sizer_all) = true;
option (gogoproto.unmarshaler_all) = true;
option (rustproto.lite_runtime_all) = true;

// KeyspaceIdentity identifies a V3 tenant keyspace.
//
// For V3 tenant-scoped APIs, namespace_id must be non-zero and keyspace_id must
// satisfy 0 < keyspace_id < 2^24. Namespace 0 and keyspace 0 mean
// missing/invalid identity and must be rejected by V3 validators.
message KeyspaceIdentity {
uint32 namespace_id = 1;
uint32 keyspace_id = 2;
}
14 changes: 13 additions & 1 deletion proto/autoid.proto
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
syntax = "proto3";
package autoid;

import "apipb.proto";
import "gogoproto/gogo.proto";
import "rustproto.proto";

Expand All @@ -20,7 +21,12 @@ message AutoIDRequest {
uint64 n = 4;
int64 increment = 5;
int64 offset = 6;
uint32 keyspaceID = 7;
oneof keyspace {
// V1/V2 compatibility keyspace id. V3 should use keyspace_identity.
uint32 keyspaceID = 7;
// V3 keyspace identity.
apipb.KeyspaceIdentity keyspace_identity = 8;
}
}

message AutoIDResponse {
Expand All @@ -36,6 +42,12 @@ message RebaseRequest {
bool isUnsigned = 3;
int64 base = 4;
bool force = 5;
oneof keyspace {
// V1/V2 compatibility keyspace id. V3 should use keyspace_identity.
uint32 keyspaceID = 6;
// V3 keyspace identity.
apipb.KeyspaceIdentity keyspace_identity = 7;
}
}

message RebaseResponse {
Expand Down
9 changes: 9 additions & 0 deletions proto/cdcpb.proto
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,12 @@ message ResolvedTs {
uint64 request_id = 3;
}

enum ScanPriority {
SCAN_PRIORITY_UNKNOWN = 0;
SCAN_PRIORITY_LOW = 1;
SCAN_PRIORITY_HIGH = 2;
}

message ChangeDataRequest {
message Register {}

Expand Down Expand Up @@ -191,6 +197,9 @@ message ChangeDataRequest {

// Whether to filter out the value write by cdc itself.
bool filter_loop = 12;

// ScanPriority tells the CDC service how to schedule the initial scan.
ScanPriority scan_priority = 14;
}

service ChangeData {
Expand Down
40 changes: 40 additions & 0 deletions proto/coprocessor.proto
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,33 @@ message Request {
// (paging_size). The two fields target different scenarios and may be set
// independently.
uint64 paging_size_bytes = 17;
// Signals that the client can handle results of the batched tasks in `tasks`
// being merged into `Response.data` instead of each task returning its result
// in its own `StoreBatchTaskResponse.data`. Merging lets the store combine
// mergeable payloads, such as per-region ANALYZE sampling statistics, into
// one result, reducing the response size and the client's decode and merge
// work. See the batched ANALYZE design for the motivating use case:
// https://github.com/pingcap/tidb/pull/70355.
//
// For every merged task, the store still adds a `StoreBatchTaskResponse`
// with `data_merged_into_response` set. The store may return some or all task
// results separately even when this field is set, for example when a task
// fails, when its result is not mergeable, or when the store predates this
// field, so the client must handle both merged and per-task results.
//
// This field only negotiates the response shape. It does not affect task
// scheduling and may be set independently of `execute_batch_tasks_serially`.
bool allow_batch_task_data_merge = 18;
// When true, the store executes the primary task and all tasks in `tasks` one
// at a time, so at most one task of this request is running at any moment.
// Task execution order is not guaranteed.
//
// Clients that already bound their per-store concurrency by the number of
// in-flight requests, such as batched ANALYZE, set this so that batching more
// tasks into one request does not multiply that concurrency. The trade-off is
// a longer-lived request. This field only affects task scheduling and may be
// set independently of `allow_batch_task_data_merge`.
bool execute_batch_tasks_serially = 19;
}

message Response {
Expand Down Expand Up @@ -195,6 +222,19 @@ message StoreBatchTaskResponse {
string other_error = 4;
uint64 task_id = 5;
kvrpcpb.ExecDetailsV2 exec_details_v2 = 6;
// Indicates that this task's result was merged into the enclosing
// `Response.data`, so this message's `data` is empty. The store sets this
// field only when the client enables `Request.allow_batch_task_data_merge`,
// and only for a task that succeeded: a failed or non-mergeable task is
// returned as a normal per-task response with this field unset.
//
// Merging is atomic. If the store fails while merging, it returns no partial
// merged data and no response with this field set, so the client can safely
// retry the entire batch without losing or double-counting any task's result.
//
// This message still identifies the merged task by `task_id` and carries its
// execution details.
bool data_merged_into_response = 7;
}

message DelegateRequest {
Expand Down
7 changes: 6 additions & 1 deletion proto/disaggregated.proto
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
syntax = "proto3";
package disaggregated;

import "apipb.proto";
import "coprocessor.proto";
import "gogoproto/gogo.proto";
import "kvrpcpb.proto";
Expand Down Expand Up @@ -81,7 +82,11 @@ message DisaggTaskMeta {
uint64 local_query_id = 4; // unique local query_id if tidb don't restart.
int64 task_id = 5; // if task id is -1 , it indicates a tidb task.
string executor_id = 6; // the exectuor id
uint32 keyspace_id = 7; // keyspace id of the request
oneof keyspace {
uint32 keyspace_id = 7; // V1/V2 compatibility keyspace id of the request. V3 should use keyspace_identity.
// V3 keyspace identity of the request.
apipb.KeyspaceIdentity keyspace_identity = 12;
}
kvrpcpb.APIVersion api_version = 8; // API version of the request
uint64 connection_id = 10; // This is the session id between a client and tidb
string connection_alias = 11; // This is the session alias between a client and tidb
Expand Down
32 changes: 32 additions & 0 deletions proto/errorpb.proto
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,30 @@ message EpochNotMatch {
repeated metapb.Region current_regions = 1;
}

// Reasons for rejecting an incompatible transaction protocol request.
enum IncompatibleRequestReason {
IncompatibleRequestReasonUnknown = 0;
// The declared version is outside the compatible range returned in the error.
IncompatibleRequestReasonTxnProtocolVersionOutOfRange = 1;
}

// A transaction protocol compatibility rejection.
// The compatible range is inclusive: admission reports the store's global range;
// feature checks report [required feature version, store's maximum version].
message IncompatibleRequest {
IncompatibleRequestReason reason = 1;
// Diagnostic text; clients must use structured fields for control flow.
string message = 2;
// The request's declaration; missing and explicit zero both mean legacy.
uint32 provided_txn_protocol_version = 3;
uint32 min_compatible_txn_protocol_version = 4;
uint32 max_compatible_txn_protocol_version = 5;
}

// ServerIsBusy is the error variant that tells the server is too busy to response.
message ServerIsBusy {
// "txn_protocol_incompatible" is a legacy fallback for IncompatibleRequest,
// not an overload signal.
string reason = 1;
// The suggested backoff time
uint64 backoff_ms = 2;
Expand Down Expand Up @@ -214,4 +236,14 @@ message Error {

// UndeterminedResult is the error variant that tells the result is not determined yet.
UndeterminedResult undetermined_result = 22;

// A compatibility rejection with no usable business result.
// For a zero declaration, also set server_is_busy.reason to
// "txn_protocol_incompatible"; omit that fallback for nonzero declarations.
// Clients must handle this error before fallback or ordinary retry logic.
// Only client-c may reselect and resend when the reason is version out of range,
// the returned range is valid, and provided > max. The selected version must
// satisfy the request's requirements. Such admission rejections must have no
// transaction side effects. All other incompatibilities are terminal.
IncompatibleRequest incompatible_request = 23;
}
113 changes: 109 additions & 4 deletions proto/keyspacepb.proto
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
syntax = "proto3";
package keyspacepb;

import "apipb.proto";
import "gogoproto/gogo.proto";
import "pdpb.proto";
import "rustproto.proto";
Expand All @@ -14,9 +15,18 @@ option (gogoproto.sizer_all) = true;
option (gogoproto.unmarshaler_all) = true;
option (rustproto.lite_runtime_all) = true;

// Namespace provides services to manage namespaces.
service Namespace {
rpc CreateNamespace(CreateNamespaceRequest) returns (CreateNamespaceResponse) {}
rpc LoadNamespace(LoadNamespaceRequest) returns (LoadNamespaceResponse) {}
rpc GetAllNamespaces(GetAllNamespacesRequest) returns (GetAllNamespacesResponse) {}
rpc UpdateNamespaceState(UpdateNamespaceStateRequest) returns (UpdateNamespaceStateResponse) {}
}

// Keyspace provides services to manage keyspaces.
service Keyspace {
rpc LoadKeyspace(LoadKeyspaceRequest) returns (LoadKeyspaceResponse) {}
rpc LookupKeyspace(LookupKeyspaceRequest) returns (LookupKeyspaceResponse) {}
rpc LoadKeyspaceByID(LoadKeyspaceByIDRequest) returns (LoadKeyspaceResponse) {}
// WatchKeyspaces first return all current keyspaces' metadata as its first response.
// Then, it returns responses containing keyspaces that had their metadata changed.
Expand All @@ -26,7 +36,12 @@ service Keyspace {
}

message KeyspaceMeta {
uint32 id = 1;
oneof keyspace {
// V1/V2 compatibility keyspace id. V3 should read keyspace_identity instead.
uint32 id = 1;
// Canonical V3 keyspace identity.
apipb.KeyspaceIdentity keyspace_identity = 8;
}
string name = 2;
KeyspaceState state = 3;
int64 created_at = 4;
Expand All @@ -41,21 +56,99 @@ enum KeyspaceState {
TOMBSTONE = 3;
}

message NamespaceMeta {
uint32 id = 1;
string name = 2;
KeyspaceState state = 3;
int64 created_at = 4;
int64 state_changed_at = 5;
map<string, string> config = 7;
}

message NamespaceRef {
oneof namespace {
// API V3 namespace id.
uint32 namespace_id = 1;
// API V3 namespace name.
string namespace_name = 2;
}
}

message CreateNamespaceRequest {
pdpb.RequestHeader header = 1;
string name = 2;
map<string, string> config = 3;
}

message CreateNamespaceResponse {
pdpb.ResponseHeader header = 1;
NamespaceMeta namespace = 2;
}

message LoadNamespaceRequest {
pdpb.RequestHeader header = 1;
NamespaceRef namespace = 2;
}

message LoadNamespaceResponse {
pdpb.ResponseHeader header = 1;
NamespaceMeta namespace = 2;
}

message GetAllNamespacesRequest {
pdpb.RequestHeader header = 1;
uint32 start_id = 2;
uint32 limit = 3;
}

message GetAllNamespacesResponse {
pdpb.ResponseHeader header = 1;
repeated NamespaceMeta namespaces = 2;
}

message UpdateNamespaceStateRequest {
pdpb.RequestHeader header = 1;
NamespaceRef namespace = 2;
KeyspaceState state = 3;
}

message UpdateNamespaceStateResponse {
pdpb.ResponseHeader header = 1;
NamespaceMeta namespace = 2;
}

message LoadKeyspaceRequest {
pdpb.RequestHeader header = 1;
string name = 2;
// V3 namespace-scoped name lookup. If unset, V3 name-only lookup should use LookupKeyspace and may return multiple keyspaces.
NamespaceRef namespace = 3;
}

message LoadKeyspaceByIDRequest {
pdpb.RequestHeader header = 1;
uint32 id = 2;
oneof keyspace {
// V1/V2 compatibility keyspace id. V3 should use keyspace_identity.
uint32 id = 2;
// V3 keyspace identity.
apipb.KeyspaceIdentity keyspace_identity = 3;
}
}

message LoadKeyspaceResponse {
pdpb.ResponseHeader header = 1;
KeyspaceMeta keyspace = 2;
}

message LookupKeyspaceRequest {
pdpb.RequestHeader header = 1;
string name = 2;
}

message LookupKeyspaceResponse {
pdpb.ResponseHeader header = 1;
repeated KeyspaceMeta keyspaces = 2;
}

message WatchKeyspacesRequest {
pdpb.RequestHeader header = 1;
}
Expand All @@ -67,7 +160,12 @@ message WatchKeyspacesResponse {

message UpdateKeyspaceStateRequest {
pdpb.RequestHeader header = 1;
uint32 id = 2;
oneof keyspace {
// V1/V2 compatibility keyspace id. V3 should use keyspace_identity.
uint32 id = 2;
// V3 keyspace identity.
apipb.KeyspaceIdentity keyspace_identity = 4;
}
KeyspaceState state = 3;
}

Expand All @@ -78,8 +176,15 @@ message UpdateKeyspaceStateResponse {

message GetAllKeyspacesRequest {
pdpb.RequestHeader header = 1;
uint32 start_id = 2;
oneof start_keyspace {
// V1/V2 compatibility pagination cursor. V3 should use namespace_id and start_keyspace_identity.
uint32 start_id = 2;
// V3 pagination cursor within namespace_id.
apipb.KeyspaceIdentity start_keyspace_identity = 5;
}
uint32 limit = 3;
// V3 namespace-scoped pagination. Must be non-zero in V3.
NamespaceRef namespace = 4;
}

message GetAllKeyspacesResponse {
Expand Down
Loading
Loading