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 #
| Name | Type | Definition |
|---|---|---|
| force | Boolean | Proceeds even if the keyspace already exists |
| durability-policy | string | Specifies the durability policy to use for the keyspace |
| 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.
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
v1argument 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
v1argument 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.
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 #
- 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
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 #
vtctl Keyspace Command Reference