vtctl Keyspace Command Reference
The following vtctl
commands are available for administering Keyspaces.
Commands #
CreateKeyspace #
Creates the specified keyspace.
Example #
CreateKeyspace [-sharding_column_name=name] [-sharding_column_type=type] [-served_from=tablettype1:ks1,tablettype2,ks2,...] [-force] <keyspace name> Creates the specified keyspace. keyspace_type can be NORMAL or SNAPSHOT. For a SNAPSHOT keyspace you must specify the name of a base_keyspace, and a snapshot_time in UTC, in RFC3339 time format, e.g. 2006-01-02T15:04:05+00:00
Flags #
Name | Type | Definition |
---|---|---|
force | Boolean | Proceeds even if the keyspace already exists |
served_from | string | Specifies a comma-separated list of dbtype:keyspace pairs used to serve traffic |
sharding_column_name | string | Specifies the column to use for sharding operations |
sharding_column_type | string | Specifies the type of the column to use for sharding operations |
Arguments #
<keyspace name>
– Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
Errors #
- the
<keyspace name>
argument is required for the<CreateKeyspace>
command This error occurs if the command is not called with exactly one argument.
DeleteKeyspace #
Deletes the specified keyspace. In recursive mode, it also recursively deletes all shards in the keyspace. Otherwise, there must be no shards left in the keyspace.
Example #
DeleteKeyspace [-recursive] <keyspace> Deletes the specified keyspace. In recursive mode, it also recursively deletes all shards in the keyspace. Otherwise, there must be no shards left in the keyspace.
Flags #
Name | Type | Definition |
---|---|---|
recursive | Boolean | Also recursively delete all shards in the keyspace. |
Arguments #
<keyspace>
– Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
Errors #
- must specify the
<keyspace>
argument for<DeleteKeyspace>
This error occurs if the command is not called with exactly one argument.
RemoveKeyspaceCell #
Removes the cell from the Cells list for all shards in the keyspace, and the SrvKeyspace for that keyspace in that cell.
Example #
RemoveKeyspaceCell [-force] [-recursive] <keyspace> <cell> Removes the cell from the Cells list for all shards in the keyspace, and the SrvKeyspace for that keyspace in that cell.
Flags #
Name | Type | Definition |
---|---|---|
force | Boolean | Proceeds 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. |
recursive | Boolean | Also delete all tablets in that cell belonging to the specified keyspace. |
Arguments #
<keyspace>
– Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.<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>
and<cell>
arguments are required for the<RemoveKeyspaceCell>
command This error occurs if the command is not called with exactly 2 arguments.
GetKeyspace #
Outputs a JSON structure that contains information about the Keyspace.
Example #
GetKeyspace <keyspace> Outputs a JSON structure that contains information about the Keyspace.
Arguments #
<keyspace>
– Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
Errors #
- the
<keyspace>
argument is required for the<GetKeyspace>
command This error occurs if the command is not called with exactly one argument.
GetKeyspaces #
Outputs a sorted list of all keyspaces.
Errors #
- the
<destination keyspace/shard>
and<served tablet type>
arguments are both required for the<MigrateServedFrom>
command This error occurs if the command is not called with exactly 2 arguments.
SetKeyspaceShardingInfo #
Updates the sharding information for a keyspace.
Example #
SetKeyspaceShardingInfo [-force] <keyspace name> [<column name>] [<column type>] Updates the sharding information for a keyspace.
Flags #
Name | Type | Definition |
---|---|---|
force | Boolean | Updates fields even if they are already set. Use caution before calling this command. |
Arguments #
<keyspace name>
– Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.<column name>
– Optional.<column type>
– Optional.
Errors #
- the
<keyspace name>
argument is required for the<SetKeyspaceShardingInfo>
command. The<column name>
and<column type>
arguments are both optional This error occurs if the command is not called with between 1 and 3 arguments. - both
<column name>
and<column type>
must be set, or both must be unset
SetKeyspaceServedFrom #
Changes the ServedFromMap manually. This command is intended for emergency fixes. This field is automatically set when you call the MigrateServedFrom command. This command does not rebuild the serving graph.
Example #
SetKeyspaceServedFrom [-source=<source keyspace name>] [-remove] [-cells=c1,c2,...] <keyspace name> <tablet type> Changes the ServedFromMap manually. This command is intended for emergency fixes. This field is automatically set when you call the *MigrateServedFrom* command. This command does not rebuild the serving graph.
Flags #
Name | Type | Definition |
---|---|---|
cells | string | Specifies a comma-separated list of cells to affect |
remove | Boolean | Indicates whether to add (default) or remove the served from record |
source | string | Specifies the source keyspace name |
Arguments #
<keyspace name>
– Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.<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 purposesbatch
– 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 primary. Vitess also does not worry about lag for experimental tablets when reparenting.primary
– A primary copy of datamaster
– Deprecated, same as primaryrdonly
– A replicated copy of data for OLAP load patternsreplica
– A replicated copy of data ready to be promoted to primaryrestore
– 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 name>
and<tablet type>
arguments are required for the<SetKeyspaceServedFrom>
command This error occurs if the command is not called with exactly 2 arguments.
RebuildKeyspaceGraph #
Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients.
Example #
RebuildKeyspaceGraph [-cells=c1,c2,...] <keyspace> ... Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients.
Flags #
Name | Type | Definition |
---|---|---|
cells | string | Specifies a comma-separated list of cells to update |
Arguments #
<keyspace>
– Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. To specify multiple values for this argument, separate individual values with a space.
Errors #
- the
<keyspace>
argument must be used to specify at least one keyspace when calling the<RebuildKeyspaceGraph>
command This error occurs if the command is not called with at least one argument.
ValidateKeyspace #
Validates that all nodes reachable from the specified keyspace are consistent.
Example #
ValidateKeyspace [-ping-tablets] <keyspace name> Validates that all nodes reachable from the specified keyspace are consistent.
Flags #
Name | Type | Definition |
---|---|---|
ping-tablets | Boolean | Specifies whether all tablets will be pinged during the validation process |
Arguments #
<keyspace name>
– Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
Errors #
- the
<keyspace name>
argument is required for the<ValidateKeyspace>
command This error occurs if the command is not called with exactly one argument.
Reshard (v1) #
Reshard -v1 [-skip_schema_copy] <keyspace.workflow> <source_shards> <target_shards>
Start a Resharding process. Example: Reshard -cells='zone1,alias1' -tablet_types='primary,replica,rdonly' ks.workflow001 '0' '-80,80-'.
Notes #
- The
v1
argument is required in Vitess 11.0 and later - This command is part of the VReplication v1 workflow -- we recommend that you use the v2 workflow in Vitess 11.0 and later
Reshard (v2) #
Reshard <options> <action> <workflow identifier>
MoveTables (v1) #
MoveTables -v1 [-cell=<cell>] [-tablet_types=<source_tablet_types>] -workflow=<workflow> <source_keyspace> <target_keyspace> <table_specs>
Move table(s) to another keyspace, table_specs is a list of tables or the tables section of the vschema for the target keyspace. Example: '{"t1":{"column_vindexes": [{"column": "id1", "name": "hash"}]}, "t2":{"column_vindexes": [{"column": "id2", "name": "hash"}]}}'. In the case of an unsharded target keyspace the vschema for each table may be empty. Example: '{"t1":{}, "t2":{}}'.
Notes #
- The
v1
argument is required in Vitess 11.0 and later - This command is part of the VReplication v1 workflow -- we recommend that you use the v2 workflow in Vitess 11.0 and later
MoveTables (v2) #
MoveTables <options> <action> <workflow identifier>
DropSources #
DropSources [-dry_run] [-rename_tables] <keyspace.workflow>
After a MoveTables or Resharding workflow cleanup unused artifacts like source tables, source shards and blacklists.
Notes #
- This command is part of the VReplication v1 workflow -- we recommend that you use the v2 workflow in Vitess 11.0 and later
CreateLookupVindex #
CreateLookupVindex [-cells=<source_cells>] [-continue_after_copy_with_owner=false] [-tablet_types=<source_tablet_types>] <keyspace> <json_spec>
Create and backfill a lookup vindex. the json_spec must contain the vindex and colvindex specs for the new lookup.
ExternalizeVindex #
ExternalizeVindex <keyspace>.<vindex>
Externalize (activate) a lookup vindex backfilled using `CreateLookupVindex`.
This removes the workflow and vreplication streams associated with the
backfill, and clears the `write_only` flag on the vindex. After this flag is
removed, applications can start using the vindex for lookups.
Materialize #
Materialize <json_spec>, example : '{"workflow": "aaa", "source_keyspace": "source", "target_keyspace": "target", "table_settings": [{"target_table": "customer", "source_expression": "select * from customer", "create_ddl": "copy"}]}'
Performs materialization based on the json spec. Is used directly to form VReplication rules, with an optional step to copy table structure/DDL.
SplitClone #
SplitClone <keyspace> <from_shards> <to_shards>
Start the SplitClone process to perform horizontal resharding. Example: SplitClone ks '0' '-80,80-'
VerticalSplitClone #
VerticalSplitClone <from_keyspace> <to_keyspace> <tables>
Start the VerticalSplitClone process to perform vertical resharding. Example: SplitClone from_ks to_ks 'a,/b.*/'
VDiff #
VDiff [-source_cell=<cell>] [-target_cell=<cell>] [-tablet_types=<source_tablet_types>] [-filtered_replication_wait_time=30s] <keyspace.workflow>
Perform a diff of all tables in the workflow
MigrateServedTypes #
Migrates a serving type from the source shard to the shards that it replicates to. This command also rebuilds the serving graph. The <keyspace/shard> argument can specify any of the shards involved in the migration.
Example #
MigrateServedTypes [-cells=c1,c2,...] [-reverse] [-skip-refresh-state] <keyspace/shard> <served tablet type> Migrates a serving type from the source shard to the shards that it replicates to. This command also rebuilds the serving graph. Theargument can specify any of the shards involved in the migration.
Flags #
Name | Type | Definition |
---|---|---|
cells | string | Specifies a comma-separated list of cells to update |
filtered_replication_wait_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on primary migrations |
reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble |
skip-refresh-state | Boolean | Skips refreshing the state of the source tablets after the migration, meaning that the refresh will need to be done manually, replica and rdonly only) |
reverse_replication | Boolean | For primary migration, enabling this flag reverses replication which allows you to rollback |
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>
.<served 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 purposesbatch
– 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 primary. Vitess also does not worry about lag for experimental tablets when reparenting.primary
– A primary copy of datamaster
– Deprecated, same as primaryrdonly
– A replicated copy of data for OLAP load patternsreplica
– A replicated copy of data ready to be promoted to primaryrestore
– 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
<source keyspace/shard>
and<served tablet type>
arguments are both required for the<MigrateServedTypes>
command This error occurs if the command is not called with exactly 2 arguments. - the
<skip-refresh-state>
flag can only be specified for non-primary migrations
MigrateServedFrom #
Makes the <destination keyspace/shard> serve the given type. This command also rebuilds the serving graph.
Example #
MigrateServedFrom [-cells=c1,c2,...] [-reverse] <destination keyspace/shard> <served tablet type>
Flags #
Name | Type | Definition |
---|---|---|
cells | string | Specifies a comma-separated list of cells to update |
filtered_replication_wait_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on primary migrations |
reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble |
Arguments #
<destination 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>
.<served 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 purposesbatch
– 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 primary. Vitess also does not worry about lag for experimental tablets when reparenting.primary
– A primary copy of datamaster
– Deprecated, same as primaryrdonly
– A replicated copy of data for OLAP load patternsreplica
– A replicated copy of data ready to be promoted to primaryrestore
– 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
<destination keyspace/shard>
and<served tablet type>
arguments are both required for the<MigrateServedFrom>
command This error occurs if the command is not called with exactly 2 arguments.
SwitchReads #
SwitchReads [-cells=c1,c2,...] [-reverse] -tablet_types={replica|rdonly} [-dry-run] <keyspace.workflow>
Switch read traffic for the specified workflow.
Notes #
- This command is part of the VReplication v1 workflow -- we recommend that you use the v2 workflow in Vitess 11.0 and later
SwitchWrites #
SwitchWrites [-timeout=30s] [-cancel] [-reverse] [-reverse_replication=false] -tablet_types={replica|rdonly} [-dry-run] <keyspace.workflow>
Switch write traffic for the specified workflow.
Notes #
- This command is part of the VReplication v1 workflow -- we recommend that you use the v2 workflow in Vitess 11.0 and later
CancelResharding #
Permanently cancels a resharding in progress. All resharding related metadata will be deleted.
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>
.
ShowResharding #
Displays all metadata about a resharding in progress.
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>
.
FindAllShardsInKeyspace #
Displays all of the shards in the specified keyspace.
Example #
FindAllShardsInKeyspace <keyspace> Displays all of the shards in the specified keyspace.
Arguments #
<keyspace>
– Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
Errors #
- the
<keyspace>
argument is required for the<FindAllShardsInKeyspace>
command This error occurs if the command is not called with exactly one argument.
WaitForDrain #
Blocks until no new queries were observed on all tablets with the given tablet type in the specified keyspace. This can be used as sanity check to ensure that the tablets were drained after running vtctl MigrateServedTypes and vtgate is no longer using them. If -timeout is set, it fails when the timeout is reached.
Example #
WaitForDrain [-timeout <duration>] [-retry_delay <duration>] [-initial_wait <duration>] <keyspace/shard> <served tablet type> Blocks until no new queries were observed on all tablets with the given tablet type in the specified keyspace. This can be used as sanity check to ensure that the tablets were drained after running vtctl MigrateServedTypes and vtgate is no longer using them. If -timeout is set, it fails when the timeout is reached."
Flags #
Name | Type | Definition |
---|---|---|
cells | string | Specifies a comma-separated list of cells to look for tablets |
initial_wait | Duration | Time to wait for all tablets to check in |
retry_delay | Duration | Time to wait between two checks |
timeout | Duration | Timeout after which the command fails |
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>
.<served 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 purposesbatch
– 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 primary. Vitess also does not worry about lag for experimental tablets when reparenting.primary
– A primary copy of datamaster
– Deprecated, same as primaryrdonly
– A replicated copy of data for OLAP load patternsreplica
– A replicated copy of data ready to be promoted to primaryrestore
– 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<WaitForDrain>
command This error occurs if the command is not called with exactly 2 arguments.