vitess-gh/proto/binlogdata.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.
*/

// This file contains all the types and servers necessary to make
// RPC calls to VtTablet for the binlog protocol, used by filtered
// replication only.

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

package binlogdata;

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

// Charset is the per-statement charset info from a QUERY_EVENT binlog entry.
message Charset {
  // @@session.character_set_client
  int32 client = 1;
  // @@session.collation_connection
  int32 conn = 2;
  // @@session.collation_server
  int32 server = 3;
}

// BinlogTransaction describes a transaction inside the binlogs.
// It is streamed by vttablet for filtered replication, used during resharding.
message BinlogTransaction {
  message Statement {
    enum Category {
      BL_UNRECOGNIZED = 0;
      BL_BEGIN = 1;
      BL_COMMIT = 2;
      BL_ROLLBACK = 3;
      // BL_DML is deprecated.
      BL_DML_DEPRECATED = 4;
      BL_DDL = 5;
      BL_SET = 6;
      BL_INSERT = 7;
      BL_UPDATE = 8;
      BL_DELETE = 9;
    }

    // what type of statement is this?
    Category category = 1;

    // charset of this statement, if different from pre-negotiated default.
    Charset charset = 2;

    // the sql
    bytes sql = 3;
  }

  // the statements in this transaction
  repeated Statement statements = 1;

  // DEPRECATED (replaced by event_token): the timestamp of the statements.
  // int64 timestamp = 2;
  reserved 2;

  // DEPRECATED (replaced by event_token): the Transaction ID after
  // this statement was applied.
  // string transaction_id = 3;
  reserved 3;

  // The Event Token for this event.
  query.EventToken event_token = 4;
}

// StreamKeyRangeRequest is the payload to StreamKeyRange
message StreamKeyRangeRequest {
  // where to start
  string position = 1;

  // what to get
  topodata.KeyRange key_range = 2;

  // default charset on the player side
  Charset charset = 3;
}

// StreamKeyRangeResponse is the response from StreamKeyRange
message StreamKeyRangeResponse{
  BinlogTransaction binlog_transaction = 1;
}

// StreamTablesRequest is the payload to StreamTables
message StreamTablesRequest {
  // where to start
  string position = 1;

  // what to get
  repeated string tables = 2;

  // default charset on the player side
  Charset charset = 3;
}

// StreamTablesResponse is the response from StreamTables
message StreamTablesResponse {
  BinlogTransaction binlog_transaction = 1;
}

// Rule represents one rule.
message Rule {
  // match can be a table name or a regular expression
  // delineated by '/' and '/'.
  string match = 1;
  // filter can be an empty string or keyrange if the match
  // is a regular expression. Otherwise, it must be a select
  // query.
  string filter = 2;
}

// Filter represents a list of ordered rules. First match
// wins.
message Filter {
  repeated Rule rules = 1;
  enum FieldEventMode {
    ERR_ON_MISMATCH = 0;
    BEST_EFFORT = 1;
  }
  FieldEventMode fieldEventMode = 2;
}

// OnDDLAction lists the possible actions for DDLs.
enum OnDDLAction {
  IGNORE = 0;
  STOP = 1;
  EXEC = 2;
  EXEC_IGNORE = 3;
}

// BinlogSource specifies the source  and filter parameters for
// Filtered Replication. It currently supports a keyrange
// or a list of tables.
message BinlogSource {
  // the source keyspace
  string keyspace = 1;

  // the source shard
  string shard = 2;

  // the source tablet type
  topodata.TabletType tablet_type = 3;

  // key_range is set if the request is for a keyrange
  topodata.KeyRange key_range = 4;

  // tables is set if the request is for a list of tables
  repeated string tables = 5;

  // filter is set if we're using the generalized representation
  // for the filter.
  Filter filter = 6;

  // on_ddl specifies the action to be taken when a DDL is encountered.
  OnDDLAction on_ddl = 7;

  // Source is an external mysql. This attribute should be set to the username
  // to use in the connection
  string external_mysql = 8;
}

// VEventType enumerates the event types.
// This list is comprehensive. Many of these types
// will not be encountered in RBR mode.
enum VEventType {
  UNKNOWN = 0;
  GTID = 1;
  BEGIN = 2;
  COMMIT = 3;
  ROLLBACK = 4;
  DDL = 5;
  INSERT = 6;
  REPLACE = 7;
  UPDATE = 8;
  DELETE = 9;
  SET = 10;
  OTHER = 11;
  ROW = 12;
  FIELD = 13;
  HEARTBEAT = 14;
  VGTID = 15;
  JOURNAL = 16;
}

// RowChange represents one row change
message RowChange {
  query.Row before = 1;
  query.Row after = 2;
}

// RowEvent represent row events for one table
message RowEvent {
  string table_name = 1;
  repeated RowChange row_changes = 2;
}

message FieldEvent {
  string table_name = 1;
  repeated query.Field fields = 2;
}

message ShardGtid {
  string keyspace = 1;
  string shard = 2;
  string gtid = 3;
}

message VGtid {
  repeated ShardGtid shard_gtids = 1;
}

message KeyspaceShard {
  string keyspace = 1;
  string shard = 2;
}

// MigrationType specifies the type of migration for the Journal.
enum MigrationType {
  TABLES = 0;
  SHARDS = 1;
}

message Journal {
  int64 id = 1;
  MigrationType migration_type = 2;
  repeated string tables = 3;
  string local_position = 4;
  repeated ShardGtid shard_gtids = 5;
  repeated KeyspaceShard participants = 6;
  repeated string source_workflows = 7;
}

// VEvent represents a vstream event
message VEvent {
  VEventType type = 1;
  int64 timestamp = 2;
  string gtid = 3;
  string ddl = 4;
  RowEvent row_event = 5;
  FieldEvent field_event = 6;
  VGtid vgtid = 7;
  Journal journal = 8;
  string dml = 9;
  // current_time specifies the current time to handle clock skew.
  int64 current_time = 20;
}

// VStreamRequest is the payload for VStream
message VStreamRequest {
  vtrpc.CallerID effective_caller_id = 1;
  query.VTGateCallerID immediate_caller_id = 2;
  query.Target target = 3;

  string position = 4;
  Filter filter = 5;
}

// VStreamResponse is the response from VStream
message VStreamResponse {
  repeated VEvent events = 1;
}

// VStreamRowsRequest is the payload for VStreamRows
message VStreamRowsRequest {
  vtrpc.CallerID effective_caller_id = 1;
  query.VTGateCallerID immediate_caller_id = 2;
  query.Target target = 3;

  string query = 4;
  query.QueryResult lastpk = 5;
}

// VStreamRowsResponse is the response from VStreamRows
message VStreamRowsResponse {
  repeated query.Field fields = 1;
  repeated query.Field pkfields = 2;
  string gtid = 3;
  repeated query.Row rows = 4;
  query.Row lastpk = 5;
}

// VStreamResultsRequest is the payload for VStreamResults
// The ids match VStreamRows, in case we decide to merge the two.
message VStreamResultsRequest {
  vtrpc.CallerID effective_caller_id = 1;
  query.VTGateCallerID immediate_caller_id = 2;
  query.Target target = 3;

  string query = 4;
}

// VStreamResultsResponse is the response from VStreamResults
// The ids match VStreamRows, in case we decide to merge the two.
message VStreamResultsResponse {
  repeated query.Field fields = 1;
  string gtid = 3;
  repeated query.Row rows = 4;
}