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_type=type] [--base_keyspace=base_keyspace] [--snapshot_time=time] [--durability-policy=policy_name] [--sidecar-db-name=db_name] <keyspace name> 

Flags #

NameTypeDefinition
allow_empty_vschemaBooleanIf set this will allow a new keyspace to have no vschema
base_keyspaceBooleanSpecifies the base keyspace for a snapshot keyspace type
durability-policyStringSpecifies the durability policy to use for the keyspace
forceBooleanProceeds even if the keyspace already exists
keyspace_typeStringSpecifies the type of the keyspace. It 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
sharding_column_nameStringSpecifies the column to use for sharding operations
sharding_column_typeStringSpecifies the type of the column to use for sharding operations
sidecar-db-nameString(Experimental) Specifies the name of the Vitess sidecar database that tablets in this keyspace will use for internal metadata
served_fromStringSpecifies a comma-separated list of dbtype:keyspace pairs used to serve traffic
snapshot_timeStringSpecifies the snapshot time for this keyspace

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 #

NameTypeDefinition
recursiveBooleanAlso 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 #

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

RebuildKeyspaceGraph #

Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients.

Example #

RebuildKeyspaceGraph -- [--cells=c1,c2,...] [--allow_partial] <keyspace> ...
Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients.

Flags #

NameTypeDefinition
allow_partialBooleanSpecifies whether a SNAPSHOT keyspace is allowed to serve with an incomplete set of shards. Ignored for all other types of keyspaces
cellsStringSpecifies 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 #

NameTypeDefinition
ping-tabletsBooleanSpecifies 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.

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.

Reshard #

Start a Resharding process. Example: Reshard --cells='zone1,alias1' --tablet_types='PRIMARY,REPLICA,RDONLY' ks.workflow001 -- '0' '-80,80-'

Example #

Reshard -- [--source_shards=<source_shards>] [--target_shards=<target_shards>] [--cells=<cells>] [--tablet_types=<source_tablet_types>] [--on-ddl=<ddl-action>] [--skip_schema_copy] <action> <keyspace.workflow> 

Flags #

NameTypeDefinition
allBooleanMoveTables only. Move all tables from the source keyspace. Either table_specs or --all needs to be specified.
auto_startBooleanIf false, streams will start in the Stopped state and will need to be explicitly started (default true)
cellsStringCell(s) or CellAlias(es) (comma-separated) to replicate from.
drop_foreign_keysBooleanIf true, tables in the target keyspace will be created without foreign keys.
dry_runBooleanDoes a dry run of SwitchTraffic and only reports the actions to be taken. --dry_run is only supported for SwitchTraffic, ReverseTraffic and Complete.
excludeStringMoveTables only. Tables to exclude (comma-separated) if --all is specified
keep_dataBooleanDo not drop tables or shards (if true, only vreplication artifacts are cleaned up). --keep_data is only supported for Complete and Cancel.
keep_routing_rulesBooleanDo not remove the routing rules for the source keyspace. --keep_routing_rules is only supported for Complete and Cancel.
max_replication_lag_allowedDurationAllow traffic to be switched only if vreplication lag is below this (in seconds) (default 30s)
on-ddlStringWhat to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE. (default "IGNORE")
rename_tablesBooleanMoveTables only. Rename tables instead of dropping them. --rename_tables is only supported for Complete.
reverse_replicationBooleanAlso reverse the replication (default true). --reverse_replication is only supported for SwitchTraffic. (default true)
skip_schema_copyBooleanReshard only. Skip copying of schema to target shards
sourceStringMoveTables only. Source keyspace
source_shardsStringSource shards
source_time_zoneStringMoveTables only. Specifying this causes any DATETIME fields to be converted from given time zone into UTC
stop_after_copyBooleanStreams will be stopped once the copy phase is completed
tablesStringMoveTables only. A table spec or a list of tables. Either table_specs or --all needs to be specified.
tablet_typesStringSource tablet types to replicate from (e.g. PRIMARY, REPLICA, RDONLY). Note: SwitchTraffic overrides this default and uses in_order:RDONLY,REPLICA,PRIMARY to switch all traffic by default. (default "in_order:REPLICA,PRIMARY")
target_shardsStringReshard only. Target shards
timeoutDurationSpecifies the maximum time to wait, in seconds, for vreplication to catch up on primary migrations. The migration will be cancelled on a timeout. --timeout is only supported for SwitchTraffic and ReverseTraffic. (default 30s)

Arguments #

  • <action> - Required. Action must be one of the following: Create, Complete, Cancel, SwitchTraffic, ReverseTrafffic, Show, or Progress.
  • <keyspace.workflow> - Required. The name of the keyspace and workflow to be used for the resharding process. The argument value must be a string that does not contain whitespace.

MoveTables #

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":{}
}

Example #

MoveTables [--source=<sourceKs>] [--tables=<tableSpecs>] [--cells=<cells>] [--tablet_types=<source_tablet_types>] [--all] [--exclude=<tables>] [--auto_start] [--stop_after_copy] [--on-ddl=<ddl-action>] [--source_shards=<source_shards>] <action> <targetKs.workflow> 

Flags #

