Skip to content

vtctlReference.md

Latest commit

 

History

History
2133 lines (1201 loc) · 100 KB

vtctlReference.md

File metadata and controls

2133 lines (1201 loc) · 100 KB
Raw

This reference guide explains the commands that the vtctl tool supports. vtctl is a command-line tool used to administer a Vitess cluster, and it allows a human or application to easily interact with a Vitess implementation.

Commands are listed in the following groups:

Generic

ListAllTablets

Lists all tablets in an awk-friendly way.

Example

ListAllTablets <cell name>

Arguments

  • <cell name> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.

Errors

  • The <cell name> argument is required for the <ListAllTablets> command. This error occurs if the command is not called with exactly one argument.

ListTablets

Lists specified tablets in an awk-friendly way.

Example

ListTablets <tablet alias> ...

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space.

Errors

  • The <tablet alias> argument is required for the <ListTablets> command. This error occurs if the command is not called with at least one argument.

PruneActionLogs

(requires zktopo.Server)

e.g. PruneActionLogs -keep-count=10 /zk/global/vt/keyspaces/my_keyspace/shards/0/actionlog

Removes older actionlog entries until at most <count to keep> are left.

Example

PruneActionLogs [-keep-count=<count to keep>] <zk actionlog path> ...

Flags

Name Type Definition
keep-count Int count to keep

Arguments

  • <zk actionlog path> – Required. To specify multiple values for this argument, separate individual values with a space.

Errors

  • action <PruneActionLogs> requires <zk action log path> [...] This error occurs if the command is not called with at least one argument.
  • <PruneActionLogs> requires a zktopo.Server
  • some errors occurred, check the log

Validate

Validates that all nodes reachable from the global replication graph and that all tablets in all discoverable cells are consistent.

Example

Validate [-ping-tablets]

Flags

Name Type Definition
ping-tablets Boolean Indicates whether all tablets should be pinged during the validation process

Keyspaces

CreateKeyspace

Creates the specified keyspace.

Example

CreateKeyspace [-sharding_column_name=name] [-sharding_column_type=type] [-served_from=tablettype1:ks1,tablettype2,ks2,...] [-force] <keyspace name>

Flags

Name Type Definition
force Boolean Proceeds even if the keyspace already exists
served_from string Specifies a comma-separated list of dbtype:keyspace pairs used to serve traffic
sharding_column_name string Specifies the column to use for sharding operations
sharding_column_type string Specifies the type of the column to use for sharding operations

Arguments

  • <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <keyspace name> argument is required for the <CreateKeyspace> command. This error occurs if the command is not called with exactly one argument.

DeleteKeyspace

Deletes the specified keyspace. In recursive mode, it also recursively deletes all shards in the keyspace. Otherwise, there must be no shards left in the keyspace.

Example

DeleteKeyspace [-recursive] <keyspace>

Flags

Name Type Definition
recursive Boolean Also recursively delete all shards in the keyspace.

Arguments

  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • Must specify the <keyspace> argument for <DeleteKeyspace>. This error occurs if the command is not called with exactly one argument.

FindAllShardsInKeyspace

Displays all of the shards in the specified keyspace.

Example

FindAllShardsInKeyspace <keyspace>

Arguments

  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <keyspace> argument is required for the <FindAllShardsInKeyspace> command. This error occurs if the command is not called with exactly one argument.

GetKeyspace

Outputs a JSON structure that contains information about the Keyspace.

Example

GetKeyspace <keyspace>

Arguments

  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <keyspace> argument is required for the <GetKeyspace> command. This error occurs if the command is not called with exactly one argument.

GetKeyspaces

Outputs a sorted list of all keyspaces.

MigrateServedFrom

Makes the <destination keyspace/shard> serve the given type. This command also rebuilds the serving graph.

Example

MigrateServedFrom [-cells=c1,c2,...] [-reverse] <destination keyspace/shard> <served tablet type>

Flags

Name Type Definition
cells string Specifies a comma-separated list of cells to update
filtered_replication_wait_time Duration Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations
reverse Boolean Moves the served tablet type backward instead of forward. Use in case of trouble

Arguments

  • <destination keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

  • <served tablet type> – Required. The vttablet's role. Valid values are:

    • backup – A slaved copy of data that is offline to queries other than for backup purposes
    • batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
    • experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
    • master – A primary copy of data
    • rdonly – A slaved copy of data for OLAP load patterns
    • replica – A slaved copy of data ready to be promoted to master
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
    • snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
      vtctl Snapshot -server-mode ...
      Use this command to exit this mode: 
      vtctl SnapshotSourceEnd ...
    • spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
    • worker – A tablet that is in use by a vtworker process. The tablet is likely lagging in replication.

Errors

  • The <destination keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedFrom> command. This error occurs if the command is not called with exactly 2 arguments.

MigrateServedTypes

Migrates a serving type from the source shard to the shards that it replicates to. This command also rebuilds the serving graph. The <keyspace/shard> argument can specify any of the shards involved in the migration.

Example

MigrateServedTypes [-cells=c1,c2,...] [-reverse] [-skip-refresh-state] <keyspace/shard> <served tablet type>

Flags

Name Type Definition
cells string Specifies a comma-separated list of cells to update
filtered_replication_wait_time Duration Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations
reverse Boolean Moves the served tablet type backward instead of forward. Use in case of trouble
skip-refresh-state Boolean Skips refreshing the state of the source tablets after the migration, meaning that the refresh will need to be done manually, replica and rdonly only)

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

  • <served tablet type> – Required. The vttablet's role. Valid values are:

    • backup – A slaved copy of data that is offline to queries other than for backup purposes
    • batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
    • experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
    • master – A primary copy of data
    • rdonly – A slaved copy of data for OLAP load patterns
    • replica – A slaved copy of data ready to be promoted to master
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
    • snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
      vtctl Snapshot -server-mode ...
      Use this command to exit this mode: 
      vtctl SnapshotSourceEnd ...
    • spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
    • worker – A tablet that is in use by a vtworker process. The tablet is likely lagging in replication.

