vtctl Schema, Version, Permissions Command Reference
The following vtctl commands are available for administering Schema, Versions and Permissions.
Commands #
GetSchema #
Displays the full schema for a tablet, or just the schema for the specified tables in that tablet.
Example #
GetSchema -- [--tables=<table1>,<table2>,...] [--exclude_tables=<table1>,<table2>,...] [--include-views] <tablet alias>
Flags #
| Name | Type | Definition |
|---|---|---|
| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ |
| include-views | Boolean | Includes views in the output |
| table_names_only | Boolean | Only displays table names that match |
| tables | string | Specifies a comma-separated list of tables for which we should gather information. Each is either an exact match, or a regular expression of the form /regexp/ |
Arguments #
<tablet alias>– Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format<cell name>-<uid>.
Errors #
- The
<tablet alias>argument is required for the<GetSchema>command This error occurs if the command is not called with exactly one argument.
ReloadSchema #
Reloads the schema on a remote tablet.
Example #
ReloadSchema <tablet alias>
Arguments #
<tablet alias>– Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format<cell name>-<uid>.
Errors #
- The
<tablet alias>argument is required for the<ReloadSchema>command This error occurs if the command is not called with exactly one argument.
ReloadSchemaShard #
Reloads the schema on all the tablets in a shard.
Example #
ReloadSchemaShard -- [--concurrency=10] [--include_primary=false] <keyspace/shard>
Flags #
| Name | Type | Definition |
|---|---|---|
| concurrency | Int | How many tablets to reload in parallel |
| include_primary | Boolean | Include the primary tablet |
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<ReloadSchemaShard>command This error occurs if the command is not called with exactly one argument.
ReloadSchemaKeyspace #
Reloads the schema on all the tablets in a keyspace.
Example #
ReloadSchemaKeyspace -- [--concurrency=10] [--include_primary=false] <keyspace>
Flags #
| Name | Type | Definition |
|---|---|---|
| concurrency | Int | How many tablets to reload in parallel |
| include_primary | Boolean | Include the primary tablet(s) |
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<ReloadSchemaKeyspace>command This error occurs if the command is not called with exactly one argument.
ValidateSchemaShard #
Validates that the schema on the primary tablet matches all of the replicas.
Example #
ValidateSchemaShard -- [--exclude_tables=''] [-include-views] <keyspace/shard>
Flags #
| Name | Type | Definition |
|---|---|---|
| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ |
| include-views | Boolean | Includes views in the validation |
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<ValidateSchemaShard>command This error occurs if the command is not called with exactly one argument.
ValidateSchemaKeyspace #
Validates that the schema on the primary tablet for shard 0 matches the schema on all of the other tablets in the keyspace.
Example #
ValidateSchemaKeyspace -- [--exclude_tables=''] [--include-views] <keyspace name>
Flags #
| Name | Type | Definition |
|---|---|---|
| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ |
| include-views | Boolean | Includes views in the validation |
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<ValidateSchemaKeyspace>command This error occurs if the command is not called with exactly one argument.
ApplySchema #
Applies the schema change to the specified keyspace on all shards. The recommended method of applying schema changes is via Online DDL, which ensures migrations are non-blocking and keeps replication in sync throughout the operation. --ddl_strategy is used to instruct migrations via vreplication, gh-ost or pt-osc with optional parameters. -request_context allows the user to specify a custom request context for online DDL migrations.
Example #
ApplySchema -- [--wait_replicas_timeout=10s] [--ddl_strategy=] [--request_context= ] {--sql=<sql> || --sql-file=<filename>} <keyspace>
Flags #
| Name | Type | Definition |
|---|---|---|
| caller_id | string | Effective caller ID used for the operation and should map to an ACL name which grants this identity the necessary permissions to perform the operation (this is only necessary when strict table ACLs are used). |
| ddl_strategy | string | Online DDL strategy, compatible with @@ddl_strategy session variable (examples: 'vitess', 'pt-osc', 'gh-ost --max-load=Threads_running=100' (default "direct"). |
| request_context | string | For Only DDL, optionally supply a custom unique string used as context for the migration(s) in this command. By default a unique context is auto-generated by Vitess. |
| sql | string | A list of semicolon-delimited SQL commands. |
| sql-file | string | Identifies the file that contains the SQL commands. This file needs to exist on the server, rather than on the client. |
| wait_replicas_timeout | Duration | The amount of time to wait for replicas to receive the schema change via replication (default 10s). |
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 command<ApplySchema>command This error occurs if the command is not called with exactly one argument. - If using a file you may need to pass the absolute path.
CopySchemaShard #
Copies the schema from a source shard's primary (or a specific tablet) to a destination shard. The schema is applied directly on the primary of the destination shard, and it is propagated to the replicas through binlogs.
Example #
CopySchemaShard -- [--tables=<table1>,<table2>,...] [--exclude_tables=<table1>,<table2>,...] [--include-views] [--wait_replicas_timeout=10s] {<source keyspace/shard> || <source tablet alias>} <destination keyspace/shard>Flags #
| Name | Type | Definition |
|---|---|---|
| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ |
| include-views | Boolean | Includes views in the output |
| tables | string | Specifies a comma-separated list of tables to copy. Each is either an exact match, or a regular expression of the form /regexp/ |
| wait_replicas_timeout | Duration | The amount of time to wait for replicas to receive the schema change via replication. |
Arguments #
<source keyspace/shard>– Required. A keyspace or shard to be used as the source of the copy.<source tablet alias>– Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format<cell name>-<uid>.<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>.
Errors #
- The
<source keyspace/shard>and<destination keyspace/shard>arguments are both required for the<CopySchemaShard>command. Instead of the<source keyspace/shard>argument, you can also specify<tablet alias>which refers to a specific tablet of the shard in the source keyspace This error occurs if the command is not called with exactly 2 arguments.
ValidateVersionShard #
Validates that the version on the primary matches all of the replicas.
Example #
ValidateVersionShard <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<ValidateVersionShard>command This error occurs if the command is not called with exactly one argument.
ValidateVersionKeyspace #
Validates that the version on the primary of shard 0 matches all of the other tablets in the keyspace.
Example #
ValidateVersionKeyspace <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.
Errors #
- The
<keyspace name>argument is required for the<ValidateVersionKeyspace>command This error occurs if the command is not called with exactly one argument.
GetPermissions #
Displays the permissions for a tablet.
Example #
GetPermissions <tablet alias>
Arguments #
<tablet alias>– Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format<cell name>-<uid>.
Errors #
- The
<tablet alias>argument is required for the<GetPermissions>command This error occurs if the command is not called with exactly one argument.
ValidatePermissionsShard #
Validates that the permissions on the primary tablet match all the replicas.
Example #
ValidatePermissionsShard <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<ValidatePermissionsShard>command This error occurs if the command is not called with exactly one argument.
ValidatePermissionsKeyspace #
Validates that the permissions on the primary of shard 0 match those of all of the other tablets in the keyspace.
Example #
ValidatePermissionsKeyspace <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.
Errors #
- The
<keyspace name>argument is required for the<ValidatePermissionsKeyspace>command This error occurs if the command is not called with exactly one argument.
GetVSchema #
Displays the VTGate routing schema.
Example #
GetVSchema <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<GetVSchema>command This error occurs if the command is not called with exactly one argument.
ApplyVSchema #
Applies the VTGate routing schema to the provided keyspace. Shows the result after application.
Example #
ApplyVSchema -- {--vschema=<vschema> || --vschema_file=<vschema file> || --sql=<sql> || --sql_file=<sql file>} [--cells=c1,c2,...] [--skip_rebuild] [--dry-run]<keyspace>Flags #
| Name | Type | Definition |
|---|---|---|
| cells | string | If specified, limits the rebuild to the cells, after upload. Ignored if skipRebuild is set. |
| dry-run | Boolean | If set, do not save the altered vschema, simply echo to console. |
| skip_rebuild | Boolean | If set, do not rebuild the SrvSchema objects. |
| sql | add vindex | A vschema ddl SQL statement (e.g. add vindex, alter table t add vindex hash(id), etc) |
| sql_file | add vindex | A vschema ddl SQL statement (e.g. add vindex, alter table t add vindex hash(id), etc) |
| vschema | string | Identifies the VTGate routing schema |
| vschema_file | string | Identifies the VTGate routing schema file |
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<ApplyVSchema>command. This error occurs if the command is not called with exactly one argument. - Either the
<vschema>or<vschema>File flag must be specified when calling the<ApplyVSchema>command. - If using a file you may need to pass the absolute path.
Warnings #
- In some cases, unknown params passed to Vindexes may be accepted but reported as warnings in the command response.
GetRoutingRules #
GetRoutingRules
ApplyRoutingRules #
Applies the VSchema routing rules.
Example #
ApplyRoutingRules -- {--rules=<rules> | --rules_file=<rules_file>} [--cells=c1,c2,...] [--skip_rebuild] [--dry-run]
Flags #
| Name | Type | Definition |
|---|---|---|
| cells | string | If specified, limits the rebuild to the cells, after upload. Ignored if skip_rebuild is set. |
| dry-run | Boolean | If set, do not save the altered vschema, simply echo to console. |
| skip_rebuild | Boolean | If set, do not rebuild the SrvSchema objects. |
| rules | string | Specify rules as a string. |
| rules_file | string | Specify rules in a file. |
RebuildVSchemaGraph #
Rebuilds the cell-specific SrvVSchema from the global VSchema objects in the provided cells (or all cells if none provided).
Example #
RebuildVSchemaGraph -- [--cells=c1,c2,...]
Flags #
| Name | Type | Definition |
|---|---|---|
| cells | string | Specifies a comma-separated list of cells to look for tablets |
Errors #
<RebuildVSchemaGraph>doesn't take any arguments This error occurs if the command is not called with exactly 0 arguments.
See Also #
vtctl Schema, Version, Permissions Command Reference