topodata.proto

// This file contains the Vitess topology related data structures.
// Very few of these structures are exchanged over the wire (only
// TabletType and KeyRange), but they are all used by the topology
// service.

syntax = "proto3";

option java_package="com.youtube.vitess.proto";

package topodata;

// KeyRange describes a range of sharding keys, when range-based
// sharding is used.
message KeyRange {
  bytes start = 1;
  bytes end = 2;
}

// KeyspaceIdType describes the type of the sharding key for a
// range-based sharded keyspace.
enum KeyspaceIdType {
  // UNSET is the default value, when range-based sharding is not used.
  UNSET = 0;

  // UINT64 is when uint64 value is used.
  // This is represented as 'unsigned bigint' in mysql
  UINT64 = 1;

  // BYTES is when an array of bytes is used.
  // This is represented as 'varbinary' in mysql
  BYTES = 2;
}

// TabletAlias is a globally unique tablet identifier.
message TabletAlias {
  // cell is the cell (or datacenter) the tablet is in
  string cell = 1;

  // uid is a unique id for this tablet within the shard
  // (this is the MySQL server id as well).
  uint32 uid = 2;
}

// TabletType represents the type of a given tablet.
enum TabletType {
  option allow_alias = true; // so we can have RDONLY and BATCH co-exist

  // UNKNOWN is not a valid value.
  UNKNOWN = 0;

  // MASTER is the master server for the shard. Only MASTER allows DMLs.
  MASTER = 1;

  // REPLICA is a slave type. It is used to serve live traffic.
  // A REPLICA can be promoted to MASTER. A demoted MASTER will go to REPLICA.
  REPLICA = 2;

  // RDONLY (old name) / BATCH (new name) is used to serve traffic for
  // long-running jobs. It is a separate type from REPLICA so
  // long-running queries don't affect web-like traffic.
  RDONLY = 3;
  BATCH = 3;

  // SPARE is a type of servers that cannot serve queries, but is available
  // in case an extra server is needed.
  SPARE = 4;

  // EXPERIMENTAL is like SPARE, except it can serve queries. This
  // type can be used for usages not planned by Vitess, like online
  // export to another storage engine.
  EXPERIMENTAL = 5;

  // BACKUP is the type a server goes to when taking a backup. No queries
  // can be served in BACKUP mode.
  BACKUP = 6;

  // RESTORE is the type a server uses when restoring a backup, at
  // startup time.  No queries can be served in RESTORE mode.
  RESTORE = 7;

  // DRAINED is the type a server goes into when used by Vitess tools
  // to perform an offline action. It is a serving type (as
  // the tools processes may need to run queries), but it's not used
  // to route queries from Vitess users. In this state,
  // this tablet is dedicated to the process that uses it.
  DRAINED = 8;
}

// Tablet represents information about a running instance of vttablet.
message Tablet {
  // alias is the unique name of the tablet.
  TabletAlias alias = 1;

  // Fully qualified domain name of the host.
  string hostname = 2;

  // IP address, stored as a string.
  string ip = 3;

  // Map of named ports. Normally this should include vt, grpc, and mysql.
  map<string, int32> port_map = 4;

  // Keyspace name.
  string keyspace = 5;

  // Shard name. If range based sharding is used, it should match
  // key_range.
  string shard = 6;

  // If range based sharding is used, range for the tablet's shard.
  KeyRange key_range = 7;

  // type is the current type of the tablet.
  TabletType type = 8;

  // It this is set, it is used as the database name instead of the
  // normal "vt_" + keyspace.
  string db_name_override = 9;

  // tablet tags
  map<string, string> tags = 10;

  // OBSOLETE: tablet health information
  // map<string, string> health_map = 11;
  reserved 11;
}