Errors

  • The <source keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedTypes> command. This error occurs if the command is not called with exactly 2 arguments.
  • The <skip-refresh-state> flag can only be specified for non-master migrations.

RebuildKeyspaceGraph

Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients.

Example

RebuildKeyspaceGraph [-cells=c1,c2,...] <keyspace> ...

Flags

Name Type Definition
cells string Specifies a comma-separated list of cells to update

Arguments

  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. To specify multiple values for this argument, separate individual values with a space.

Errors

  • The <keyspace> argument must be used to specify at least one keyspace when calling the <RebuildKeyspaceGraph> command. This error occurs if the command is not called with at least one argument.

RemoveKeyspaceCell

Removes the cell from the Cells list for all shards in the keyspace.

Example

RemoveKeyspaceCell [-force] [-recursive] <keyspace> <cell>

Flags

Name Type Definition
force Boolean Proceeds even if the cell's topology server cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data.
recursive Boolean Also delete all tablets in that cell belonging to the specified keyspace.

Arguments

  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
  • <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.

Errors

  • The <keyspace> and <cell> arguments are required for the <RemoveKeyspaceCell> command. This error occurs if the command is not called with exactly 2 arguments.

SetKeyspaceServedFrom

Changes the ServedFromMap manually. This command is intended for emergency fixes. This field is automatically set when you call the MigrateServedFrom command. This command does not rebuild the serving graph.

Example

SetKeyspaceServedFrom [-source=<source keyspace name>] [-remove] [-cells=c1,c2,...] <keyspace name> <tablet type>

Flags

Name Type Definition
cells string Specifies a comma-separated list of cells to affect
remove Boolean Indicates whether to add (default) or remove the served from record
source string Specifies the source keyspace name

Arguments

  • <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

  • <tablet type> – Required. The vttablet's role. Valid values are:

    • backup – A slaved copy of data that is offline to queries other than for backup purposes
    • batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
    • experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
    • master – A primary copy of data
    • rdonly – A slaved copy of data for OLAP load patterns
    • replica – A slaved copy of data ready to be promoted to master
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
    • snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
      vtctl Snapshot -server-mode ...
      Use this command to exit this mode: 
      vtctl SnapshotSourceEnd ...
    • spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
    • worker – A tablet that is in use by a vtworker process. The tablet is likely lagging in replication.

Errors

  • The <keyspace name> and <tablet type> arguments are required for the <SetKeyspaceServedFrom> command. This error occurs if the command is not called with exactly 2 arguments.

SetKeyspaceShardingInfo

Updates the sharding information for a keyspace.

Example

SetKeyspaceShardingInfo [-force] <keyspace name> [<column name>] [<column type>]

Flags

Name Type Definition
force Boolean Updates fields even if they are already set. Use caution before calling this command.

Arguments

  • <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
  • <column name> – Optional.
  • <column type> – Optional.

Errors

  • The <keyspace name> argument is required for the <SetKeyspaceShardingInfo> command. The <column name> and <column type> arguments are both optional. This error occurs if the command is not called with between 1 and 3 arguments.
  • Both <column name> and <column type> must be set, or both must be unset.

ValidateKeyspace

Validates that all nodes reachable from the specified keyspace are consistent.

Example

ValidateKeyspace [-ping-tablets] <keyspace name>

Flags

Name Type Definition
ping-tablets Boolean Specifies whether all tablets will be pinged during the validation process

Arguments

  • <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <keyspace name> argument is required for the <ValidateKeyspace> command. This error occurs if the command is not called with exactly one argument.

WaitForDrain

Blocks until no new queries were observed on all tablets with the given tablet type in the specifed keyspace. This can be used as sanity check to ensure that the tablets were drained after running vtctl MigrateServedTypes and vtgate is no longer using them. If -timeout is set, it fails when the timeout is reached.

Example

WaitForDrain [-timeout <duration>] <keyspace/shard> <served tablet type>

Flags

Name Type Definition
cells string Specifies a comma-separated list of cells to look for tablets
retry_delay Duration Time to wait between two checks
timeout Duration Timeout after which the command fails

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

  • <served tablet type> – Required. The vttablet's role. Valid values are:

    • backup – A slaved copy of data that is offline to queries other than for backup purposes
    • batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
    • experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
    • master – A primary copy of data
    • rdonly – A slaved copy of data for OLAP load patterns
    • replica – A slaved copy of data ready to be promoted to master
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
    • snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
      vtctl Snapshot -server-mode ...
      Use this command to exit this mode: 
      vtctl SnapshotSourceEnd ...
    • spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
    • worker – A tablet that is in use by a vtworker process. The tablet is likely lagging in replication.

Errors

  • The <keyspace/shard> and <tablet type> arguments are both required for the <WaitForDrain> command. This error occurs if the command is not called with exactly 2 arguments.

Queries

VtGateExecute

Executes the given SQL query with the provided bound variables against the vtgate server.

Example

VtGateExecute -server <vtgate> [-bind_variables <JSON map>] [-connect_timeout <connect timeout>] [-keyspace <default keyspace>] [-tablet_type <tablet type>] [-json] <sql>

Flags

Name Type Definition
connect_timeout Duration Connection timeout for vtgate client
json Boolean Output JSON instead of human-readable table
keyspace string default keyspace to use
server string VtGate server to connect to
tablet_type string tablet type to query

Arguments

  • <vtgate> – Required.
  • <sql> – Required.

