vtgate.proto

/*
Copyright 2019 The Vitess Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

// Data definitions for service vtgateservice.

syntax = "proto3";
option go_package = "vitess.io/vitess/go/vt/proto/vtgate";

package vtgate;

option java_package = "io.vitess.proto";

import "binlogdata.proto";
import "query.proto";
import "topodata.proto";
import "vtrpc.proto";

// TransactionMode controls the execution of distributed transaction
// across multiple shards.
enum TransactionMode {
  // UNSPECIFIED uses the transaction mode set by the VTGate flag 'transaction_mode'.
  UNSPECIFIED = 0;
  // SINGLE disallows distributed transactions.
  SINGLE = 1;
  // MULTI allows distributed transactions with best effort commit.
  MULTI = 2;
  // TWOPC is for distributed transactions with atomic commits.
  TWOPC = 3;
}


// CommitOrder is used to designate which of the ShardSessions
// get used for transactions.
enum CommitOrder {
  // NORMAL is the default commit order.
  NORMAL = 0;
  // PRE is used to designate pre_sessions.
  PRE = 1;
  // POST is used to designate post_sessions.
  POST = 2;
  // AUTOCOMMIT is used to run the statement as autocommitted transaction.
  AUTOCOMMIT = 3;
}

// Session objects are exchanged like cookies through various
// calls to VTGate. The behavior differs between V2 & V3 APIs.
// V3 APIs are Execute, ExecuteBatch and StreamExecute. All
// other APIs are V2. For the V3 APIs, the session
// must be sent with every call to Execute or ExecuteBatch.
// For the V2 APIs, Begin does not accept a session. It instead
// returns a brand new one with in_transaction set to true.
// After a call to Commit or Rollback, the session can be
// discarded. If you're not in a transaction, Session is
// an optional parameter for the V2 APIs.
message Session {
  // in_transaction is set to true if the session is in a transaction.
  bool in_transaction = 1;

  message ShardSession {
    query.Target target = 1;
    int64 transaction_id = 2;
    topodata.TabletAlias tablet_alias = 3;
    // reserved connection if a dedicated connection is needed
    int64 reserved_id = 4;
    bool vindex_only = 5;
  }
  // shard_sessions keep track of per-shard transaction info.
  repeated ShardSession shard_sessions = 2;

  // single_db is deprecated. Use transaction_mode instead.
  reserved 3;

  // autocommit specifies if the session is in autocommit mode.
  // This is used only for V3.
  bool autocommit = 4;

  // target_string is the target expressed as a string. Valid
  // names are: keyspace:shard@target, keyspace@target or @target.
  // This is used only for V3.
  string target_string = 5;

  // options is used only for V3.
  query.ExecuteOptions options = 6;

  // transaction_mode specifies the current transaction mode.
  TransactionMode transaction_mode = 7;

  // warnings contains non-fatal warnings from the previous query
  repeated query.QueryWarning warnings = 8;

  // pre_sessions contains sessions that have to be committed first.
  repeated ShardSession pre_sessions = 9;

  // post_sessions contains sessions that have to be committed last.
  repeated ShardSession post_sessions = 10;

  // last_insert_id keeps track of the last seen insert_id for this session
  uint64 last_insert_id = 11;

  // found_rows keeps track of how many rows the last query returned
  uint64 found_rows = 12;

  // user_defined_variables contains all the @variables defined for this session
  map<string, query.BindVariable> user_defined_variables = 13;

  // system_variables keeps track of all session variables set for this connection
  // TODO: systay should we keep this so we can apply it ordered? 
  map<string, string> system_variables = 14;

  // row_count keeps track of the last seen rows affected for this session
  int64 row_count = 15;

  // Stores savepoint and release savepoint calls inside a transaction
  // and is reset once transaction is committed or rolled back.
  repeated string savepoints = 16;

  // in_reserved_conn is set to true if the session should be using reserved connections.
  bool in_reserved_conn = 17;

  // lock_session keep tracks of shard on which the lock query is sent.
  ShardSession lock_session = 18;

  // last_lock_heartbeat keep tracks of when last lock heartbeat was sent.
  int64 last_lock_heartbeat = 19;

  // read_after_write tracks the ReadAfterWrite settings for this session.
  ReadAfterWrite read_after_write = 20;

  // DDL strategy
  string DDLStrategy = 21;

  // Session UUID
  string SessionUUID = 22;

  // enable_system_settings defines if we can use reserved connections.
  bool enable_system_settings = 23;

  map<string, int64> advisory_lock = 24;

  // query_timeout is the maximum amount of time a query is permitted to run
  int64 query_timeout = 25;

  map<string, PrepareData> prepare_statement = 26;

  // MigrationContext
  string migration_context = 27;
}

// PrepareData keeps the prepared statement and other information related for execution of it.
message PrepareData {
  string prepare_statement = 1;
  int32 params_count = 2;
}

// ReadAfterWrite contains information regarding gtid set and timeout
// Also if the gtid information needs to be passed to client.
message ReadAfterWrite {
  string read_after_write_gtid = 1;
  double read_after_write_timeout = 2;
  bool session_track_gtids = 3;
}

// ExecuteRequest is the payload to Execute.
message ExecuteRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the session state.
  Session session = 2;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 3;

  // These values are deprecated. Use session instead.
  // topodata.TabletType tablet_type = 4;
  // string keyspace_shard = 6;
  // query.ExecuteOptions options = 7;
  // Deprecated: use session.in_transaction instead
  // bool not_in_transaction = 5;
  reserved 4, 5, 6, 7;
}

// ExecuteResponse is the returned value from Execute.
message ExecuteResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information.
  Session session = 2;

  // result contains the query result, only set if error is unset.
  query.QueryResult result = 3;
}

// ExecuteBatchRequest is the payload to ExecuteBatch.
message ExecuteBatchRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the session state.
  Session session = 2;

  // queries is a list of query and bind variables to execute.
  repeated query.BoundQuery queries = 3;

  // These values are deprecated. Use session instead.
  //  topodata.TabletType tablet_type = 4;
  //  bool as_transaction = 5;
  //  string keyspace_shard = 6;
  //  query.ExecuteOptions options = 7;
  reserved 4, 5, 6, 7;

}


// ExecuteBatchResponse is the returned value from ExecuteBatch.
message ExecuteBatchResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information.
  Session session = 2;

  // results contains the query results, only set if application level error is unset.
  repeated query.ResultWithError results = 3;
}

// StreamExecuteRequest is the payload to StreamExecute.
message StreamExecuteRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 2;

  // These values are deprecated. Use session instead.
  //  topodata.TabletType tablet_type = 3;
  //  string keyspace_shard = 4;
  //  query.ExecuteOptions options = 5;
  reserved 3,4,5;

  // session carries the session state.
  Session session = 6;
}

// StreamExecuteResponse is the returned value from StreamExecute.
// The session is currently not returned because StreamExecute is
// not expected to modify it.
message StreamExecuteResponse {
  // result contains the result data.
  // The first value contains only Fields information.
  // The next values contain the actual rows, a few values per result.
  query.QueryResult result = 1;

  // session is the updated session information.
  Session session = 2;
}

// ResolveTransactionRequest is the payload to ResolveTransaction.
message ResolveTransactionRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // dtid is the dtid of the transaction to be resolved.
  string dtid = 2;
}

// ResolveTransactionResponse is the returned value from Rollback.
message ResolveTransactionResponse {
}

message VStreamFlags {
  // align streams
  bool minimize_skew = 1;
  // how often heartbeats must be sent when idle (seconds)
  uint32 heartbeat_interval = 2;
  // stop streams on a reshard (journal event)
  bool stop_on_reshard = 3;
  // if specified, these cells (comma-separated) are used to pick source tablets from.
  // defaults to the cell of the vtgate serving the VStream API.
  string cells = 4;
  string cell_preference = 5;
  string tablet_order = 6;
  // When set, all new row events from the `heartbeat` table, for all shards, in the sidecardb will be streamed.
  bool stream_keyspace_heartbeats = 7;
}

// VStreamRequest is the payload for VStream.
message VStreamRequest {
  vtrpc.CallerID caller_id = 1;

  topodata.TabletType tablet_type = 2;

  // position specifies the starting point of the bin log positions
  // as well as the keyspace-shards to pull events from.
  // position is of the form 'ks1:0@MySQL56/<mysql_pos>|ks2:-80@MySQL56/<mysql_pos>'.
  binlogdata.VGtid vgtid = 3;
  binlogdata.Filter filter = 4;
  VStreamFlags flags = 5;
}

// VStreamResponse is streamed by VStream.
message VStreamResponse {
  repeated binlogdata.VEvent events = 1;
}

// PrepareRequest is the payload to Prepare.
message PrepareRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the session state.
  Session session = 2;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 3;
}

// PrepareResponse is the returned value from Prepare.
message PrepareResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information.
  Session session = 2;

  // fields contains the fields, only set if error is unset.
  repeated query.Field fields = 3;
}

// CloseSessionRequest is the payload to CloseSession.
message CloseSessionRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the session state.
  Session session = 2;
}

// CloseSessionResponse is the returned value from CloseSession.
message CloseSessionResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;
}