NameTypeDefinition
allBooleanMoveTables only. Move all tables from the source keyspace. Either table_specs or --all needs to be specified.
auto_startBooleanIf false, streams will start in the Stopped state and will need to be explicitly started (default true)
cellsStringCell(s) or CellAlias(es) (comma-separated) to replicate from.
drop_foreign_keysBooleanIf true, tables in the target keyspace will be created without foreign keys.
dry_runBooleanDoes a dry run of SwitchTraffic and only reports the actions to be taken. --dry_run is only supported for SwitchTraffic, ReverseTraffic and Complete.
excludeStringMoveTables only. Tables to exclude (comma-separated) if --all is specified
keep_dataBooleanDo not drop tables or shards (if true, only vreplication artifacts are cleaned up). --keep_data is only supported for Complete and Cancel.
keep_routing_rulesBooleanDo not remove the routing rules for the source keyspace. --keep_routing_rules is only supported for Complete and Cancel.
max_replication_lag_allowedDurationAllow traffic to be switched only if vreplication lag is below this (in seconds) (default 30s)
on-ddlStringWhat to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE. (default "IGNORE")
rename_tablesBooleanMoveTables only. Rename tables instead of dropping them. --rename_tables is only supported for Complete.
reverse_replicationBooleanAlso reverse the replication (default true). --reverse_replication is only supported for SwitchTraffic. (default true)
skip_schema_copyBooleanReshard only. Skip copying of schema to target shards
sourceStringMoveTables only. Source keyspace
source_shardsStringSource shards
source_time_zoneStringMoveTables only. Specifying this causes any DATETIME fields to be converted from given time zone into UTC
stop_after_copyBooleanStreams will be stopped once the copy phase is completed
tablesStringMoveTables only. A table spec or a list of tables. Either table_specs or --all needs to be specified.
tablet_typesStringSource tablet types to replicate from (e.g. PRIMARY, REPLICA, RDONLY). Note: SwitchTraffic overrides this default and uses in_order:RDONLY,REPLICA,PRIMARY to switch all traffic by default. (default "in_order:REPLICA,PRIMARY")
target_shardsStringReshard only. Target shards
timeoutDurationSpecifies the maximum time to wait, in seconds, for vreplication to catch up on primary migrations. The migration will be cancelled on a timeout. --timeout is only supported for SwitchTraffic and ReverseTraffic. (default 30s)

Arguments #

  • <action> - Required. Action must be one of the following: Create, Complete, Cancel, SwitchTraffic, ReverseTrafffic, Show, or Progress.
  • <keyspace.workflow> - Required. The name of the keyspace and workflow to be used for the resharding process. The argument value must be a string that does not contain whitespace.

CreateLookupVindex #

Create and backfill a lookup vindex. the json_spec must contain the vindex and colvindex specs for the new lookup.

Example #

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.

Flags #

NameTypeDefinition
cellsStringSource cells to replicate from.
continue_after_copy_with_ownerBooleanVindex will continue materialization after copy when an owner is provided
tablet_typesStringSource tablet types to replicate from.

Arguments #

  • <keyspace> - Required. The name of the keyspace where lookup vindex needs to be created.
  • <json_spec> - Required. json specification about how to create the lookup vindex. More information in user-guides

ExternalizeVindex #

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.

Example #

ExternalizeVindex <keyspace>.<vindex>

Materialize #

Performs materialization based on the json spec. Is used directly to form VReplication rules, with an optional step to copy table structure/DDL.

Example #

Materialize -- [--cells=<cells>] [--tablet_types=<source_tablet_types>] <json_spec>

Flags #

NameTypeDefinition
cellsStringSource cells to replicate from.
tablet_typesStringSource tablet types to replicate from.

Argument #

  • <json_spec> - Required.

Example:

{
  "workflow": "aaa", 
  "source_keyspace": "source", 
  "target_keyspace": "target", 
  "table_settings": [{
    "target_table": "customer", 
    "source_expression": "select * from customer", 
    "create_ddl": "copy"}]
}

VDiff #

Perform a diff of all tables in the workflow

Example #

VDiff -- [--source_cell=<cell>] [--target_cell=<cell>] [--tablet_types=in_order:RDONLY,REPLICA,PRIMARY] [--limit=<max rows to diff>] [--tables=<table list>] [--format=json] [--auto-retry] [--verbose] [--max_extra_rows_to_compare=1000] [--filtered_replication_wait_time=30s] [--debug_query] [--only_pks] [--wait] [--wait-update-interval=1m] <keyspace.workflow> [<action>] [<UUID>]

Flags #

NameTypeDefinition
auto-retryBooleanShould this vdiff automatically retry and continue in case of recoverable errors (default true)
checksumBooleanUse row-level checksums to compare, not yet implemented
debug_queryBooleanAdds a mysql query to the report that can be used for further debugging
filtered_replication_wait_timeDurationSpecifies the maximum time to wait, in seconds, for filtered replication to catch up on primary migrations. The migration will be cancelled on a timeout. (default 30s)
formatStringFormat of report (default "text")
limitIntMax rows to stop comparing after (default 9223372036854775807)
max_extra_rows_to_compareIntIf there are collation differences between the source and target, you can have rows that are identical but simply returned in a different order from MySQL. We will do a second pass to compare the rows for any actual differences in this case and this flag allows you to control the resources used for this operation. (default 1000)
only_pksBooleanWhen reporting missing rows, only show primary keys in the report.
sample_pctIntHow many rows to sample, not yet implemented (default 100)
source_cellStringThe source cell to compare from; default is any available cell
tablesStringOnly run vdiff for these tables in the workflow
tablet_typesStringTablet types for source (PRIMARY is always used on target) (default "in_order:RDONLY,REPLICA,PRIMARY")
target_cellStringThe target cell to compare with; default is any available cell
v1BooleanUse legacy VDiff v1
verboseBooleanShow verbose vdiff output in summaries
waitBooleanWhen creating or resuming a vdiff, wait for it to finish before exiting
wait-update-intervalDurationWhen waiting on a vdiff to finish, check and display the current status this often (default 1m0s)

See Also #