Errors

  • the <sql> argument is required for the <VtGateExecute> command This error occurs if the command is not called with exactly one argument.
  • error connecting to vtgate '%v': %v
  • Execute failed: %v

VtGateExecuteKeyspaceIds

Executes the given SQL query with the provided bound variables against the vtgate server. It is routed to the shards that contain the provided keyspace ids.

Example

VtGateExecuteKeyspaceIds -server <vtgate> -keyspace <keyspace> -keyspace_ids <ks1 in hex>,<k2 in hex>,... [-bind_variables <JSON map>] [-connect_timeout <connect timeout>] [-tablet_type <tablet type>] [-json] <sql>

Flags

Name Type Definition
connect_timeout Duration Connection timeout for vtgate client
json Boolean Output JSON instead of human-readable table
keyspace string keyspace to send query to
keyspace_ids string comma-separated list of keyspace ids (in hex) that will map into shards to send query to
server string VtGate server to connect to
tablet_type string tablet type to query

Arguments

  • <vtgate> – Required.
  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
  • <ks1 in hex> – Required. To specify multiple values for this argument, separate individual values with a comma.
  • <sql> – Required.

Errors

  • the <sql> argument is required for the <VtGateExecuteKeyspaceIds> command This error occurs if the command is not called with exactly one argument.
  • cannot hex-decode value %v '%v': %v
  • error connecting to vtgate '%v': %v
  • Execute failed: %v

VtGateExecuteShards

Executes the given SQL query with the provided bound variables against the vtgate server. It is routed to the provided shards.

Example

VtGateExecuteShards -server <vtgate> -keyspace <keyspace> -shards <shard0>,<shard1>,... [-bind_variables <JSON map>] [-connect_timeout <connect timeout>] [-tablet_type <tablet type>] [-json] <sql>

Flags

Name Type Definition
connect_timeout Duration Connection timeout for vtgate client
json Boolean Output JSON instead of human-readable table
keyspace string keyspace to send query to
server string VtGate server to connect to
shards string comma-separated list of shards to send query to
tablet_type string tablet type to query

Arguments

  • <vtgate> – Required.
  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
  • <shard> – Required. The name of a shard. The argument value is typically in the format <range start>-<range end>. To specify multiple values for this argument, separate individual values with a comma.
  • <sql> – Required.

Errors

  • the <sql> argument is required for the <VtGateExecuteShards> command This error occurs if the command is not called with exactly one argument.
  • error connecting to vtgate '%v': %v
  • Execute failed: %v

VtGateSplitQuery

Executes the SplitQuery computation for the given SQL query with the provided bound variables against the vtgate server (this is the base query for Map-Reduce workloads, and is provided here for debug / test purposes).

Example

VtGateSplitQuery -server <vtgate> -keyspace <keyspace> [-split_column <split_column>] -split_count <split_count> [-bind_variables <JSON map>] [-connect_timeout <connect timeout>] <sql>

Flags

Name Type Definition
connect_timeout Duration Connection timeout for vtgate client
keyspace string keyspace to send query to
server string VtGate server to connect to
split_column string force the use of this column to split the query
split_count Int number of splits to generate

Arguments

  • <vtgate> – Required.
  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
  • <split_count> – Required.
  • <sql> – Required.

Errors

  • the <sql> argument is required for the <VtGateSplitQuery> command This error occurs if the command is not called with exactly one argument.
  • error connecting to vtgate '%v': %v
  • SplitQuery failed: %v

VtTabletBegin

Starts a transaction on the provided server.

Example

VtTabletBegin [-connect_timeout <connect timeout>] [-tablet_type <tablet_type>] -keyspace <keyspace> -shard <shard> <tablet alias>

Flags

Name Type Definition
connect_timeout Duration Connection timeout for vttablet client

Arguments

  • <connect timeout> – Required.
  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
  • <shard> – Required. The name of a shard. The argument value is typically in the format <range start>-<range end>.
  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • the <tablet_alias> argument is required for the <VtTabletBegin> command This error occurs if the command is not called with exactly one argument.
  • cannot connect to tablet %v: %v
  • Begin failed: %v

VtTabletCommit

Commits a transaction on the provided server.

Example

VtTabletCommit [-connect_timeout <connect timeout>] [-tablet_type <tablet_type>] -keyspace <keyspace> -shard <shard> <tablet alias> <transaction_id>

Flags

Name Type Definition
connect_timeout Duration Connection timeout for vttablet client

Arguments

  • <connect timeout> – Required.
  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
  • <shard> – Required. The name of a shard. The argument value is typically in the format <range start>-<range end>.
  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
  • <transaction_id> – Required.

Errors

  • the <tablet_alias> and <transaction_id> arguments are required for the <VtTabletCommit> command This error occurs if the command is not called with exactly 2 arguments.
  • cannot connect to tablet %v: %v

VtTabletExecute

Executes the given query on the given tablet.

Example

VtTabletExecute [-bind_variables <JSON map>] [-connect_timeout <connect timeout>] [-transaction_id <transaction_id>] [-tablet_type <tablet_type>] [-json] -keyspace <keyspace> -shard <shard> <tablet alias> <sql>

Flags

Name Type Definition
connect_timeout Duration Connection timeout for vttablet client
json Boolean Output JSON instead of human-readable table
transaction_id Int transaction id to use, if inside a transaction.

Arguments

  • <JSON map> – Required.
  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
  • <shard> – Required. The name of a shard. The argument value is typically in the format <range start>-<range end>.
  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
  • <sql> – Required.

Errors

  • the <tablet_alias> and <sql> arguments are required for the <VtTabletExecute> command This error occurs if the command is not called with exactly 2 arguments.
  • cannot connect to tablet %v: %v
  • Execute failed: %v

VtTabletRollback

Rollbacks a transaction on the provided server.

Example

