vitess-gh/doc/vtctlReference.md

83 KiB

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.

Resolve

Reads a list of addresses that can answer this query. The port name can be mysql, vt, or vts. Vitess uses this name to retrieve the actual port number from the topology server (ZooKeeper or etcd).

Example

Resolve <keyspace>.<shard>.<db type>:<port name>

Arguments

  • <keyspace>.<shard>.<db type>:<port name> – Required.

Errors

  • The <Resolve> command requires a single argument, the value of which must be in the format <keyspace>.<shard>.<db type>:<port name>. This error occurs if the command is not called with exactly one argument.

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,...] [-split_shard_count=N] [-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
split_shard_count Int Specifies the number of shards to use for data splits

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.
  • The <sharding_column_type> flag specifies an invalid value.
  • The <served_from> flag specifies a database (tablet) type that is not in the serving graph. The invalid value is: %v

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.

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)
    • checker – A tablet that is running a checker process. The tablet is likely lagging in replication.
    • 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.
    • idle – An idle vttablet that does not have a keyspace, shard or type assigned
    • lag – A slaved copy of data intentionally lagged for pseudo-backup.
    • lag_orphan – A tablet in the midst of a reparenting process. During that process, the tablet goes into a lag_orphan state until it is reparented properly.
    • 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 has not been in the replication graph and is restoring from a snapshot. Typically, a tablet progresses from the idle state to the restore state and then to the spare state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is not applying a schema change. Following the change, the tablet will revert to its serving type.
    • scrap – A tablet that contains data that needs to be wiped.
    • 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.

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)
    • checker – A tablet that is running a checker process. The tablet is likely lagging in replication.
    • 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.
    • idle – An idle vttablet that does not have a keyspace, shard or type assigned
    • lag – A slaved copy of data intentionally lagged for pseudo-backup.
    • lag_orphan – A tablet in the midst of a reparenting process. During that process, the tablet goes into a lag_orphan state until it is reparented properly.
    • 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 has not been in the replication graph and is restoring from a snapshot. Typically, a tablet progresses from the idle state to the restore state and then to the spare state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is not applying a schema change. Following the change, the tablet will revert to its serving type.
    • scrap – A tablet that contains data that needs to be wiped.
    • 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.

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 and, optionally, all shards in the specified keyspace. This command may trigger an update to all connected clients.

Example

RebuildKeyspaceGraph [-cells=a,b] [-rebuild_srv_shards] <keyspace> ...

Flags

Name Type Definition
cells string Specifies a comma-separated list of cells to update
rebuild_srv_shards Boolean Indicates whether all SrvShard objects should also be rebuilt. The default value is false.

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.

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)
    • checker – A tablet that is running a checker process. The tablet is likely lagging in replication.
    • 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.
    • idle – An idle vttablet that does not have a keyspace, shard or type assigned
    • lag – A slaved copy of data intentionally lagged for pseudo-backup.
    • lag_orphan – A tablet in the midst of a reparenting process. During that process, the tablet goes into a lag_orphan state until it is reparented properly.
    • 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 has not been in the replication graph and is restoring from a snapshot. Typically, a tablet progresses from the idle state to the restore state and then to the spare state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is not applying a schema change. Following the change, the tablet will revert to its serving type.
    • scrap – A tablet that contains data that needs to be wiped.
    • 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.

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] [-split_shard_count=N] <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.
split_shard_count Int Specifies the number of shards to use for data splits

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.
  • The <column type> argument specifies an invalid value for the sharding_column_type.

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.

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.

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 the force flag is set, then numerous checks will be ignored, so that option should be used very cautiously.

Example

ApplySchema [-force] {-sql=<sql> || -sql-file=<filename>} <keyspace>

Flags

Name Type Definition
force Boolean Applies the schema even if the preflight schema doesn't match
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 catch up during reparenting. The default value is 30 seconds.

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.

Example

ApplyVSchema {-vschema=<vschema> || -vschema_file=<vschema file>}

Flags

Name Type Definition
vschema string Identifies the VTGate routing schema
vschema_file string Identifies the VTGate routing schema file

