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

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

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 corrupted MoveTables action. 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 errantly blocked. To remove the tabletControls for selected tables, use the remove flag. 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

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

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

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

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

This command has been deprecated. Please use PlannedReparentShard instead.

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.

Example

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

Flags

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

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

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

See Also

• vtctl command index