VtTabletRollback [-connect_timeout <connect timeout>] [-tablet_type <tablet_type>] -keyspace <keyspace> -shard <shard> <tablet alias> <transaction_id>

Flags

Name Type Definition
connect_timeout Duration Connection timeout for vttablet client

Arguments

  • <connect timeout> – Required.
  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
  • <shard> – Required. The name of a shard. The argument value is typically in the format <range start>-<range end>.
  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
  • <transaction_id> – Required.

Errors

  • the <tablet_alias> and <transaction_id> arguments are required for the <VtTabletRollback> command This error occurs if the command is not called with exactly 2 arguments.
  • cannot connect to tablet %v: %v

VtTabletStreamHealth

Executes the StreamHealth streaming query to a vttablet process. Will stop after getting <count> answers.

Example

VtTabletStreamHealth [-count <count, default 1>] [-connect_timeout <connect timeout>] <tablet alias>

Flags

Name Type Definition
connect_timeout Duration Connection timeout for vttablet client
count Int number of responses to wait for

Arguments

  • <count default 1> – Required.
  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <VtTabletStreamHealth> command. This error occurs if the command is not called with exactly one argument.
  • cannot connect to tablet %v: %v
  • stream ended early: %v

Replication Graph

GetShardReplication

Outputs a JSON structure that contains information about the ShardReplication.

Example

GetShardReplication <cell> <keyspace/shard>

Arguments

  • <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <cell> and <keyspace/shard> arguments are required for the <GetShardReplication> command. This error occurs if the command is not called with exactly 2 arguments.

Resharding Throttler

ThrottlerMaxRates

Returns the current max rate of all active resharding throttlers on the server.

Example

ThrottlerMaxRates -server <vtworker or vttablet>

Flags

Name Type Definition
server string vtworker or vttablet to connect to

Arguments

  • <vtworker or vttablet> – Required.

Errors

  • the ThrottlerSetMaxRate command does not accept any positional parameters This error occurs if the command is not called with exactly 0 arguments.
  • error creating a throttler client for <server> '%v': %v
  • failed to get the throttler rate from <server> '%v': %v

ThrottlerSetMaxRate

Sets the max rate for all active resharding throttlers on the server.

Example

ThrottlerSetMaxRate -server <vtworker or vttablet> <rate>

Flags

Name Type Definition
server string vtworker or vttablet to connect to

Arguments

  • <vtworker or vttablet> – Required.
  • <rate> – Required.

Errors

  • the <rate> argument is required for the <ThrottlerSetMaxRate> command This error occurs if the command is not called with exactly one argument.
  • failed to parse rate '%v' as integer value: %v
  • error creating a throttler client for <server> '%v': %v
  • failed to set the throttler rate on <server> '%v': %v

Schema, Version, Permissions

ApplySchema

Applies the schema change to the specified keyspace on every master, running in parallel on all shards. The changes are then propagated to slaves via replication. If -allow_long_unavailability is set, schema changes affecting a large number of rows (and possibly incurring a longer period of unavailability) will not be rejected.

Example

ApplySchema [-allow_long_unavailability] [-wait_slave_timeout=10s] {-sql=<sql> || -sql-file=<filename>} <keyspace>

Flags

Name Type Definition
allow_long_unavailability Boolean Allow large schema changes which incur a longer unavailability of the database.
sql string A list of semicolon-delimited SQL commands
sql-file string Identifies the file that contains the SQL commands
wait_slave_timeout Duration The amount of time to wait for slaves to receive the schema change via replication.

Arguments

  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <keyspace> argument is required for the command<ApplySchema> command. This error occurs if the command is not called with exactly one argument.

ApplyVSchema

Applies the VTGate routing schema to the provided keyspace. Shows the result after application.

Example

ApplyVSchema {-vschema=<vschema> || -vschema_file=<vschema file>} [-cells=c1,c2,...] [-skip_rebuild] <keyspace>

Flags

Name Type Definition
cells string If specified, limits the rebuild to the cells, after upload. Ignored if skipRebuild is set.
skip_rebuild Boolean If set, do no rebuild the SrvSchema objects.
vschema string Identifies the VTGate routing schema
vschema_file string Identifies the VTGate routing schema file

Arguments

  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <keyspace> argument is required for the <ApplyVSchema> command. This error occurs if the command is not called with exactly one argument.
  • Either the <vschema> or <vschema>File flag must be specified when calling the <ApplyVSchema> command.

CopySchemaShard

Copies the schema from a source shard's master (or a specific tablet) to a destination shard. The schema is applied directly on the master of the destination shard, and it is propagated to the replicas through binlogs.

Example

CopySchemaShard [-tables=<table1>,<table2>,...] [-exclude_tables=<table1>,<table2>,...] [-include-views] [-wait_slave_timeout=10s] {<source keyspace/shard> || <source tablet alias>} <destination keyspace/shard>

Flags

Name Type Definition
exclude_tables string Specifies a comma-separated list of regular expressions for which tables to exclude
include-views Boolean Includes views in the output
tables string Specifies a comma-separated list of regular expressions for which tables gather schema information for
wait_slave_timeout Duration The amount of time to wait for slaves to receive the schema change via replication.

Arguments

  • <source tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
  • <destination keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <source keyspace/shard> and <destination keyspace/shard> arguments are both required for the <CopySchemaShard> command. Instead of the <source keyspace/shard> argument, you can also specify <tablet alias> which refers to a specific tablet of the shard in the source keyspace. This error occurs if the command is not called with exactly 2 arguments.

GetPermissions

Displays the permissions for a tablet.

Example

GetPermissions <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <GetPermissions> command. This error occurs if the command is not called with exactly one argument.

GetSchema

Displays the full schema for a tablet, or just the schema for the specified tables in that tablet.

Example

GetSchema [-tables=<table1>,<table2>,...] [-exclude_tables=<table1>,<table2>,...] [-include-views] <tablet alias>