// A Shard contains data about a subset of the data whithin a keyspace.
message Shard {
  // master_alias is the tablet alias of the master for the shard.
  // If it is unset, then there is no master in this shard yet.

  // No lock is necessary to update this field, when for instance
  // TabletExternallyReparented updates this. However, we lock the
  // shard for reparenting operations (InitShardMaster,
  // PlannedReparentShard,EmergencyReparentShard), to guarantee
  // exclusive operation.
  TabletAlias master_alias = 1;

  // key_range is the KeyRange for this shard. It can be unset if:
  // - we are not using range-based sharding in this shard.
  // - the shard covers the entire keyrange.
  // This must match the shard name based on our other conventions, but
  // helpful to have it decomposed here.
  // Once set at creation time, it is never changed.
  KeyRange key_range = 2;

  // ServedType is an entry in the served_types
  message ServedType {
    TabletType tablet_type = 1;
    repeated string cells = 2;
  }

  // served_types has at most one entry per TabletType
  // The keyspace lock is always taken when changing this.
  repeated ServedType served_types = 3;

  // SourceShard represents a data source for filtered replication
  // accross shards. When this is used in a destination shard, the master
  // of that shard will run filtered replication.
  message SourceShard {
    // Uid is the unique ID for this SourceShard object.
    uint32 uid = 1;

    // the source keyspace
    string keyspace = 2;

    // the source shard
    string shard = 3;

    // the source shard keyrange
    KeyRange key_range = 4;

    // the source table list to replicate
    repeated string tables = 5;
  }

  // SourceShards is the list of shards we're replicating from,
  // using filtered replication.
  // The keyspace lock is always taken when changing this.
  repeated SourceShard source_shards = 4;

  // Cells is the list of cells that contain tablets for this shard.
  // No lock is necessary to update this field.
  repeated string cells = 5;

  // TabletControl controls tablet's behavior
  message TabletControl {
    // which tablet type is affected
    TabletType tablet_type = 1;
    repeated string cells = 2;

    // what to do
    bool disable_query_service = 3;
    repeated string blacklisted_tables = 4;
  }

  // tablet_controls has at most one entry per TabletType.
  // The keyspace lock is always taken when changing this.
  repeated TabletControl tablet_controls = 6;
}

// A Keyspace contains data about a keyspace.
message Keyspace {
  // name of the column used for sharding
  // empty if the keyspace is not sharded
  string sharding_column_name = 1;

  // type of the column used for sharding
  // UNSET if the keyspace is not sharded
  KeyspaceIdType sharding_column_type = 2;

  // OBSOLETE int32 split_shard_count = 3;
  reserved 3;

  // ServedFrom indicates a relationship between a TabletType and the
  // keyspace name that's serving it.
  message ServedFrom {
    // the tablet type (key for the map)
    TabletType tablet_type = 1;

    // the cells to limit this to
    repeated string cells = 2;

    // the keyspace name that's serving it
    string keyspace = 3;
  }

  // ServedFrom will redirect the appropriate traffic to
  // another keyspace.
  repeated ServedFrom served_froms = 4;
}

// ShardReplication describes the MySQL replication relationships
// whithin a cell.
message ShardReplication {

  // Node describes a tablet instance within the cell
  message Node {
    TabletAlias tablet_alias = 1;
  }

  // Note there can be only one Node in this array
  // for a given tablet.
  repeated Node nodes = 1;
}

// ShardReference is used as a pointer from a SrvKeyspace to a Shard
message ShardReference {
  // Copied from Shard.
  string name = 1;
  KeyRange key_range = 2;
}

// SrvKeyspace is a rollup node for the keyspace itself.
message SrvKeyspace {
  message KeyspacePartition {
    // The type this partition applies to.
    TabletType served_type = 1;

    // List of non-overlapping continuous shards sorted by range.
    repeated ShardReference shard_references = 2;
  }

  // The partitions this keyspace is serving, per tablet type.
  repeated KeyspacePartition partitions = 1;

  // ServedFrom indicates a relationship between a TabletType and the
  // keyspace name that's serving it.
  message ServedFrom {
    // the tablet type
    TabletType tablet_type = 1;

    // the keyspace name that's serving it
    string keyspace = 2;
  }

  // copied from Keyspace
  string sharding_column_name = 2;
  KeyspaceIdType sharding_column_type = 3;
  repeated ServedFrom served_from = 4;
  // OBSOLETE int32 split_shard_count = 5;
  reserved 5;
}