Errors

  • Either the <vschema> or <vschema>File flag must be specified when calling the <ApplyVSchema> command.
  • %T does not support <vschema> operations

CopySchemaShard

Copies the schema from a source tablet to the specified 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] <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

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 <tablet alias> and <keyspace/shard> arguments are both required for the <CopySchemaShard> command. The <tablet alias> argument identifies a source and the <keyspace/shard> argument identifies a destination. 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.

Errors

  • The <GetVSchema> command does not support any arguments. This error occurs if the command is not called with exactly 0 arguments.
  • %T does not support the vschema operations

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

GetEndPoints

Outputs a JSON structure that contains information about the EndPoints.

Example

GetEndPoints <cell> <keyspace/shard> <tablet type>

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>.

  • <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)
    • checker – A tablet that is running a checker process. The tablet is likely lagging in replication.
    • 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.
    • idle – An idle vttablet that does not have a keyspace, shard or type assigned
    • lag – A slaved copy of data intentionally lagged for pseudo-backup.
    • lag_orphan – A tablet in the midst of a reparenting process. During that process, the tablet goes into a lag_orphan state until it is reparented properly.
    • 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 has not been in the replication graph and is restoring from a snapshot. Typically, a tablet progresses from the idle state to the restore state and then to the spare state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is not applying a schema change. Following the change, the tablet will revert to its serving type.
    • scrap – A tablet that contains data that needs to be wiped.
    • 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.

Errors

  • The <cell>, <keyspace/shard>, and <tablet type> arguments are required for the <GetEndPoints> command. This error occurs if the command is not called with exactly 3 arguments.

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.

GetSrvShard

Outputs a JSON structure that contains information about the SrvShard.

Example

GetSrvShard <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 <GetSrvShard> command. This error occurs if the command is not called with exactly 2 arguments.

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).

Example

DeleteShard <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>. 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.

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.

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.

RebuildShardGraph

Rebuilds the replication graph and shard serving data in ZooKeeper or etcd. This may trigger an update to all connected clients.

Example

RebuildShardGraph [-cells=a,b] <keyspace/shard> ...

Flags

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

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 <RebuildShardGraph> command. This error occurs if the command is not called with at least one argument.

RemoveShardCell

Removes the cell from the shard's Cells list.

Example

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

Flags

Name Type Definition
force Boolean Proceeds even if the cell's topology server cannot be reached to check for tablets

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)
    • checker – A tablet that is running a checker process. The tablet is likely lagging in replication.
    • 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.
    • idle – An idle vttablet that does not have a keyspace, shard or type assigned
    • lag – A slaved copy of data intentionally lagged for pseudo-backup.
    • lag_orphan – A tablet in the midst of a reparenting process. During that process, the tablet goes into a lag_orphan state until it is reparented properly.
    • 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 has not been in the replication graph and is restoring from a snapshot. Typically, a tablet progresses from the idle state to the restore state and then to the spare state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is not applying a schema change. Following the change, the tablet will revert to its serving type.
    • scrap – A tablet that contains data that needs to be wiped.
    • 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.

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)
    • checker – A tablet that is running a checker process. The tablet is likely lagging in replication.
    • 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.
    • idle – An idle vttablet that does not have a keyspace, shard or type assigned
    • lag – A slaved copy of data intentionally lagged for pseudo-backup.
    • lag_orphan – A tablet in the midst of a reparenting process. During that process, the tablet goes into a lag_orphan state until it is reparented properly.
    • 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 has not been in the replication graph and is restoring from a snapshot. Typically, a tablet progresses from the idle state to the restore state and then to the spare state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is not applying a schema change. Following the change, the tablet will revert to its serving type.
    • scrap – A tablet that contains data that needs to be wiped.
    • 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.

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.

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 <a href="https://github.com/youtube/vitess/blob/master/doc/Reparenting.md#external-reparents">Reparenting guide for more information.

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.

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.

Valid <tablet type> values for this command are backup, batch, experimental, rdonly, replica, restore, schema_apply, spare, and worker.