Flags

Name Type Definition
exclude_tables string Specifies a comma-separated list of regular expressions for tables to exclude
include-views Boolean Includes views in the output
table_names_only Boolean Only displays table names that match
tables string Specifies a comma-separated list of regular expressions for which tables should gather information

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <GetSchema> command. This error occurs if the command is not called with exactly one argument.

GetVSchema

Displays the VTGate routing schema.

Example

GetVSchema <keyspace>

Arguments

  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <keyspace> argument is required for the <GetVSchema> command. This error occurs if the command is not called with exactly one argument.

RebuildVSchemaGraph

Rebuilds the cell-specific SrvVSchema from the global VSchema objects in the provided cells (or all cells if none provided).

Example

RebuildVSchemaGraph [-cells=c1,c2,...]

Flags

Name Type Definition
cells string Specifies a comma-separated list of cells to look for tablets

Errors

  • <RebuildVSchemaGraph> doesn't take any arguments. This error occurs if the command is not called with exactly 0 arguments.

ReloadSchema

Reloads the schema on a remote tablet.

Example

ReloadSchema <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <ReloadSchema> command. This error occurs if the command is not called with exactly one argument.

ValidatePermissionsKeyspace

Validates that the master permissions from shard 0 match those of all of the other tablets in the keyspace.

Example

ValidatePermissionsKeyspace <keyspace name>

Arguments

  • <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <keyspace name> argument is required for the <ValidatePermissionsKeyspace> command. This error occurs if the command is not called with exactly one argument.

ValidatePermissionsShard

Validates that the master permissions match all the slaves.

Example

ValidatePermissionsShard <keyspace/shard>

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <keyspace/shard> argument is required for the <ValidatePermissionsShard> command. This error occurs if the command is not called with exactly one argument.

ValidateSchemaKeyspace

Validates that the master schema from shard 0 matches the schema on all of the other tablets in the keyspace.

Example

ValidateSchemaKeyspace [-exclude_tables=''] [-include-views] <keyspace name>

Flags

Name Type Definition
exclude_tables string Specifies a comma-separated list of regular expressions for tables to exclude
include-views Boolean Includes views in the validation

Arguments

  • <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <keyspace name> argument is required for the <ValidateSchemaKeyspace> command. This error occurs if the command is not called with exactly one argument.

ValidateSchemaShard

Validates that the master schema matches all of the slaves.

Example

ValidateSchemaShard [-exclude_tables=''] [-include-views] <keyspace/shard>

Flags

Name Type Definition
exclude_tables string Specifies a comma-separated list of regular expressions for tables to exclude
include-views Boolean Includes views in the validation

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <keyspace/shard> argument is required for the <ValidateSchemaShard> command. This error occurs if the command is not called with exactly one argument.

ValidateVersionKeyspace

Validates that the master version from shard 0 matches all of the other tablets in the keyspace.

Example

ValidateVersionKeyspace <keyspace name>

Arguments

  • <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <keyspace name> argument is required for the <ValidateVersionKeyspace> command. This error occurs if the command is not called with exactly one argument.

ValidateVersionShard

Validates that the master version matches all of the slaves.

Example

ValidateVersionShard <keyspace/shard>

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <keyspace/shard> argument is requird for the <ValidateVersionShard> command. This error occurs if the command is not called with exactly one argument.

Serving Graph

GetSrvKeyspace

Outputs a JSON structure that contains information about the SrvKeyspace.

Example

GetSrvKeyspace <cell> <keyspace>

Arguments

  • <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
  • <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.

Errors

  • The <cell> and <keyspace> arguments are required for the <GetSrvKeyspace> command. This error occurs if the command is not called with exactly 2 arguments.

GetSrvKeyspaceNames

Outputs a list of keyspace names.

Example

GetSrvKeyspaceNames <cell>

Arguments

  • <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.

Errors

  • The <cell> argument is required for the <GetSrvKeyspaceNames> command. This error occurs if the command is not called with exactly one argument.

GetSrvVSchema

Outputs a JSON structure that contains information about the SrvVSchema.

Example

GetSrvVSchema <cell>

Arguments

  • <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.

Errors

  • The <cell> argument is required for the <GetSrvVSchema> command. This error occurs if the command is not called with exactly one argument.

Shards

CreateShard

Creates the specified shard.

Example

CreateShard [-force] [-parent] <keyspace/shard>

Flags

Name Type Definition
force Boolean Proceeds with the command even if the keyspace already exists
parent Boolean Creates the parent keyspace if it doesn't already exist

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <keyspace/shard> argument is required for the <CreateShard> command. This error occurs if the command is not called with exactly one argument.

DeleteShard

Deletes the specified shard(s). In recursive mode, it also deletes all tablets belonging to the shard. Otherwise, there must be no tablets left in the shard.

Example

DeleteShard [-recursive] <keyspace/shard> ...

Flags

Name Type Definition
recursive Boolean Also delete all tablets belonging to the shard.

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>. To specify multiple values for this argument, separate individual values with a space.

Errors

  • The <keyspace/shard> argument must be used to identify at least one keyspace and shard when calling the <DeleteShard> command. This error occurs if the command is not called with at least one argument.

EmergencyReparentShard

Reparents the shard to the new master. Assumes the old master is dead and not responsding.

Example

EmergencyReparentShard <keyspace/shard> <tablet alias>

Flags

Name Type Definition
wait_slave_timeout Duration time to wait for slaves to catch up in reparenting

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • action <EmergencyReparentShard> requires <keyspace/shard> <tablet alias> This error occurs if the command is not called with exactly 2 arguments.

GetShard

Outputs a JSON structure that contains information about the Shard.

Example

GetShard <keyspace/shard>

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <keyspace/shard> argument is required for the <GetShard> command. This error occurs if the command is not called with exactly one argument.

