vtctl Tablet Command Reference

The following vtctl commands are available for administering tablets.

Commands

InitTablet

Initializes a tablet in the topology.

Example

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

Flags

NameTypeDefinition
allow_master_overrideBooleanUse 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_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)
    • 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.
    • 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 master. Vitess also does not worry about lag for experimental tablets when reparenting.
    • master – A primary copy of data
    • rdonly – A replicated copy of data for OLAP load patterns
    • replica – A replicated copy of data ready to be promoted to master
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • spare – A replicated 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.

GetTablet

Outputs a JSON structure that contains information about the Tablet.

Example

GetTablet <tablet alias>

Arguments

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

Errors

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

IgnoreHealthError

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

Example

IgnoreHealthError <tablet alias> <ignore regexp>

Arguments

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

Errors

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

UpdateTabletAddrs

Updates the IP address and port numbers of a tablet.

Example

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

Flags

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_master] <tablet alias> ...

Flags

NameTypeDefinition
allow_masterBooleanAllows for the master tablet of a shard to be deleted. Use with caution.

Arguments

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

Errors

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

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

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)
    • 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.
    • 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 master. Vitess also does not worry about lag for experimental tablets when reparenting.
    • master – A primary copy of data
    • rdonly – A replicated copy of data for OLAP load patterns
    • replica – A replicated copy of data ready to be promoted to master
    • restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
    • spare – A replicated 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 <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.

IgnoreHealthError

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

Example

IgnoreHealthError <tablet alias> <ignore regexp>

Arguments

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

Errors

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

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

NameTypeDefinition
concurrencyIntSpecifies the number of compression/checksum jobs to run simultaneously

Arguments

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

Errors

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

ChangeSlaveType

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

NOTE: This command automatically updates the serving graph.

Example

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

Flags

NameTypeDefinition
dry-runBooleanLists the proposed change without actually executing it

RestoreFromBackup

Stops mysqld and restores the data from the latest backup.

Example

RestoreFromBackup <tablet alias>

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