vtctl Tablet Command Reference

The following vtctl commands are available for administering tablets.

Commands #

InitTablet #

Deprecated. It is no longer necessary to run this command to initialize a tablet's record in the topology. Starting up a vttablet ensures that the tablet record is eventually published.

Example #

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

Flags #

NameTypeDefinition
allow_master_overrideBooleanUse this flag to force initialization if a tablet is created as primary, and a primary for the keyspace/shard already exists. Use with caution.
allow_updateBooleanUse this flag to force initialization if a tablet with the same name already exists. Use with caution.
db_name_overridestringOverrides the name of the database that the vttablet uses
grpc_portIntThe gRPC port for the vttablet process
hostnamestringThe server on which the tablet is running
keyspacestringThe keyspace to which this tablet belongs
mysql_hoststringThe mysql host for the mysql server
mysql_portIntThe mysql port for the mysql server
parentBooleanCreates the parent shard and keyspace if they don't yet exist
portIntThe main port for the vttablet process
shardstringThe shard to which this tablet belongs
tagsstringA comma-separated list of key:value pairs that are used to tag the tablet

Arguments #

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

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

    • backup – A replicated copy of data that is offline to queries other than for backup purposes
    • batch – A replicated copy of data for OLAP load patterns (typically for MapReduce jobs)
    • experimental – A replicated 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 primary. Vitess also does not worry about lag for experimental tablets when reparenting.
    • primary – A primary copy of data
    • master – Deprecated, same as primary
    • rdonly – A replicated copy of data for OLAP load patterns
    • replica – A replicated copy of data ready to be promoted to primary
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • spare – A replicated copy of data that is ready but not serving query traffic. The data could be a potential primary 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.

GetTablet #

Outputs a JSON structure that contains information about the Tablet.

Example #

GetTablet <tablet alias>

Arguments #

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

Errors #

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

IgnoreHealthError #

Deprecated.

UpdateTabletAddrs #

Deprecated. Updates the IP address and port numbers of a tablet.

Example #

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

Flags #

NameTypeDefinition
grpc-portIntThe gRPC port for the vttablet process
hostnamestringThe fully qualified host name of the server on which the tablet is running.
mysql-portIntThe mysql port for the mysql daemon
mysql_hoststringThe mysql host for the mysql server
vt-portIntThe main port for the vttablet process

Arguments #

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

Errors #

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

DeleteTablet #

Deletes tablet(s) from the topology.

Example #

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

Flags #

NameTypeDefinition
allow_primaryBooleanAllows for the primary tablet of a shard to be deleted. Use with caution.

Arguments #

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

Errors #

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

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

StartReplication #

Starts replication on the specified tablet.

Example #

StartReplication <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 <StartReplication> requires <tablet alias> This error occurs if the command is not called with exactly one argument.
  • failed reading tablet %v: %v

StopReplication #

Stops replication on the specified tablet.

Example #

StopReplication <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 <StopReplication> requires <tablet alias> This error occurs if the command is not called with exactly one argument.
  • failed reading tablet %v: %v

ChangeTabletType #

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

NOTE: This command automatically updates the serving graph.

Example #

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

Flags #

NameTypeDefinition
dry-runBooleanLists the proposed change without actually executing it

Arguments #

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

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

    • backup – A replicated copy of data that is offline to queries other than for backup purposes
    • batch – A replicated copy of data for OLAP load patterns (typically for MapReduce jobs)
    • experimental – A replicated 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 primary. Vitess also does not worry about lag for experimental tablets when reparenting.
    • primary – A primary copy of data
    • master – Deprecated, same as primary
    • rdonly – A replicated copy of data for OLAP load patterns
    • replica – A replicated copy of data ready to be promoted to primary
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • spare – A replicated copy of data that is ready but not serving query traffic. The data could be a potential primary tablet.

Errors #

  • the <tablet alias> and <db type> arguments are required for the <ChangeTabletType> 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

Ping #

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

RefreshStateByShard #

Runs 'RefreshState' on all tablets in the given shard.

Example #

RefreshStateByShard -- [--cells=c1,c2,...] <keyspace/shard>

Flags #

NameTypeDefinition
cellsstringSpecifies a comma-separated list of cells whose tablets are included. If empty, all cells are considered.

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

RunHealthCheck #

Runs a health check on a remote tablet.

Example #

RunHealthCheck <tablet alias>

Arguments #

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

Errors #

  • the <tablet alias> argument is required for the <RunHealthCheck> command This error occurs if the command is not called with exactly one argument.
  • this only reports an error if a "healthcheck" RPC call to a vttablet fails. It is only useful as a connectivity and vttablet liveness check.

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.

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.

ExecuteFetchAsApp #

ExecuteFetchAsApp -- [--max_rows=10000] [--json] [--use_pool] <tablet alias> <sql command>

ExecuteFetchAsDba #

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

Example #

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

Flags #

NameTypeDefinition
disable_binlogsBooleanDisables writing to binlogs during the query
jsonBooleanOutput JSON instead of human-readable table
max_rowsIntSpecifies the maximum number of rows to allow in reset
reload_schemaBooleanIndicates whether the tablet schema will be reloaded after executing the SQL command. The default value is false, which indicates that the tablet schema will not be reloaded.

Arguments #

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

Errors #

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

VReplicationExec #

VReplicationExec -- [--json] <tablet alias> <sql command>

Backup #

Stops mysqld and uses the BackupEngine to generate a new backup and uses the BackupStorage service to store the results. 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] [--upgrade-safe=false] <tablet alias>

Flags #

NameTypeDefinition
concurrencyIntSpecifies the number of compression/checksum jobs to run simultaneously
upgrade-safeBooleanWhether to use innodb_fast_shutdown=0 for the backup so it is safe to use for MySQL upgrades

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.

RestoreFromBackup #

Stops mysqld and restores the data from the latest backup.

Example #

RestoreFromBackup -- [--backup_timestamp=2021-09-24.021828] <tablet alias>

Flags #

NameTypeDefinition
backup_timestampStringUse the latest backup at or before this time -- in yyyy-MM-dd.HHmmss format -- rather than using the most recent backup (Vitess 12.0+)

Errors #

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

ReparentTablet #

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

Example #

ReparentTablet <tablet alias>

Errors #

  • action <ReparentTablet> requires <tablet alias> This error occurs if the command is not called with exactly one argument.
  • active reparent commands disabled (unset the -disable_active_reparents flag to enable)

See Also #

vtctl Tablet Command Reference