InitShardMaster

Sets the initial master for a shard. Will make all other tablets in the shard slaves of the provided master. WARNING: this could cause data loss on an already replicating shard. PlannedReparentShard or EmergencyReparentShard should be used instead.

Example

InitShardMaster [-force] [-wait_slave_timeout=<duration>] <keyspace/shard> <tablet alias>

Flags

Name Type Definition
force Boolean will force the reparent even if the provided tablet is not a master or the shard master
wait_slave_timeout Duration time to wait for slaves to catch up in reparenting

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • action <InitShardMaster> requires <keyspace/shard> <tablet alias> This error occurs if the command is not called with exactly 2 arguments.

ListBackups

Lists all the backups for a shard.

Example

ListBackups <keyspace/shard>

Errors

  • action <ListBackups> requires <keyspace/shard> This error occurs if the command is not called with exactly one argument.

ListShardTablets

Lists all tablets in the specified shard.

Example

ListShardTablets <keyspace/shard>

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <keyspace/shard> argument is required for the <ListShardTablets> command. This error occurs if the command is not called with exactly one argument.

PlannedReparentShard

Reparents the shard to the new master. Both old and new master need to be up and running.

Example

PlannedReparentShard <keyspace/shard> <tablet alias>

Flags

Name Type Definition
wait_slave_timeout Duration time to wait for slaves to catch up in reparenting

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • action <PlannedReparentShard> requires <keyspace/shard> <tablet alias> This error occurs if the command is not called with exactly 2 arguments.

RemoveBackup

Removes a backup for the BackupStorage.

Example

RemoveBackup <keyspace/shard> <backup name>

Arguments

  • <backup name> – Required.

Errors

  • action <RemoveBackup> requires <keyspace/shard> <backup name> This error occurs if the command is not called with exactly 2 arguments.

RemoveShardCell

Removes the cell from the shard's Cells list.

Example

RemoveShardCell [-force] [-recursive] <keyspace/shard> <cell>

Flags

Name Type Definition
force Boolean Proceeds even if the cell's topology server cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data.
recursive Boolean Also delete all tablets in that cell belonging to the specified shard.

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
  • <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.

Errors

  • The <keyspace/shard> and <cell> arguments are required for the <RemoveShardCell> command. This error occurs if the command is not called with exactly 2 arguments.

SetShardServedTypes

Sets a given shard's served tablet types. Does not rebuild any serving graph.

Example

SetShardServedTypes <keyspace/shard> [<served tablet type1>,<served tablet type2>,...]

Flags

Name Type Definition
cells string Specifies a comma-separated list of cells to update
remove Boolean Removes the served tablet type

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

  • <served tablet type> – Optional. The vttablet's role. Valid values are:

    • backup – A slaved copy of data that is offline to queries other than for backup purposes
    • batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
    • experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
    • master – A primary copy of data
    • rdonly – A slaved copy of data for OLAP load patterns
    • replica – A slaved copy of data ready to be promoted to master
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
    • snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
      vtctl Snapshot -server-mode ...
      Use this command to exit this mode: 
      vtctl SnapshotSourceEnd ...
    • spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
    • worker – A tablet that is in use by a vtworker process. The tablet is likely lagging in replication.

Errors

  • The <keyspace/shard> and <served tablet type> arguments are both required for the <SetShardServedTypes> command. This error occurs if the command is not called with exactly 2 arguments.

SetShardTabletControl

Sets the TabletControl record for a shard and type. Only use this for an emergency fix or after a finished vertical split. The MigrateServedFrom and MigrateServedType commands set this field appropriately already. Always specify the blacklisted_tables flag for vertical splits, but never for horizontal splits.

Example

SetShardTabletControl [--cells=c1,c2,...] [--blacklisted_tables=t1,t2,...] [--remove] [--disable_query_service] <keyspace/shard> <tablet type>

Flags

Name Type Definition
cells string Specifies a comma-separated list of cells to update
disable_query_service Boolean Disables query service on the provided nodes
remove Boolean Removes cells for vertical splits. This flag requires the tables flag to also be set.
tables string Specifies a comma-separated list of tables to replicate (used for vertical split)

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

  • <tablet type> – Required. The vttablet's role. Valid values are:

    • backup – A slaved copy of data that is offline to queries other than for backup purposes
    • batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
    • experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
    • master – A primary copy of data
    • rdonly – A slaved copy of data for OLAP load patterns
    • replica – A slaved copy of data ready to be promoted to master
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
    • snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
      vtctl Snapshot -server-mode ...
      Use this command to exit this mode: 
      vtctl SnapshotSourceEnd ...
    • spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
    • worker – A tablet that is in use by a vtworker process. The tablet is likely lagging in replication.

Errors

  • The <keyspace/shard> and <tablet type> arguments are both required for the <SetShardTabletControl> command. This error occurs if the command is not called with exactly 2 arguments.

ShardReplicationFix

Walks through a ShardReplication object and fixes the first error that it encounters.

Example

ShardReplicationFix <cell> <keyspace/shard>

Arguments

  • <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <cell> and <keyspace/shard> arguments are required for the ShardReplicationRemove command. This error occurs if the command is not called with exactly 2 arguments.

ShardReplicationPositions

Shows the replication status of each slave machine in the shard graph. In this case, the status refers to the replication lag between the master vttablet and the slave vttablet. In Vitess, data is always written to the master vttablet first and then replicated to all slave vttablets. Output is sorted by tablet type, then replication position. Use ctrl-C to interrupt command and see partial result if needed.

Example

ShardReplicationPositions <keyspace/shard>

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <keyspace/shard> argument is required for the <ShardReplicationPositions> command. This error occurs if the command is not called with exactly one argument.

SourceShardAdd

