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 primary vttablet and the replica vttablet. In Vitess, data is always written to the primary 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.

SetShardIsPrimaryServing #

SetShardIsPrimaryServing <keyspace/shard> <is_serving>

SetShardTabletControl #

Sets the shardTabletControls or the tabletControls records for a shard and tablet type in the topology service. Only use this for an emergency fix or after a finished vertical split or after a corrupted MoveTables action. The MigrateServedFrom and MigrateServedType commands set this field appropriately already. Always specify the denied_tables flag for MoveTables, but never for Reshard operations.

To set the queryServiceDisabled for the tablet, set disable_query_service to true; to unset the queryServiceDisabled provide denied_tables with an empty table set. Useful to fix vReplication operations gone wrong. These specific flags update the values for shardTabletControls in the topology path: /keyspaces/<keyspace>/SrvKeyspace.

It is important to note here the queryServiceDisabled can not be removed by disable_query_service=false or the remove flags. Only denied_tables="" will remove this setting.

To change the deniedTables list, specify the denied_tables parameter with the new list, this is useful to fix tables that are being blocked after a vertical split. To remove the tabletControls for selected tables, use the remove flag, useful after a vertical split is finished to remove serving restrictions. These specific flags update the values for tabletControls in the topology path: /keyspaces/<keyspace>/shards/<shard>/Shard.

The SetShardTabletControl only updates the topology records for a given shard and type, you still need to run RefreshStateByShard to inform the vttablets of the topology change.

Examples #

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

Disable serving of the listed tables for the selected keyspace/shard and tablet type:

SetShardTabletControl -- [--denied_tables=t1,t2,...] <keyspace/shard> <tablet type>

RefreshStateByShard <keyspace/shard>

Serve all tables for the selected keyspace/shard and tablet type:

SetShardTabletControl -- --remove <keyspace/shard> <tablet type>

RefreshStateByShard <keyspace/shard>

Disable serving for the selected keyspace/shard and tablet type:

SetShardTabletControl -- --disable_query_service=true <keyspace/shard> <tablet type>

RefreshStateByShard <keyspace/shard>

Enable serving for the selected keyspace/shard and tablet type:

SetShardTabletControl -- --denied_tables="" <keyspace/shard> <tablet type>

RefreshStateByShard <keyspace/shard>

Flags #

NameTypeDefinition
denied_tablesstringSpecifies a comma-separated list of tables to deny queries on (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 'denied_tables' and 'remove' to be unset, otherwise it's ignored.
removeBooleanRemoves cells for MoveTables.

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

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

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_primary=false] <keyspace/shard>

RemoveBackup #

Removes a backup from 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.

InitShardPrimary #

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

Example #

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

Flags #

NameTypeDefinition
forceBooleanwill force the reparent even if the provided tablet is not writable or the shard primary
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 <InitShardPrimary> 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 primary that can either be explicitly specified, or chosen by Vitess. Both the existing primary and new primary need to be up and running to use this command. If the existing primary for the shard is down, you should use EmergencyReparentShard instead.

If the new_primary flag is not provided, Vitess will try to automatically choose a replica to promote to primary, avoiding any replicas specified in the avoid_tablet flag, if provided. Note that Vitess will not consider any replicas outside the cell the current primary is in for promotion, therefore you must pass the new_primary flag if you need to promote a replica in a different cell from the primary. 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_primary=<tablet alias>] [--avoid_tablet=<tablet alias>]

Flags #

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

Errors #

  • action <PlannedReparentShard> requires --keyspace_shard=<keyspace/shard> [--new_primary=<tablet alias>] [--avoid_tablet=<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_primary> for action <PlannedReparentShard> at the same time

EmergencyReparentShard #

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

Example #

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

Flags #

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

Errors #

  • action <EmergencyReparentShard> requires --keyspace_shard=<keyspace/shard> --new_primary=<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_primary> for action <EmergencyReparentShard> at the same time

TabletExternallyReparented #

Changes metadata in the topology service to acknowledge a shard primary 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 to promote to primary. 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.

GenerateShardRanges #

Generates shard ranges assuming a keyspace with N shards.

Example #

GenerateShardRanges -- --num_shards=<N>

Flags #

NameTypeDefinition
num_shardsintNumber of shards to generate shard ranges for. (default 2)

See Also #

vtctl Shard Command Reference