Example

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

Flags

Name Type Definition
dry-run Boolean Lists the proposed change without actually executing it
force Boolean Changes the slave type in ZooKeeper or etcd without running hooks

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)
    • checker – A tablet that is running a checker process. The tablet is likely lagging in replication.
    • 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.
    • idle – An idle vttablet that does not have a keyspace, shard or type assigned
    • lag – A slaved copy of data intentionally lagged for pseudo-backup.
    • lag_orphan – A tablet in the midst of a reparenting process. During that process, the tablet goes into a lag_orphan state until it is reparented properly.
    • 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 has not been in the replication graph and is restoring from a snapshot. Typically, a tablet progresses from the idle state to the restore state and then to the spare state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is not applying a schema change. Following the change, the tablet will revert to its serving type.
    • scrap – A tablet that contains data that needs to be wiped.
    • 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.

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 scrapped tablet(s) from the topology.

Example

DeleteTablet <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 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.

ExecuteFetchAsDba

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

Example

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

Flags

Name Type Definition
disable_binlogs Boolean Disables writing to binlogs during the query
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.
want_fields Boolean Indicates whether the request should also get field names

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.

HealthStream

Streams the health status of a tablet.

Example

HealthStream <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 <HealthStream> command. This error occurs if the command is not called with exactly one argument.

InitTablet

Initializes a tablet in the topology.

Example

InitTablet [-force] [-parent] [-update] [-db-name-override=<db name>] [-hostname=<hostname>] [-mysql_port=<port>] [-port=<port>] [-vts_port=<port>] [-keyspace=<keyspace>] [-shard=<shard>] [-parent_alias=<parent alias>] <tablet alias> <tablet type>

Flags

Name Type Definition
db-name-override string Overrides the name of the database that the vttablet uses
force Boolean Overwrites the node if the node already exists
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
update Boolean Performs update if a tablet with the provided alias already exists
vts_port Int The encrypted 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>.

  • <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)
    • checker – A tablet that is running a checker process. The tablet is likely lagging in replication.
    • 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.
    • idle – An idle vttablet that does not have a keyspace, shard or type assigned
    • lag – A slaved copy of data intentionally lagged for pseudo-backup.
    • lag_orphan – A tablet in the midst of a reparenting process. During that process, the tablet goes into a lag_orphan state until it is reparented properly.
    • 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 has not been in the replication graph and is restoring from a snapshot. Typically, a tablet progresses from the idle state to the restore state and then to the spare state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is not applying a schema change. Following the change, the tablet will revert to its serving type.
    • scrap – A tablet that contains data that needs to be wiped.
    • 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.

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.

RunHealthCheck

Runs a health check on a remote tablet with the specified target type.

Example

RunHealthCheck <tablet alias> <target tablet type>

Arguments

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

  • <target 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)
    • checker – A tablet that is running a checker process. The tablet is likely lagging in replication.
    • 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.
    • idle – An idle vttablet that does not have a keyspace, shard or type assigned
    • lag – A slaved copy of data intentionally lagged for pseudo-backup.
    • lag_orphan – A tablet in the midst of a reparenting process. During that process, the tablet goes into a lag_orphan state until it is reparented properly.
    • 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 has not been in the replication graph and is restoring from a snapshot. Typically, a tablet progresses from the idle state to the restore state and then to the spare state.
    • schema_apply – A slaved copy of data that had been serving query traffic but that is not applying a schema change. Following the change, the tablet will revert to its serving type.
    • scrap – A tablet that contains data that needs to be wiped.
    • 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.

Errors

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

ScrapTablet

Scraps a tablet.

Example

ScrapTablet [-force] [-skip-rebuild] <tablet alias>

Flags

Name Type Definition
force Boolean Changes the tablet type to scrap in ZooKeeper or etcd if a tablet is offline
skip-rebuild Boolean Skips rebuilding the shard and keyspace graph after scrapping the tablet

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 <ScrapTablet> 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>] [-vts-port <vts port>] <tablet alias>

Flags

Name Type Definition
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
vts-port Int The encrypted 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