Adds the SourceShard record with the provided index. This is meant as an emergency function. It does not call RefreshState for the shard master.

Example

SourceShardAdd [--key_range=<keyrange>] [--tables=<table1,table2,...>] <keyspace/shard> <uid> <source keyspace/shard>

Flags

Name Type Definition
key_range string Identifies the key range to use for the SourceShard
tables string Specifies a comma-separated list of tables to replicate (used for vertical split)

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
  • <uid> – Required.
  • <source keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <keyspace/shard>, <uid>, and <source keyspace/shard> arguments are all required for the <SourceShardAdd> command. This error occurs if the command is not called with exactly 3 arguments.

SourceShardDelete

Deletes the SourceShard record with the provided index. This is meant as an emergency cleanup function. It does not call RefreshState for the shard master.

Example

SourceShardDelete <keyspace/shard> <uid>

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
  • <uid> – Required.

Errors

  • The <keyspace/shard> and <uid> arguments are both required for the <SourceShardDelete> command. This error occurs if the command is not called with at least 2 arguments.

TabletExternallyReparented

Changes metadata in the topology server to acknowledge a shard master change performed by an external tool. See the Reparenting guide for more information:https://github.com/youtube/vitess/blob/master/doc/Reparenting.md#external-reparents.

Example

TabletExternallyReparented <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <TabletExternallyReparented> command. This error occurs if the command is not called with exactly one argument.

ValidateShard

Validates that all nodes that are reachable from this shard are consistent.

Example

ValidateShard [-ping-tablets] <keyspace/shard>

Flags

Name Type Definition
ping-tablets Boolean Indicates whether all tablets should be pinged during the validation process

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <keyspace/shard> argument is required for the <ValidateShard> command. This error occurs if the command is not called with exactly one argument.

WaitForFilteredReplication

Blocks until the specified shard has caught up with the filtered replication of its source shard.

Example

WaitForFilteredReplication [-max_delay <max_delay, default 30s>] <keyspace/shard>

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.

Errors

  • The <keyspace/shard> argument is required for the <WaitForFilteredReplication> command. This error occurs if the command is not called with exactly one argument.
  • shard %v/%v has no source shard
  • shard %v/%v has no master
  • failed to run explicit healthcheck on tablet: %v err: %v
  • cannot connect to tablet %v: %v
  • could not stream health records from tablet: %v err: %v
  • context was done before filtered replication did catch up. Last seen delay: %v context Error: %v
  • stream ended early: %v
  • health record does not include RealtimeStats message. tablet: %v health record: %v
  • tablet is not healthy. tablet: %v health record: %v
  • no filtered replication running on tablet: %v health record: %v
  • last seen delay should never be negative. tablet: %v delay: %v

Tablets

Backup

Stops mysqld and uses the BackupStorage service to store a new backup. This function also remembers if the tablet was replicating so that it can restore the same state after the backup completes.

Example

Backup [-concurrency=4] <tablet alias>

Flags

Name Type Definition
concurrency Int Specifies the number of compression/checksum jobs to run simultaneously

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <Backup> command requires the <tablet alias> argument. This error occurs if the command is not called with exactly one argument.

ChangeSlaveType

Changes the db type for the specified tablet, if possible. This command is used primarily to arrange replicas, and it will not convert a master.

NOTE: This command automatically updates the serving graph.

Example

ChangeSlaveType [-dry-run] <tablet alias> <tablet type>

Flags

Name Type Definition
dry-run Boolean Lists the proposed change without actually executing it

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

  • <tablet type> – Required. The vttablet's role. Valid values are:

    • backup – A slaved copy of data that is offline to queries other than for backup purposes
    • batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
    • experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
    • master – A primary copy of data
    • rdonly – A slaved copy of data for OLAP load patterns
    • replica – A slaved copy of data ready to be promoted to master
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
    • snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
      vtctl Snapshot -server-mode ...
      Use this command to exit this mode: 
      vtctl SnapshotSourceEnd ...
    • spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
    • worker – A tablet that is in use by a vtworker process. The tablet is likely lagging in replication.

Errors

  • The <tablet alias> and <db type> arguments are required for the <ChangeSlaveType> command. This error occurs if the command is not called with exactly 2 arguments.
  • failed reading tablet %v: %v
  • invalid type transition %v: %v -> %v

DeleteTablet

Deletes tablet(s) from the topology.

Example

DeleteTablet [-allow_master] <tablet alias> ...

Flags

Name Type Definition
allow_master Boolean Allows for the master tablet of a shard to be deleted. Use with caution.

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space.

Errors

  • The <tablet alias> argument must be used to specify at least one tablet when calling the <DeleteTablet> command. This error occurs if the command is not called with at least one argument.

DemoteMaster

Demotes a master tablet.

Example

DemoteMaster <tablet alias>

Errors

  • action <DemoteMaster> requires <tablet alias> This error occurs if the command is not called with exactly one argument.

ExecuteFetchAsDba

Runs the given SQL command as a DBA on the remote tablet.

Example

ExecuteFetchAsDba [-max_rows=10000] [-disable_binlogs] [-json] <tablet alias> <sql command>

Flags

Name Type Definition
disable_binlogs Boolean Disables writing to binlogs during the query
json Boolean Output JSON instead of human-readable table
max_rows Int Specifies the maximum number of rows to allow in reset
reload_schema Boolean Indicates whether the tablet schema will be reloaded after executing the SQL command. The default value is false, which indicates that the tablet schema will not be reloaded.

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
  • <sql command> – Required.

Errors

  • The <tablet alias> and <sql command> arguments are required for the <ExecuteFetchAsDba> command. This error occurs if the command is not called with exactly 2 arguments.

ExecuteHook

Runs the specified hook on the given tablet. A hook is a script that resides in the $VTROOT/vthook directory. You can put any script into that directory and use this command to run that script.

