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] [--durability-policy=policy_name] <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 #

NameTypeDefinition
forceBooleanProceeds even if the keyspace already exists
durability-policystringSpecifies the durability policy to use for the keyspace
served_fromstringSpecifies a comma-separated list of dbtype:keyspace pairs used to serve traffic
sharding_column_namestringSpecifies the column to use for sharding operations
sharding_column_typestringSpecifies 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 #

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,...] <keyspace> ...
Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients.

Flags #

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

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 #

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 #

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 #

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.

VDiff #

VDiff  -- [--source_cell=<cell>] [--target_cell=<cell>] [--tablet_types=<source_tablet_types>] [--filtered_replication_wait_time=30s] [--max_extra_rows_to_compare=1000] <keyspace.workflow>
Perform a diff of all tables in the workflow

SwitchReads #

SwitchReads  -- [--cells=c1,c2,...] [--reverse] -tablet_types={replica|rdonly} [--dry-run] <keyspace.workflow>
Switch read traffic for the specified workflow.

Notes #

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 #

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.

See Also #