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 #

NameTypeDefinition
exclude_tablesstringSpecifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/
include-viewsBooleanIncludes views in the output
table_names_onlyBooleanOnly displays table names that match
tablesstringSpecifies 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 #

NameTypeDefinition
concurrencyIntHow many tablets to reload in parallel
include_primaryBooleanInclude 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 #

NameTypeDefinition
concurrencyIntHow many tablets to reload in parallel
include_primaryBooleanInclude 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 #

NameTypeDefinition
exclude_tablesstringSpecifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/
include-viewsBooleanIncludes 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 #

NameTypeDefinition
exclude_tablesstringSpecifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/
include-viewsBooleanIncludes 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 #

NameTypeDefinition
caller_idstringEffective 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_strategystringOnline DDL strategy, compatible with @@ddl_strategy session variable (examples: 'vitess', 'pt-osc', 'gh-ost --max-load=Threads_running=100' (default "direct").
request_contextstringFor 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.
sqlstringA list of semicolon-delimited SQL commands.
sql-filestringIdentifies the file that contains the SQL commands. This file needs to exist on the server, rather than on the client.
wait_replicas_timeoutDurationThe 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 #

NameTypeDefinition
exclude_tablesstringSpecifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/
include-viewsBooleanIncludes views in the output
tablesstringSpecifies a comma-separated list of tables to copy. Each is either an exact match, or a regular expression of the form /regexp/
wait_replicas_timeoutDurationThe 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 #

NameTypeDefinition
cellsstringIf specified, limits the rebuild to the cells, after upload. Ignored if skipRebuild is set.
dry-runBooleanIf set, do not save the altered vschema, simply echo to console.
skip_rebuildBooleanIf set, do not rebuild the SrvSchema objects.
sqladd vindexA vschema ddl SQL statement (e.g. add vindex, alter table t add vindex hash(id), etc)
sql_fileadd vindexA vschema ddl SQL statement (e.g. add vindex, alter table t add vindex hash(id), etc)
vschemastringIdentifies the VTGate routing schema
vschema_filestringIdentifies 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 #

NameTypeDefinition
cellsstringIf specified, limits the rebuild to the cells, after upload. Ignored if skip_rebuild is set.
dry-runBooleanIf set, do not save the altered vschema, simply echo to console.
skip_rebuildBooleanIf set, do not rebuild the SrvSchema objects.
rulesstringSpecify rules as a string.
rules_filestringSpecify 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 #

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