For this command, the param=value arguments are parameters that the command passes to the specified hook.

Example

ExecuteHook <tablet alias> <hook name> [<param1=value1> <param2=value2> ...]

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
  • <hook name> – Required.
  • <param1=value1> <param2=value2> . – Optional.

Errors

  • The <tablet alias> and <hook name> arguments are required for the <ExecuteHook> command. This error occurs if the command is not called with at least 2 arguments.

GetTablet

Outputs a JSON structure that contains information about the Tablet.

Example

GetTablet <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <GetTablet> command. This error occurs if the command is not called with exactly one argument.

IgnoreHealthError

Sets the regexp for health check errors to ignore on the specified tablet. The pattern has implicit ^$ anchors. Set to empty string or restart vttablet to stop ignoring anything.

Example

IgnoreHealthError <tablet alias> <ignore regexp>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
  • <ignore regexp> – Required.

Errors

  • The <tablet alias> and <ignore regexp> arguments are required for the <IgnoreHealthError> command. This error occurs if the command is not called with exactly 2 arguments.

InitTablet

Initializes a tablet in the topology.

Example

InitTablet [-allow_update] [-allow_different_shard] [-allow_master_override] [-parent] [-db_name_override=<db name>] [-hostname=<hostname>] [-mysql_port=<port>] [-port=<port>] [-grpc_port=<port>] -keyspace=<keyspace> -shard=<shard> <tablet alias> <tablet type>

Flags

Name Type Definition
allow_different_shard Boolean Use this flag to force initialization if a tablet with the same name but a different keyspace/shard already exists. Use with caution.
allow_master_override Boolean Use this flag to force initialization if a tablet is created as master, and a master for the keyspace/shard already exists. Use with caution.
allow_update Boolean Use this flag to force initialization if a tablet with the same name already exists. Use with caution.
db_name_override string Overrides the name of the database that the vttablet uses
grpc_port Int The gRPC port for the vttablet process
hostname string The server on which the tablet is running
keyspace string The keyspace to which this tablet belongs
mysql_port Int The mysql port for the mysql daemon
parent Boolean Creates the parent shard and keyspace if they don't yet exist
port Int The main port for the vttablet process
shard string The shard to which this tablet belongs
tags string A comma-separated list of key:value pairs that are used to tag the tablet

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

  • <tablet type> – Required. The vttablet's role. Valid values are:

    • backup – A slaved copy of data that is offline to queries other than for backup purposes
    • batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
    • experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
    • master – A primary copy of data
    • rdonly – A slaved copy of data for OLAP load patterns
    • replica – A slaved copy of data ready to be promoted to master
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
    • snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
      vtctl Snapshot -server-mode ...
      Use this command to exit this mode: 
      vtctl SnapshotSourceEnd ...
    • spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
    • worker – A tablet that is in use by a vtworker process. The tablet is likely lagging in replication.

Errors

  • The <tablet alias> and <tablet type> arguments are both required for the <InitTablet> command. This error occurs if the command is not called with exactly 2 arguments.

Ping

Checks that the specified tablet is awake and responding to RPCs. This command can be blocked by other in-flight operations.

Example

Ping <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <Ping> command. This error occurs if the command is not called with exactly one argument.

RefreshState

Reloads the tablet record on the specified tablet.

Example

RefreshState <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <RefreshState> command. This error occurs if the command is not called with exactly one argument.

ReparentTablet

Reparent a tablet to the current master in the shard. This only works if the current slave position matches the last known reparent action.

Example

ReparentTablet <tablet alias>

Errors

  • action <ReparentTablet> requires <tablet alias> This error occurs if the command is not called with exactly one argument.

RunHealthCheck

Runs a health check on a remote tablet.

Example

RunHealthCheck <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <RunHealthCheck> command. This error occurs if the command is not called with exactly one argument.

SetReadOnly

Sets the tablet as read-only.

Example

SetReadOnly <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <SetReadOnly> command. This error occurs if the command is not called with exactly one argument.
  • failed reading tablet %v: %v

SetReadWrite

Sets the tablet as read-write.

Example

SetReadWrite <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <SetReadWrite> command. This error occurs if the command is not called with exactly one argument.
  • failed reading tablet %v: %v

Sleep

Blocks the action queue on the specified tablet for the specified amount of time. This is typically used for testing.

Example

Sleep <tablet alias> <duration>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
  • <duration> – Required. The amount of time that the action queue should be blocked. The value is a string that contains a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms" or "1h45m". See the definition of the Go language's ParseDuration function for more details. Note that, in practice, the value should be a positively signed value.

Errors

  • The <tablet alias> and <duration> arguments are required for the <Sleep> command. This error occurs if the command is not called with exactly 2 arguments.

StartSlave

Starts replication on the specified slave.

Example

StartSlave <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • action <StartSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument.
  • failed reading tablet %v: %v

StopSlave

Stops replication on the specified slave.

Example

StopSlave <tablet alias>

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • action <StopSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument.
  • failed reading tablet %v: %v

UpdateTabletAddrs

Updates the IP address and port numbers of a tablet.

Example

UpdateTabletAddrs [-hostname <hostname>] [-ip-addr <ip addr>] [-mysql-port <mysql port>] [-vt-port <vt port>] [-grpc-port <grpc port>] <tablet alias>

Flags

Name Type Definition
grpc-port Int The gRPC port for the vttablet process
hostname string The fully qualified host name of the server on which the tablet is running.
ip-addr string IP address
mysql-port Int The mysql port for the mysql daemon
vt-port Int The main port for the vttablet process

Arguments

  • <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.

Errors

  • The <tablet alias> argument is required for the <UpdateTabletAddrs> command. This error occurs if the command is not called with exactly one argument.
  • malformed address: %v