vitess-gh/proto/vtctlservice.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 package contains a service allowing you to use vtctld as a
// proxy for vt commands.

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

package vtctlservice;

import "vtctldata.proto";

// Service Vtctl allows you to call vt commands through gRPC.
service Vtctl {
  rpc ExecuteVtctlCommand (vtctldata.ExecuteVtctlCommandRequest) returns (stream vtctldata.ExecuteVtctlCommandResponse) {};
}

// Service Vtctld exposes gRPC endpoints for each vt command.
service Vtctld {
  // AddCellInfo registers a local topology service in a new cell by creating
  // the CellInfo with the provided parameters.
  rpc AddCellInfo(vtctldata.AddCellInfoRequest) returns (vtctldata.AddCellInfoResponse) {};
  // AddCellsAlias defines a group of cells that can be referenced by a single
  // name (the alias).
  //
  // When routing query traffic, replica/rdonly traffic can be routed across
  // cells within the group (alias). Only primary traffic can be routed across
  // cells not in the same group (alias).
  rpc AddCellsAlias(vtctldata.AddCellsAliasRequest) returns (vtctldata.AddCellsAliasResponse) {}; 
  // ApplyRoutingRules applies the VSchema routing rules.
  rpc ApplyRoutingRules(vtctldata.ApplyRoutingRulesRequest) returns (vtctldata.ApplyRoutingRulesResponse) {};
  // ApplyVSchema applies a vschema to a keyspace.
  rpc ApplyVSchema(vtctldata.ApplyVSchemaRequest) returns (vtctldata.ApplyVSchemaResponse) {};
  // ChangeTabletType changes the db type for the specified tablet, if possible.
  // This is used primarily to arrange replicas, and it will not convert a
  // primary. For that, use InitShardPrimary.
  //
  // NOTE: This command automatically updates the serving graph.
  rpc ChangeTabletType(vtctldata.ChangeTabletTypeRequest) returns (vtctldata.ChangeTabletTypeResponse) {};
  // CreateKeyspace creates the specified keyspace in the topology. For a
  // SNAPSHOT keyspace, the request must specify the name of a base keyspace,
  // as well as a snapshot time.
  rpc CreateKeyspace(vtctldata.CreateKeyspaceRequest) returns (vtctldata.CreateKeyspaceResponse) {};
  // CreateShard creates the specified shard in the topology.
  rpc CreateShard(vtctldata.CreateShardRequest) returns (vtctldata.CreateShardResponse) {};
  // DeleteCellInfo deletes the CellInfo for the provided cell. The cell cannot
  // be referenced by any Shard record in the topology.
  rpc DeleteCellInfo(vtctldata.DeleteCellInfoRequest) returns (vtctldata.DeleteCellInfoResponse) {};
  // DeleteCellsAlias deletes the CellsAlias for the provided alias.
  rpc DeleteCellsAlias(vtctldata.DeleteCellsAliasRequest) returns (vtctldata.DeleteCellsAliasResponse) {};
  // DeleteKeyspace deletes the specified keyspace from the topology. In
  // recursive mode, it also recursively deletes all shards in the keyspace.
  // Otherwise, the keyspace must be empty (have no shards), or DeleteKeyspace
  // returns an error.
  rpc DeleteKeyspace(vtctldata.DeleteKeyspaceRequest) returns (vtctldata.DeleteKeyspaceResponse) {};
  // DeleteShards deletes the specified shards from the topology. In recursive
  // mode, it also deletes all tablets belonging to the shard. Otherwise, the
  // shard must be empty (have no tablets) or DeleteShards returns an error for
  // that shard.
  rpc DeleteShards(vtctldata.DeleteShardsRequest) returns (vtctldata.DeleteShardsResponse) {};
  // DeleteTablets deletes one or more tablets from the topology.
  rpc DeleteTablets(vtctldata.DeleteTabletsRequest) returns (vtctldata.DeleteTabletsResponse) {};
  // EmergencyReparentShard reparents the shard to the new primary. It assumes
  // the old primary is dead or otherwise not responding.
  rpc EmergencyReparentShard(vtctldata.EmergencyReparentShardRequest) returns (vtctldata.EmergencyReparentShardResponse) {};
  // FindAllShardsInKeyspace returns a map of shard names to shard references
  // for a given keyspace.
  rpc FindAllShardsInKeyspace(vtctldata.FindAllShardsInKeyspaceRequest) returns (vtctldata.FindAllShardsInKeyspaceResponse) {};
  // GetBackups returns all the backups for a shard.
  rpc GetBackups(vtctldata.GetBackupsRequest) returns (vtctldata.GetBackupsResponse) {};
  // GetCellInfo returns the information for a cell.
  rpc GetCellInfo(vtctldata.GetCellInfoRequest) returns (vtctldata.GetCellInfoResponse) {};
  // GetCellInfoNames returns all the cells for which we have a CellInfo object,
  // meaning we have a topology service registered.
  rpc GetCellInfoNames(vtctldata.GetCellInfoNamesRequest) returns (vtctldata.GetCellInfoNamesResponse) {};
  // GetCellsAliases returns a mapping of cell alias to cells identified by that
  // alias.
  rpc GetCellsAliases(vtctldata.GetCellsAliasesRequest) returns (vtctldata.GetCellsAliasesResponse) {};
  // GetKeyspace reads the given keyspace from the topo and returns it.
  rpc GetKeyspace(vtctldata.GetKeyspaceRequest) returns (vtctldata.GetKeyspaceResponse) {};
  // GetKeyspaces returns the keyspace struct of all keyspaces in the topo.
  rpc GetKeyspaces(vtctldata.GetKeyspacesRequest) returns (vtctldata.GetKeyspacesResponse) {};
  // GetRoutingRules returns the VSchema routing rules.
  rpc GetRoutingRules(vtctldata.GetRoutingRulesRequest) returns (vtctldata.GetRoutingRulesResponse) {};
  // GetSchema returns the schema for a tablet, or just the schema for the
  // specified tables in that tablet.
  rpc GetSchema(vtctldata.GetSchemaRequest) returns (vtctldata.GetSchemaResponse) {};
  // GetShard returns information about a shard in the topology.
  rpc GetShard(vtctldata.GetShardRequest) returns (vtctldata.GetShardResponse) {};
  // GetSrvKeyspaces returns the SrvKeyspaces for a keyspace in one or more
  // cells.
  rpc GetSrvKeyspaces (vtctldata.GetSrvKeyspacesRequest) returns (vtctldata.GetSrvKeyspacesResponse) {};
  // GetSrvVSchema returns the SrvVSchema for a cell.
  rpc GetSrvVSchema(vtctldata.GetSrvVSchemaRequest) returns (vtctldata.GetSrvVSchemaResponse) {};
  // GetSrvVSchemas returns a mapping from cell name to SrvVSchema for all cells,
  // optionally filtered by cell name.
  rpc GetSrvVSchemas(vtctldata.GetSrvVSchemasRequest) returns (vtctldata.GetSrvVSchemasResponse) {};
  // GetTablet returns information about a tablet.
  rpc GetTablet(vtctldata.GetTabletRequest) returns (vtctldata.GetTabletResponse) {};
  // GetTablets returns tablets, optionally filtered by keyspace and shard.
  rpc GetTablets(vtctldata.GetTabletsRequest) returns (vtctldata.GetTabletsResponse) {};
  // GetVSchema returns the vschema for a keyspace.
  rpc GetVSchema(vtctldata.GetVSchemaRequest) returns (vtctldata.GetVSchemaResponse) {};
  // GetWorkflows returns a list of workflows for the given keyspace.
  rpc GetWorkflows(vtctldata.GetWorkflowsRequest) returns (vtctldata.GetWorkflowsResponse) {};
  // InitShardPrimary sets the initial primary for a shard. Will make all other
  // tablets in the shard replicas of the provided primary.
  //
  // WARNING: This could cause data loss on an already replicating shard.
  // PlannedReparentShard or EmergencyReparentShard should be used in those
  // cases instead.
  rpc InitShardPrimary(vtctldata.InitShardPrimaryRequest) returns (vtctldata.InitShardPrimaryResponse) {};
  // PlannedReparentShard reparents the shard to the new primary, or away from
  // an old primary. Both the old and new primaries need to be reachable and
  // running.
  //
  // **NOTE**: The vtctld will not consider any replicas outside the cell the
  // current shard primary is in for promotion unless NewPrimary is explicitly
  // provided in the request.
  rpc PlannedReparentShard(vtctldata.PlannedReparentShardRequest) returns (vtctldata.PlannedReparentShardResponse) {};
  // RebuildVSchemaGraph rebuilds the per-cell SrvVSchema from the global
  // VSchema objects in the provided cells (or all cells in the topo none
  // provided).
  rpc RebuildVSchemaGraph(vtctldata.RebuildVSchemaGraphRequest) returns (vtctldata.RebuildVSchemaGraphResponse) {};
  // RefreshState reloads the tablet record on the specified tablet.
  rpc RefreshState(vtctldata.RefreshStateRequest) returns (vtctldata.RefreshStateResponse) {};
  // RefreshStateByShard calls RefreshState on all the tablets in the given shard.
  rpc RefreshStateByShard(vtctldata.RefreshStateByShardRequest) returns (vtctldata.RefreshStateByShardResponse) {};
  // RemoveKeyspaceCell removes the specified cell from the Cells list for all
  // shards in the specified keyspace, as well as from the SrvKeyspace for that
  // keyspace in that cell.
  rpc RemoveKeyspaceCell(vtctldata.RemoveKeyspaceCellRequest) returns (vtctldata.RemoveKeyspaceCellResponse) {};
  // RemoveShardCell removes the specified cell from the specified shard's Cells
  // list.
  rpc RemoveShardCell(vtctldata.RemoveShardCellRequest) returns (vtctldata.RemoveShardCellResponse) {};
  // ReparentTablet reparents a tablet to the current primary in the shard. This
  // only works if the current replica position matches the last known reparent
  // action.
  rpc ReparentTablet(vtctldata.ReparentTabletRequest) returns (vtctldata.ReparentTabletResponse) {};
  // ShardReplicationPositions returns the replication position of each tablet
  // in a shard. This RPC makes a best-effort to return partial results. For
  // example, if one tablet in the shard graph is unreachable, then
  // ShardReplicationPositions will return non-error, and include valid results
  // for the reachable tablets.
  rpc ShardReplicationPositions(vtctldata.ShardReplicationPositionsRequest) returns (vtctldata.ShardReplicationPositionsResponse) {};
  // TabletExternallyReparented changes metadata in the topology server to
  // acknowledge a shard primary change performed by an external tool (e.g.
  // orchestrator).
  //
  // See the Reparenting guide for more information:
  // https://vitess.io/docs/user-guides/configuration-advanced/reparenting/#external-reparenting.
  rpc TabletExternallyReparented(vtctldata.TabletExternallyReparentedRequest) returns (vtctldata.TabletExternallyReparentedResponse) {};
  // UpdateCellInfo updates the content of a CellInfo with the provided
  // parameters. Empty values are ignored. If the cell does not exist, the
  // CellInfo will be created.
  rpc UpdateCellInfo(vtctldata.UpdateCellInfoRequest) returns (vtctldata.UpdateCellInfoResponse) {};
  // UpdateCellsAlias updates the content of a CellsAlias with the provided
  // parameters. Empty values are ignored. If the alias does not exist, the
  // CellsAlias will be created.
  rpc UpdateCellsAlias(vtctldata.UpdateCellsAliasRequest) returns (vtctldata.UpdateCellsAliasResponse) {};
}