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 every primary, running in parallel on all shards. The changes are then propagated to replicas via replication. If -allow_long_unavailability is set, schema changes affecting a large number of rows (and possibly incurring a longer period of unavailability) will not be rejected. -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. If -skip_preflight, SQL goes directly to shards without going through sanity checks.

Example #

ApplySchema [-allow_long_unavailability] [-wait_replicas_timeout=10s] [-ddl_strategy=] [-request_context=] [-skip_preflight] {-sql=<sql> || -sql-file=<filename>} <keyspace>

Flags #

NameTypeDefinition
allow_long_unavailabilityBooleanAllow large schema changes which incur a longer unavailability of the database.
ddl_strategystringOnline DDL strategy, compatible with @@ddl_strategy session variable (examples: 'gh-ost', '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.
skip_preflightBooleanSkip pre-apply schema checks, and directly forward schema change query to shards.
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.

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 #