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:
Lists all tablets in an awk-friendly way.
ListAllTablets <cell name>
<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.<cell name> argument is required for the <ListAllTablets> command. This error occurs if the command is not called with exactly one argument.Lists specified tablets in an awk-friendly way.
ListTablets <tablet alias> ...
<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.<tablet alias> argument is required for the <ListTablets> command. This error occurs if the command is not called with at least one argument.(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.
PruneActionLogs [-keep-count=<count to keep>] <zk actionlog path> ...
| Name | Type | Definition |
|---|---|---|
| keep-count | Int | count to keep |
<zk actionlog path> – Required. To specify multiple values for this argument, separate individual values with a space.<PruneActionLogs> requires <zk action log path> [...] This error occurs if the command is not called with at least one argument.<PruneActionLogs> requires a zktopo.ServerValidates that all nodes reachable from the global replication graph and that all tablets in all discoverable cells are consistent.
Validate [-ping-tablets]
| Name | Type | Definition |
|---|---|---|
| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process |
Creates the specified keyspace.
CreateKeyspace [-sharding_column_name=name] [-sharding_column_type=type] [-served_from=tablettype1:ks1,tablettype2,ks2,...] [-force] <keyspace name>
| 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 |
<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.<keyspace name> argument is required for the <CreateKeyspace> command. This error occurs if the command is not called with exactly one argument.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.
DeleteKeyspace [-recursive] <keyspace>
| Name | Type | Definition |
|---|---|---|
| recursive | Boolean | Also recursively delete all shards in the keyspace. |
<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.<keyspace> argument for <DeleteKeyspace>. This error occurs if the command is not called with exactly one argument.Displays all of the shards in the specified keyspace.
FindAllShardsInKeyspace <keyspace>
<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.<keyspace> argument is required for the <FindAllShardsInKeyspace> command. This error occurs if the command is not called with exactly one argument.Outputs a JSON structure that contains information about the Keyspace.
GetKeyspace <keyspace>
<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.<keyspace> argument is required for the <GetKeyspace> command. This error occurs if the command is not called with exactly one argument.Outputs a sorted list of all keyspaces.
Makes the <destination keyspace/shard> serve the given type. This command also rebuilds the serving graph.
MigrateServedFrom [-cells=c1,c2,...] [-reverse] <destination keyspace/shard> <served tablet type>
| 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 |
<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 purposesbatch – 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 datardonly – A slaved copy of data for OLAP load patternsreplica – A slaved copy of data ready to be promoted to masterrestore – 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.drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication.<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.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.
MigrateServedTypes [-cells=c1,c2,...] [-reverse] [-skip-refresh-state] <keyspace/shard> <served tablet type>
| 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) |
<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 purposesbatch – 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 datardonly – A slaved copy of data for OLAP load patternsreplica – A slaved copy of data ready to be promoted to masterrestore – 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.<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.<skip-refresh-state> flag can only be specified for non-master migrations.Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients.
RebuildKeyspaceGraph [-cells=c1,c2,...] <keyspace> ...
| Name | Type | Definition |
|---|---|---|
| cells | string | Specifies a comma-separated list of cells to update |
<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.<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.Removes the cell from the Cells list for all shards in the keyspace.
RemoveKeyspaceCell [-force] [-recursive] <keyspace> <cell>
| 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. |
<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.<keyspace> and <cell> arguments are required for the <RemoveKeyspaceCell> command. This error occurs if the command is not called with exactly 2 arguments.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.
SetKeyspaceServedFrom [-source=<source keyspace name>] [-remove] [-cells=c1,c2,...] <keyspace name> <tablet type>
| 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 |
<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 purposesbatch – 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 datardonly – A slaved copy of data for OLAP load patternsreplica – A slaved copy of data ready to be promoted to masterrestore – 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.<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.Updates the sharding information for a keyspace.
SetKeyspaceShardingInfo [-force] <keyspace name> [<column name>] [<column type>]
| Name | Type | Definition |
|---|---|---|
| force | Boolean | Updates fields even if they are already set. Use caution before calling this command. |
<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.<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.<column name> and <column type> must be set, or both must be unset.Validates that all nodes reachable from the specified keyspace are consistent.
ValidateKeyspace [-ping-tablets] <keyspace name>
| Name | Type | Definition |
|---|---|---|
| ping-tablets | Boolean | Specifies whether all tablets will be pinged during the validation process |
<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.<keyspace name> argument is required for the <ValidateKeyspace> command. This error occurs if the command is not called with exactly one argument.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.
WaitForDrain [-timeout <duration>] [-retry_delay <duration>] [-initial_wait <duration>] <keyspace/shard> <served tablet type>
| Name | Type | Definition |
|---|---|---|
| cells | string | Specifies a comma-separated list of cells to look for tablets |
| initial_wait | Duration | Time to wait for all tablets to check in |
| retry_delay | Duration | Time to wait between two checks |
| timeout | Duration | Timeout after which the command fails |
<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 purposesbatch – 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 datardonly – A slaved copy of data for OLAP load patternsreplica – A slaved copy of data ready to be promoted to masterrestore – 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.<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.Executes the given SQL query with the provided bound variables against the vtgate server.
VtGateExecute -server <vtgate> [-bind_variables <JSON map>] [-connect_timeout <connect timeout>] [-keyspace <default keyspace>] [-tablet_type <tablet type>] [-options <proto text options>] [-json] <sql>
| 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 |
| options | string | execute options values as a text encoded proto of the ExecuteOptions structure |
| server | string | VtGate server to connect to |
| tablet_type | string | tablet type to query |
<vtgate> – Required.<sql> – Required.<sql> argument is required for the <VtGateExecute> command This error occurs if the command is not called with exactly one argument.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.
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>] [-options <proto text options>] [-json] <sql>
| 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 |
| options | string | execute options values as a text encoded proto of the ExecuteOptions structure |
| server | string | VtGate server to connect to |
| tablet_type | string | tablet type to query |
<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.<sql> argument is required for the <VtGateExecuteKeyspaceIds> command This error occurs if the command is not called with exactly one argument.Executes the given SQL query with the provided bound variables against the vtgate server. It is routed to the provided shards.
VtGateExecuteShards -server <vtgate> -keyspace <keyspace> -shards <shard0>,<shard1>,... [-bind_variables <JSON map>] [-connect_timeout <connect timeout>] [-tablet_type <tablet type>] [-options <proto text options>] [-json] <sql>
| 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 |
| options | string | execute options values as a text encoded proto of the ExecuteOptions structure |
| 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 |
<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.<sql> argument is required for the <VtGateExecuteShards> command This error occurs if the command is not called with exactly one argument.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).
VtGateSplitQuery -server <vtgate> -keyspace <keyspace> [-split_column <split_column>] -split_count <split_count> [-bind_variables <JSON map>] [-connect_timeout <connect timeout>] <sql>
| 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 |
<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.<sql> argument is required for the <VtGateSplitQuery> command This error occurs if the command is not called with exactly one argument.Starts a transaction on the provided server.
VtTabletBegin [-connect_timeout <connect timeout>] [-tablet_type <tablet_type>] -keyspace <keyspace> -shard <shard> <tablet alias>
| Name | Type | Definition |
|---|---|---|
| connect_timeout | Duration | Connection timeout for vttablet client |
<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>.<tablet_alias> argument is required for the <VtTabletBegin> command This error occurs if the command is not called with exactly one argument.Commits a transaction on the provided server.
VtTabletCommit [-connect_timeout <connect timeout>] [-tablet_type <tablet_type>] -keyspace <keyspace> -shard <shard> <tablet alias> <transaction_id>
| Name | Type | Definition |
|---|---|---|
| connect_timeout | Duration | Connection timeout for vttablet client |
<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.<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.Executes the given query on the given tablet.
VtTabletExecute [-bind_variables <JSON map>] [-connect_timeout <connect timeout>] [-transaction_id <transaction_id>] [-tablet_type <tablet_type>] [-options <proto text options>] [-json] -keyspace <keyspace> -shard <shard> <tablet alias> <sql>
| Name | Type | Definition |
|---|---|---|
| connect_timeout | Duration | Connection timeout for vttablet client |
| json | Boolean | Output JSON instead of human-readable table |
| options | string | execute options values as a text encoded proto of the ExecuteOptions structure |
| transaction_id | Int | transaction id to use, if inside a transaction. |
<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.<tablet_alias> and <sql> arguments are required for the <VtTabletExecute> command This error occurs if the command is not called with exactly 2 arguments.Rollbacks a transaction on the provided server.
VtTabletRollback [-connect_timeout <connect timeout>] [-tablet_type <tablet_type>] -keyspace <keyspace> -shard <shard> <tablet alias> <transaction_id>
| Name | Type | Definition |
|---|---|---|
| connect_timeout | Duration | Connection timeout for vttablet client |
<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.<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.Executes the StreamHealth streaming query to a vttablet process. Will stop after getting <count> answers.
VtTabletStreamHealth [-count <count, default 1>] [-connect_timeout <connect timeout>] <tablet alias>
| Name | Type | Definition |
|---|---|---|
| connect_timeout | Duration | Connection timeout for vttablet client |
| count | Int | number of responses to wait for |
<count default 1> – Required.<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <VtTabletStreamHealth> command. This error occurs if the command is not called with exactly one argument.Executes the UpdateStream streaming query to a vttablet process. Will stop after getting <count> answers.
VtTabletUpdateStream [-count <count, default 1>] [-connect_timeout <connect timeout>] [-position <position>] [-timestamp <timestamp>] <tablet alias>
| Name | Type | Definition |
|---|---|---|
| connect_timeout | Duration | Connection timeout for vttablet client |
| count | Int | number of responses to wait for |
| position | string | position to start the stream from |
| timestamp | Int | timestamp to start the stream from |
<count default 1> – Required.<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <VtTabletUpdateStream> command. This error occurs if the command is not called with exactly one argument.Outputs a JSON structure that contains information about the ShardReplication.
GetShardReplication <cell> <keyspace/shard>
<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>.<cell> and <keyspace/shard> arguments are required for the <GetShardReplication> command. This error occurs if the command is not called with exactly 2 arguments.Returns the current configuration of the MaxReplicationLag module. If no throttler name is specified, the configuration of all throttlers will be returned.
GetThrottlerConfiguration -server <vtworker or vttablet> [<throttler name>]
| Name | Type | Definition |
|---|---|---|
| server | string | vtworker or vttablet to connect to |
<vtworker or vttablet> – Required.<throttler name> – Optional.<GetThrottlerConfiguration> command accepts only <throttler name> as optional positional parameter This error occurs if the command is not called with more than 1 arguments.<server> '%v': %v<server> '%v': %vResets the current configuration of the MaxReplicationLag module. If no throttler name is specified, the configuration of all throttlers will be reset.
ResetThrottlerConfiguration -server <vtworker or vttablet> [<throttler name>]
| Name | Type | Definition |
|---|---|---|
| server | string | vtworker or vttablet to connect to |
<vtworker or vttablet> – Required.<throttler name> – Optional.<ResetThrottlerConfiguration> command accepts only <throttler name> as optional positional parameter This error occurs if the command is not called with more than 1 arguments.<server> '%v': %v<server> '%v': %vReturns the current max rate of all active resharding throttlers on the server.
ThrottlerMaxRates -server <vtworker or vttablet>
| Name | Type | Definition |
|---|---|---|
| server | string | vtworker or vttablet to connect to |
<vtworker or vttablet> – Required.<server> '%v': %v<server> '%v': %vSets the max rate for all active resharding throttlers on the server.
ThrottlerSetMaxRate -server <vtworker or vttablet> <rate>
| Name | Type | Definition |
|---|---|---|
| server | string | vtworker or vttablet to connect to |
<vtworker or vttablet> – Required.<rate> – Required.<rate> argument is required for the <ThrottlerSetMaxRate> command This error occurs if the command is not called with exactly one argument.<server> '%v': %v<server> '%v': %vUpdates the configuration of the MaxReplicationLag module. The configuration must be specified as protobuf text. If a field is omitted or has a zero value, it will be ignored unless -copy_zero_values is specified. If no throttler name is specified, all throttlers will be updated.
UpdateThrottlerConfiguration `-server <vtworker or vttablet> [-copy_zero_values] "<configuration protobuf text>" [<throttler name>]`
| Name | Type | Definition |
|---|---|---|
| copy_zero_values | Boolean | If true, fields with zero values will be copied as well |
| server | string | vtworker or vttablet to connect to |
<vtworker or vttablet> – Required.<throttler name> – Optional.<server> '%v': %v<server> '%v': %vApplies 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.
ApplySchema [-allow_long_unavailability] [-wait_slave_timeout=10s] {-sql=<sql> || -sql-file=<filename>} <keyspace>
| 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. |
<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.<keyspace> argument is required for the command<ApplySchema> command. This error occurs if the command is not called with exactly one argument.Applies the VTGate routing schema to the provided keyspace. Shows the result after application.
ApplyVSchema {-vschema=<vschema> || -vschema_file=<vschema file>} [-cells=c1,c2,...] [-skip_rebuild] <keyspace>
| 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 |
<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.<keyspace> argument is required for the <ApplyVSchema> command. This error occurs if the command is not called with exactly one argument.<vschema> or <vschema>File flag must be specified when calling the <ApplyVSchema> command.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.
CopySchemaShard [-tables=<table1>,<table2>,...] [-exclude_tables=<table1>,<table2>,...] [-include-views] [-wait_slave_timeout=10s] {<source keyspace/shard> || <source tablet alias>} <destination keyspace/shard>
| 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. |
<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>.<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.Displays the permissions for a tablet.
GetPermissions <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <GetPermissions> command. This error occurs if the command is not called with exactly one argument.Displays the full schema for a tablet, or just the schema for the specified tables in that tablet.
GetSchema [-tables=<table1>,<table2>,...] [-exclude_tables=<table1>,<table2>,...] [-include-views] <tablet alias>
| 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 |
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <GetSchema> command. This error occurs if the command is not called with exactly one argument.Displays the VTGate routing schema.
GetVSchema <keyspace>
<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.<keyspace> argument is required for the <GetVSchema> command. This error occurs if the command is not called with exactly one argument.Rebuilds the cell-specific SrvVSchema from the global VSchema objects in the provided cells (or all cells if none provided).
RebuildVSchemaGraph [-cells=c1,c2,...]
| Name | Type | Definition |
|---|---|---|
| cells | string | Specifies a comma-separated list of cells to look for tablets |
<RebuildVSchemaGraph> doesn't take any arguments. This error occurs if the command is not called with exactly 0 arguments.Reloads the schema on a remote tablet.
ReloadSchema <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <ReloadSchema> command. This error occurs if the command is not called with exactly one argument.Validates that the master permissions from shard 0 match those of all of the other tablets in the keyspace.
ValidatePermissionsKeyspace <keyspace name>
<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.<keyspace name> argument is required for the <ValidatePermissionsKeyspace> command. This error occurs if the command is not called with exactly one argument.Validates that the master permissions match all the slaves.
ValidatePermissionsShard <keyspace/shard>
<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>.<keyspace/shard> argument is required for the <ValidatePermissionsShard> command. This error occurs if the command is not called with exactly one argument.Validates that the master schema from shard 0 matches the schema on all of the other tablets in the keyspace.
ValidateSchemaKeyspace [-exclude_tables=''] [-include-views] <keyspace name>
| 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 |
<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.<keyspace name> argument is required for the <ValidateSchemaKeyspace> command. This error occurs if the command is not called with exactly one argument.Validates that the master schema matches all of the slaves.
ValidateSchemaShard [-exclude_tables=''] [-include-views] <keyspace/shard>
| 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 |
<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>.<keyspace/shard> argument is required for the <ValidateSchemaShard> command. This error occurs if the command is not called with exactly one argument.Validates that the master version from shard 0 matches all of the other tablets in the keyspace.
ValidateVersionKeyspace <keyspace name>
<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.<keyspace name> argument is required for the <ValidateVersionKeyspace> command. This error occurs if the command is not called with exactly one argument.Validates that the master version matches all of the slaves.
ValidateVersionShard <keyspace/shard>
<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>.<keyspace/shard> argument is requird for the <ValidateVersionShard> command. This error occurs if the command is not called with exactly one argument.Outputs a JSON structure that contains information about the SrvKeyspace.
GetSrvKeyspace <cell> <keyspace>
<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.<cell> and <keyspace> arguments are required for the <GetSrvKeyspace> command. This error occurs if the command is not called with exactly 2 arguments.Outputs a list of keyspace names.
GetSrvKeyspaceNames <cell>
<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.<cell> argument is required for the <GetSrvKeyspaceNames> command. This error occurs if the command is not called with exactly one argument.Outputs a JSON structure that contains information about the SrvVSchema.
GetSrvVSchema <cell>
<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.<cell> argument is required for the <GetSrvVSchema> command. This error occurs if the command is not called with exactly one argument.Creates the specified shard.
CreateShard [-force] [-parent] <keyspace/shard>
| 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 |
<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>.<keyspace/shard> argument is required for the <CreateShard> command. This error occurs if the command is not called with exactly one argument.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.
DeleteShard [-recursive] [-even_if_serving] <keyspace/shard> ...
| Name | Type | Definition |
|---|---|---|
| even_if_serving | Boolean | Remove the shard even if it is serving. Use with caution. |
| recursive | Boolean | Also delete all tablets belonging to the shard. |
<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.<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.Reparents the shard to the new master. Assumes the old master is dead and not responsding.
EmergencyReparentShard -keyspace_shard=<keyspace/shard> -new_master=<tablet alias>
| Name | Type | Definition |
|---|---|---|
| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented |
| new_master | string | alias of a tablet that should be the new master |
| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting |
<EmergencyReparentShard> requires -keyspace_shard=<keyspace/shard> -new_master=<tablet alias> This error occurs if the command is not called with exactly 0 arguments.<new_master> for action <EmergencyReparentShard> at the same timeOutputs a JSON structure that contains information about the Shard.
GetShard <keyspace/shard>
<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>.<keyspace/shard> argument is required for the <GetShard> command. This error occurs if the command is not called with exactly one argument.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.
InitShardMaster [-force] [-wait_slave_timeout=<duration>] <keyspace/shard> <tablet alias>
| 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 |
<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>.<InitShardMaster> requires <keyspace/shard> <tablet alias> This error occurs if the command is not called with exactly 2 arguments.Lists all the backups for a shard.
ListBackups <keyspace/shard>
<ListBackups> requires <keyspace/shard> This error occurs if the command is not called with exactly one argument.Lists all tablets in the specified shard.
ListShardTablets <keyspace/shard>
<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>.<keyspace/shard> argument is required for the <ListShardTablets> command. This error occurs if the command is not called with exactly one argument.Reparents the shard to the new master, or away from old master. Both old and new master need to be up and running.
PlannedReparentShard -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>]
| Name | Type | Definition |
|---|---|---|
| avoid_master | string | alias of a tablet that should not be the master, i.e. reparent to any other tablet if this one is the master |
| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented |
| new_master | string | alias of a tablet that should be the new master |
| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting |
<PlannedReparentShard> requires -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>] This error occurs if the command is not called with exactly 0 arguments.<keyspace_shard> and -<new_master> for action <PlannedReparentShard> at the same timeRemoves a backup for the BackupStorage.
RemoveBackup <keyspace/shard> <backup name>
<backup name> – Required.<RemoveBackup> requires <keyspace/shard> <backup name> This error occurs if the command is not called with exactly 2 arguments.Removes the cell from the shard's Cells list.
RemoveShardCell [-force] [-recursive] <keyspace/shard> <cell>
| 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. |
<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.<keyspace/shard> and <cell> arguments are required for the <RemoveShardCell> command. This error occurs if the command is not called with exactly 2 arguments.Add or remove served type to/from a shard. This is meant as an emergency function. It does not rebuild any serving graph i.e. does not run 'RebuildKeyspaceGraph'.
SetShardServedTypes [--cells=c1,c2,...] [--remove] <keyspace/shard> <served tablet type>
| Name | Type | Definition |
|---|---|---|
| cells | string | Specifies a comma-separated list of cells to update |
| remove | Boolean | Removes the served tablet type |
<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 purposesbatch – 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 datardonly – A slaved copy of data for OLAP load patternsreplica – A slaved copy of data ready to be promoted to masterrestore – 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.<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.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.
SetShardTabletControl [--cells=c1,c2,...] [--blacklisted_tables=t1,t2,...] [--remove] [--disable_query_service] <keyspace/shard> <tablet type>
| 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) |
<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 purposesbatch – 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 datardonly – A slaved copy of data for OLAP load patternsreplica – A slaved copy of data ready to be promoted to masterrestore – 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.<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.Walks through a ShardReplication object and fixes the first error that it encounters.
ShardReplicationFix <cell> <keyspace/shard>
<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>.<cell> and <keyspace/shard> arguments are required for the ShardReplicationRemove command. This error occurs if the command is not called with exactly 2 arguments.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.
ShardReplicationPositions <keyspace/shard>
<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>.<keyspace/shard> argument is required for the <ShardReplicationPositions> command. This error occurs if the command is not called with exactly one argument.Adds the SourceShard record with the provided index. This is meant as an emergency function. It does not call RefreshState for the shard master.
SourceShardAdd [--key_range=<keyrange>] [--tables=<table1,table2,...>] <keyspace/shard> <uid> <source keyspace/shard>
| 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) |
<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>.<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.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.
SourceShardDelete <keyspace/shard> <uid>
<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.<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.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.
TabletExternallyReparented <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <TabletExternallyReparented> command. This error occurs if the command is not called with exactly one argument.Validates that all nodes that are reachable from this shard are consistent.
ValidateShard [-ping-tablets] <keyspace/shard>
| Name | Type | Definition |
|---|---|---|
| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process |
<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>.<keyspace/shard> argument is required for the <ValidateShard> command. This error occurs if the command is not called with exactly one argument.Blocks until the specified shard has caught up with the filtered replication of its source shard.
WaitForFilteredReplication [-max_delay <max_delay, default 30s>] <keyspace/shard>
<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>.<keyspace/shard> argument is required for the <WaitForFilteredReplication> command. This error occurs if the command is not called with exactly one argument.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.
Backup [-concurrency=4] <tablet alias>
| Name | Type | Definition |
|---|---|---|
| concurrency | Int | Specifies the number of compression/checksum jobs to run simultaneously |
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<Backup> command requires the <tablet alias> argument. This error occurs if the command is not called with exactly one argument.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.
ChangeSlaveType [-dry-run] <tablet alias> <tablet type>
| Name | Type | Definition |
|---|---|---|
| dry-run | Boolean | Lists the proposed change without actually executing it |
<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 purposesbatch – 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 datardonly – A slaved copy of data for OLAP load patternsreplica – A slaved copy of data ready to be promoted to masterrestore – 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.<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.Deletes tablet(s) from the topology.
DeleteTablet [-allow_master] <tablet alias> ...
| Name | Type | Definition |
|---|---|---|
| allow_master | Boolean | Allows for the master tablet of a shard to be deleted. Use with caution. |
<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.<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.Demotes a master tablet.
DemoteMaster <tablet alias>
<DemoteMaster> requires <tablet alias> This error occurs if the command is not called with exactly one argument.Runs the given SQL command as a DBA on the remote tablet.
ExecuteFetchAsDba [-max_rows=10000] [-disable_binlogs] [-json] <tablet alias> <sql command>
| 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. |
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<sql command> – Required.<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.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.
ExecuteHook <tablet alias> <hook name> [<param1=value1> <param2=value2> ...]
<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.<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.Outputs a JSON structure that contains information about the Tablet.
GetTablet <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <GetTablet> command. This error occurs if the command is not called with exactly one argument.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.
IgnoreHealthError <tablet alias> <ignore regexp>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<ignore regexp> – Required.<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.Initializes a tablet in the topology.
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>
| Name | Type | Definition |
|---|---|---|
| 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 |
<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 purposesbatch – 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 datardonly – A slaved copy of data for OLAP load patternsreplica – A slaved copy of data ready to be promoted to masterrestore – 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.<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.Checks that the specified tablet is awake and responding to RPCs. This command can be blocked by other in-flight operations.
Ping <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <Ping> command. This error occurs if the command is not called with exactly one argument.Reloads the tablet record on the specified tablet.
RefreshState <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <RefreshState> command. This error occurs if the command is not called with exactly one argument.Runs 'RefreshState' on all tablets in the given shard.
RefreshStateByShard [-cells=c1,c2,...] <keyspace/shard>
| Name | Type | Definition |
|---|---|---|
| cells | string | Specifies a comma-separated list of cells whose tablets are included. If empty, all cells are considered. |
<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>.<keyspace/shard> argument is required for the <RefreshStateByShard> command. This error occurs if the command is not called with exactly one argument.Reparent a tablet to the current master in the shard. This only works if the current slave position matches the last known reparent action.
ReparentTablet <tablet alias>
<ReparentTablet> requires <tablet alias> This error occurs if the command is not called with exactly one argument.Stops mysqld and restores the data from the latest backup.
RestoreFromBackup <tablet alias>
<RestoreFromBackup> command requires the <tablet alias> argument. This error occurs if the command is not called with exactly one argument.Runs a health check on a remote tablet.
RunHealthCheck <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <RunHealthCheck> command. This error occurs if the command is not called with exactly one argument.Sets the tablet as read-only.
SetReadOnly <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <SetReadOnly> command. This error occurs if the command is not called with exactly one argument.Sets the tablet as read-write.
SetReadWrite <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <SetReadWrite> command. This error occurs if the command is not called with exactly one argument.Blocks the action queue on the specified tablet for the specified amount of time. This is typically used for testing.
Sleep <tablet alias> <duration>
<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.<tablet alias> and <duration> arguments are required for the <Sleep> command. This error occurs if the command is not called with exactly 2 arguments.Starts replication on the specified slave.
StartSlave <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<StartSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument.Stops replication on the specified slave.
StopSlave <tablet alias>
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<StopSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument.Updates the IP address and port numbers of a tablet.
UpdateTabletAddrs [-hostname <hostname>] [-ip-addr <ip addr>] [-mysql-port <mysql port>] [-vt-port <vt port>] [-grpc-port <grpc port>] <tablet alias>
| 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 |
<tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.<tablet alias> argument is required for the <UpdateTabletAddrs> command. This error occurs if the command is not called with exactly one argument.Sends the provided action name on the specified path.
WorkflowAction <path> <name>
<name> – Required.<path> and <name> arguments are required for the <WorkflowAction> command This error occurs if the command is not called with exactly 2 arguments.Creates the workflow with the provided parameters. The workflow is also started, unless -skip_start is specified.
WorkflowCreate [-skip_start] <factoryName> [parameters...]
| Name | Type | Definition |
|---|---|---|
| skip_start | Boolean | If set, the workflow will not be started. |
<factoryName> – Required.<factoryName> argument is required for the <WorkflowCreate> command This error occurs if the command is not called with at least one argument.Starts the workflow.
WorkflowStart <uuid>
<uuid> argument is required for the <WorkflowStart> command This error occurs if the command is not called with exactly one argument.Stops the workflow.
WorkflowStop <uuid>
<uuid> argument is required for the <WorkflowStop> command This error occurs if the command is not called with exactly one argument.Displays a JSON representation of the workflow tree.
WorkflowTree
<WorkflowTree> command takes no parameter This error occurs if the command is not called with exactly 0 arguments.Waits for the workflow to finish.
WorkflowWait <uuid>
<uuid> argument is required for the <WorkflowWait> command This error occurs if the command is not called with exactly one argument.