vtctl Shard Command Reference

The following vtctl commands are available for administering shards.

Commands

CreateShard

Creates the specified shard.

Example

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

Flags

NameTypeDefinition
forceBooleanProceeds with the command even if the keyspace already exists
parentBooleanCreates 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 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 <CreateShard> command This error occurs if the command is not called with exactly 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 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 <GetShard> 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

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

ShardReplicationPositions

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

Example

ShardReplicationPositions <keyspace/shard>

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain 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 <ShardReplicationPositions> 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 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 <ListShardTablets> command This error occurs if the command is not called with exactly one argument.

SetShardIsMasterServing

SetShardIsMasterServing <keyspace/shard> <is_master_serving>

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.

To set the DisableQueryServiceFlag, keep ‘blacklisted_tables’ empty, and set ‘disable_query_service’ to true or false. Useful to fix horizontal splits gone wrong.

To change the blacklisted tables list, specify the ‘blacklisted_tables’ parameter with the new list. Useful to fix tables that are being blocked after a vertical split.

To just remove the ShardTabletControl entirely, use the ‘remove’ flag, useful after a vertical split is finished to remove serving restrictions.

Example

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

Flags

NameTypeDefinition
blacklisted_tablesstringSpecifies a comma-separated list of tables to blacklist (used for vertical split). Each is either an exact match, or a regular expression of the form ‘/regexp/'.
cellsstringSpecifies a comma-separated list of cells to update
disable_query_serviceBooleanDisables query service on the provided nodes. This flag requires ‘blacklisted_tables’ and ‘remove’ to be unset, otherwise it’s ignored.
removeBooleanRemoves cells for vertical splits.

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

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

UpdateSrvKeyspacePartition

UpdateSrvKeyspacePartition [--cells=c1,c2,...] [--remove] <keyspace/shard> <tablet type>

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

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

NameTypeDefinition
key_rangestringIdentifies the key range to use for the SourceShard
tablesstringSpecifies a comma-separated list of tables to replicate (used for vertical split). Each is either an exact match, or a regular expression of the form /regexp/

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>.
  • <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 whitespace, 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.

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

WaitForFilteredReplication

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

Example

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

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain 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 <WaitForFilteredReplication> command This error occurs if the command is not called with exactly one argument.

RemoveShardCell

Removes the cell from the shard’s Cells list.

Example

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

Flags

NameTypeDefinition
forceBooleanProceeds even if the cell’s topology service cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data.
recursiveBooleanAlso delete all tablets in that cell belonging to the specified shard.

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, 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.

DeleteShard

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

Example

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

Flags

NameTypeDefinition
even_if_servingBooleanRemove the shard even if it is serving. Use with caution.
recursiveBooleanAlso delete all tablets belonging to the shard.

Arguments

  • <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, 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.

ListBackups

Lists all the backups for a shard.

Example

ListBackups <keyspace/shard>

Errors

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

BackupShard

BackupShard [-allow_master=false] <keyspace/shard>

RemoveBackup

Removes a backup for the BackupStorage.

Example

RemoveBackup <keyspace/shard> <backup name>

Arguments

  • <backup name> – Required.

Errors

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

InitShardMaster

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

Example

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

Flags

NameTypeDefinition
forceBooleanwill force the reparent even if the provided tablet is not a master or the shard master
wait_replicas_timeoutDurationtime to wait for replicas to catch up in reparenting

Arguments

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

Errors

  • action <InitShardMaster> requires <keyspace/shard> <tablet alias> This error occurs if the command is not called with exactly 2 arguments.
  • active reparent commands disabled (unset the -disable_active_reparents flag to enable)

PlannedReparentShard

Reparents the shard to a new master that can either be explicitly specified, or chosen by Vitess. Both the existing master and new master need to be up and running to use this command. If the existing master for the shard is down, you should use EmergencyReparentShard instead.

If the new_master flag is not provided, Vitess will try to automatically choose a replica to promote to master, avoiding any replicas specified in the avoid_master flag, if provided. Note that Vitess will not consider any replicas outside the cell the current master is in for promotion, therefore you must pass the new_master flag if you need to promote a replica in a different cell from the master. In the automated selection mode Vitess will prefer the most advanced replica for promotion, to minimize failover time.

Example

PlannedReparentShard -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>]

Flags

NameTypeDefinition
avoid_masterstringalias of a tablet that should not be the master, i.e. reparent to any replica other than this one
keyspace_shardstringkeyspace/shard of the shard that needs to be reparented
new_masterstringalias of a tablet that should be the new master
wait_replicas_timeoutDurationtime to wait for replicas to catch up in reparenting

Errors

  • action <PlannedReparentShard> requires -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>] This error occurs if the command is not called with exactly 0 arguments.
  • active reparent commands disabled (unset the -disable_active_reparents flag to enable)
  • cannot use legacy syntax and flags -<keyspace_shard> and -<new_master> for action <PlannedReparentShard> at the same time

EmergencyReparentShard

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

Example

EmergencyReparentShard -keyspace_shard=<keyspace/shard> -new_master=<tablet alias>

Flags

NameTypeDefinition
keyspace_shardstringkeyspace/shard of the shard that needs to be reparented
new_masterstringalias of a tablet that should be the new master
wait_replicas_timeoutDurationtime to wait for replicas to catch up in reparenting

Errors

  • action <EmergencyReparentShard> requires -keyspace_shard=<keyspace/shard> -new_master=<tablet alias> This error occurs if the command is not called with exactly 0 arguments.
  • active reparent commands disabled (unset the -disable_active_reparents flag to enable)
  • cannot use legacy syntax and flag -<new_master> for action <EmergencyReparentShard> at the same time

TabletExternallyReparented

Changes metadata in the topology service to acknowledge a shard master change performed by an external tool. See Reparenting 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.

See Also