vtctl

vtctl Command Index

vtctl is a command-line tool used to administer a Vitess cluster. It is available as both a standalone tool (vtctl) and client-server (vtctlclient in combination with vtctld). Using client-server is recommended, as it provides an additional layer of security when using the client remotely.

Note that wherever vtctl commands produced master or MASTER for tablet type, they now produce primary or PRIMARY. Scripts and tools that depend on parsing command output will need to be updated.

Commands #

Tablets #

NameExample Usage
(DEPRECATED) InitTablet DEPRECATEDInitTablet -- [--allow_update] [--allow_different_shard] [--allow_master_override] [--parent] [--db_name_override=<db name>] [--hostname=<hostname>] [--mysql_port=<port>] [--port=<port>] [--grpc_port=<port>] [--tags=tag1:value1,tag2:value2] -keyspace=<keyspace> -shard=<shard> <tablet alias> <tablet type>
GetTabletGetTablet <tablet alias>
(DEPRECATED) UpdateTabletAddrs DEPRECATEDUpdateTabletAddrs -- [--hostname <hostname>] [--ip-addr <ip addr>] [--mysql-port <mysql port>] [--vt-port <vt port>] [--grpc-port <grpc port>] <tablet alias>
DeleteTabletDeleteTablet -- [--allow_primary=false] <tablet alias> ...
SetReadOnlySetReadOnly <tablet alias>
SetReadWriteSetReadWrite <tablet alias>
StartReplicationStartReplication <tablet alias>
StopReplicationStopReplication <tablet alias>
ChangeTabletTypeChangeTabletType -- [--dry-run] <tablet alias> <tablet type>
PingPing <tablet alias>
RefreshStateRefreshState <tablet alias>
RefreshStateByShardRefreshStateByShard -- [--cells=c1,c2,...] <keyspace/shard>
RunHealthCheckRunHealthCheck <tablet alias>
SleepSleep <tablet alias> <duration>
ExecuteHookExecuteHook <tablet alias> <hook name> [<param1=value1> <param2=value2> ...]
ExecuteFetchAsAppExecuteFetchAsApp -- [--max_rows=10000] [--json] [--use_pool] <tablet alias> <sql command>
ExecuteFetchAsDbaExecuteFetchAsDba -- [--max_rows=10000] [--disable_binlogs] [--json] <tablet alias> <sql command>
VReplicationExecVReplicationExec -- [--json] <tablet alias> <sql command>
BackupBackup -- [--concurrency=4] [--allow_primary=false] [--upgrade-safe=false] <tablet alias>
RestoreFromBackupRestoreFromBackup <tablet alias>
ReparentTabletReparentTablet <tablet alias>

Shards #

NameExample Usage
CreateShardCreateShard -- [--force] [--parent] <keyspace/shard>
GetShardGetShard <keyspace/shard>
ValidateShardValidateShard -- [--ping-tablets] <keyspace/shard>
ShardReplicationPositionsShardReplicationPositions <keyspace/shard>
ListShardTabletsListShardTablets <keyspace/shard>
SetShardIsPrimaryServingSetShardIsPrimaryServing <keyspace/shard> <is_serving>
SetShardTabletControlSetShardTabletControl -- [--cells=c1,c2,...] [--denied_tables=t1,t2,...] [--remove] [--disable_query_service] <keyspace/shard> <tablet type>
UpdateSrvKeyspacePartitionUpdateSrvKeyspacePartition -- [--cells=c1,c2,...] [--remove] <keyspace/shard> <tablet type>
SourceShardDeleteSourceShardDelete <keyspace/shard> <uid>
SourceShardAddSourceShardAdd -- [--key_range=<keyrange>] [--tables=<table1,table2,...>] <keyspace/shard> <uid> <source keyspace/shard>
ShardReplicationFixShardReplicationFix <cell> <keyspace/shard>
WaitForFilteredReplicationWaitForFilteredReplication -- [--max_delay <max_delay, default 30s>] <keyspace/shard>
RemoveShardCellRemoveShardCell -- [--force] [--recursive] <keyspace/shard> <cell>
DeleteShardDeleteShard -- [--recursive] [--even_if_serving] <keyspace/shard> ...
ListBackupsListBackups <keyspace/shard>
BackupShardBackupShard -- [--allow_primary=false] [--upgrade-safe=false] <keyspace/shard>
RemoveBackupRemoveBackup <keyspace/shard> <backup name>
(DEPRECATED) InitShardPrimaryInitShardPrimary -- [--force] [--wait_replicas_timeout=<duration>] <keyspace/shard> <tablet alias>
PlannedReparentShardPlannedReparentShard -- --keyspace_shard=<keyspace/shard> [--new_primary=<tablet alias>] [--avoid_tablet=<tablet alias>] [--wait_replicas_timeout=<duration>]
EmergencyReparentShardEmergencyReparentShard -- --keyspace_shard=<keyspace/shard> [--new_primary=<tablet alias>] [--wait_replicas_timeout=<duration>] [--ignore_replicas=<tablet alias list>] [--prevent_cross_cell_promotion=<true/false>]
TabletExternallyReparentedTabletExternallyReparented <tablet alias>
GenerateShardRangesGenerateShardRanges <num shards>

Keyspaces #

NameExample Usage
CreateKeyspaceCreateKeyspace -- [--sharding_column_name=name] [--sharding_column_type=type] [--served_from=tablettype1:ks1,tablettype2:ks2,...] [--force] [--keyspace_type=type] [--base_keyspace=base_keyspace] [--snapshot_time=time] [--durability-policy=policy_name] [--sidecar-db-name=db_name] <keyspace name>
DeleteKeyspaceDeleteKeyspace -- [--recursive] <keyspace>
RemoveKeyspaceCellRemoveKeyspaceCell -- [--force] [--recursive] <keyspace> <cell>
GetKeyspaceGetKeyspace <keyspace>
GetKeyspacesGetKeyspaces
RebuildKeyspaceGraphRebuildKeyspaceGraph -- [--cells=c1,c2,...] <keyspace> ...
ValidateKeyspaceValidateKeyspace -- [--ping-tablets] <keyspace name>
CreateLookupVindexCreateLookupVindex -- [--cell=<cell>] [--tablet_types=<source_tablet_types>] <keyspace> <json_spec>
ExternalizeVindexExternalizeVindex <keyspace>.<vindex>
MaterializeMaterialize <json_spec>, example : '{"workflow": "aaa", "source_keyspace": "source", "target_keyspace": "target", "table_settings": [{"target_table": "customer", "source_expression": "select * from customer", "create_ddl": "copy"}]}'
VDiffVDiff -- [--source_cell=<cell>] [--target_cell=<cell>] [--tablet_types=in_order:RDONLY,REPLICA,PRIMARY] [--limit=<max rows to diff>] [--tables=<table list>] [--format=json] [--auto-retry] [--verbose] [--max_extra_rows_to_compare=1000] [--filtered_replication_wait_time=30s] [--debug_query] [--only_pks] [--wait] [--wait-update-interval=1m] <keyspace.workflow> [<action>] [<UUID>]
FindAllShardsInKeyspaceFindAllShardsInKeyspace <keyspace>

Generic #

NameExample Usage
ValidateValidate -- [--ping-tablets]
ListAllTabletsListAllTablets -- [--keyspace=''] [--tablet_type=<PRIMARY,REPLICA,RDONLY,SPARE>] [<cell_name1>,<cell_name2>,...]
ListTabletsListTablets <tablet alias> ...
HelpHelp [command name]

Schema, Version, Permissions #

NameExample Usage
GetSchemaGetSchema -- [--tables=<table1>,<table2>,...] [--exclude_tables=<table1>,<table2>,...] [--include-views] <tablet alias>
ReloadSchemaReloadSchema <tablet alias>
ReloadSchemaShardReloadSchemaShard -- [--concurrency=10] [--include_primary=false] <keyspace/shard>
ReloadSchemaKeyspaceReloadSchemaKeyspace -- [--concurrency=10] [--include_primary=false] <keyspace>
ValidateSchemaShardValidateSchemaShard -- [--exclude_tables=''] [--include-views] <keyspace/shard>
ValidateSchemaKeyspaceValidateSchemaKeyspace -- [--exclude_tables=''] [--include-views] <keyspace name>
ApplySchemaApplySchema -- [--wait_replicas_timeout=10s] {--sql=<sql> || --sql-file=<filename>} <keyspace>
CopySchemaShardCopySchemaShard -- [--tables=<table1>,<table2>,...] [--exclude_tables=<table1>,<table2>,...] [--include-views] [--skip-verify] [--wait_replicas_timeout=10s] {<source keyspace/shard> || <source tablet alias>} <destination keyspace/shard>
ValidateVersionShardValidateVersionShard <keyspace/shard>
ValidateVersionKeyspaceValidateVersionKeyspace <keyspace name>
GetPermissionsGetPermissions <tablet alias>
ValidatePermissionsShardValidatePermissionsShard <keyspace/shard>
ValidatePermissionsKeyspaceValidatePermissionsKeyspace <keyspace name>
GetVSchemaGetVSchema <keyspace>
ApplyVSchemaApplyVSchema -- {--vschema=<vschema> || --vschema_file=<vschema file> || --sql=<sql> || --sql_file=<sql file>} [--cells=c1,c2,...] [--skip_rebuild] [--dry-run] <keyspace>
GetRoutingRulesGetRoutingRules
ApplyRoutingRulesApplyRoutingRules -- {--rules=<rules> || --rules_file=<rules_file>} [--cells=c1,c2,...] [--skip_rebuild] [--dry-run]
RebuildVSchemaGraphRebuildVSchemaGraph -- [--cells=c1,c2,...]

Serving Graph #

NameExample Usage
GetSrvKeyspaceNamesGetSrvKeyspaceNames <cell>
GetSrvKeyspaceGetSrvKeyspace <cell> <keyspace>
GetSrvVSchemaGetSrvVSchema <cell>
DeleteSrvVSchemaDeleteSrvVSchema <cell>

Replication Graph #

NameExample Usage
GetShardReplicationGetShardReplication <cell> <keyspace/shard>

Cells #

NameExample Usage
AddCellInfoAddCellInfo -- [--server_address <addr>] [--root <root>] <cell>
UpdateCellInfoUpdateCellInfo -- [--server_address <addr>] [--root <root>] <cell>
DeleteCellInfoDeleteCellInfo -- [--force] <cell>
GetCellInfoNamesGetCellInfoNames
GetCellInfoGetCellInfo <cell>

CellsAliases #

NameExample Usage
AddCellsAliasAddCellsAlias -- [--cells <cell,cell2...>] <alias>
UpdateCellsAliasUpdateCellsAlias -- [--cells <cell,cell2,...>] <alias>
DeleteCellsAliasDeleteCellsAlias <alias>
GetCellsAliasesGetCellsAliases

Topo #

NameExample Usage
TopoCatTopoCat -- [--cell <cell>] [--decode_proto] [--decode_proto_json] [--long] <path> [<path>...]
TopoCpTopoCp -- [--cell <cell>] [--to_topo] <src> <dst>

Throttler #

NameExample Usage
UpdateThrottlerConfigUpdateThrottlerConfig -- [--enable|--disable] [--threshold=<float64>] [--custom-query=<query>] [--check-as-check-self|--check-as-check-shard] [--throttle-app=<name>] [--throttle-app-ratio=<float, range [0..1]>] [--throttle-app-duration=<duration>] <keyspace>

Options #

The following global options apply to vtctl:

NameTypeDefinition
--alsologtostderrlog to standard error as well as files
--azblob_backup_account_key_filestringPath to a file containing the Azure Storage account key; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_KEY will be used as the key itself (NOT a file path)
--azblob_backup_account_namestringAzure Storage Account name for backups; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_NAME will be used
--azblob_backup_container_namestringAzure Blob Container Name
--azblob_backup_parallelismintAzure Blob operation parallelism (requires extra memory when increased) (default 1)
--azblob_backup_storage_rootstringRoot prefix for all backup-related Azure Blobs; this should exclude both initial and trailing '/' (e.g. just 'a/b' not '/a/b/')
--backup_engine_implementationstringSpecifies which implementation to use for creating new backups (builtin or xtrabackup). Restores will always be done with whichever engine created a given backup. (default "builtin")
--backup_storage_block_sizeintif backup_storage_compress is true, backup_storage_block_size sets the byte size for each block while compressing (default is 250000). (default 250000)
--backup_storage_compressif set, the backup files will be compressed (default is true).
--backup_storage_implementationstringwhich implementation to use for the backup storage feature
--backup_storage_number_blocksintif backup_storage_compress is true, backup_storage_number_blocks sets the number of blocks that can be processed, at once, before the writer blocks, during compression (default is 2). It should be equal to the number of CPUs available for compression (default 2)
--ceph_backup_storage_configstringPath to JSON config file for ceph backup storage (default "ceph_backup_config.json")
--consul_auth_static_filestringJSON File to read the topos/tokens from.
--datadog-agent-hoststringhost to send spans to. if empty, no tracing will be done
--datadog-agent-portstringport to send spans to. if empty, no tracing will be done
--detachdetached mode - run vtcl detached from the terminal
-file_backup_storage_rootstringroot directory for the file backup storage -- this path must be on shared storage to provide a global view of backups to all vitess components
--gcs_backup_storage_bucketstringGoogle Cloud Storage bucket to use for backups
--gcs_backup_storage_rootstringroot prefix for all backup-related object names
--grpc_auth_static_client_credsstringwhen using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server
--grpc_compressionstringhow to compress gRPC, default: nothing, supported: snappy
--grpc_enable_tracingEnable GRPC tracing
--grpc_initial_conn_window_sizeintgrpc initial connection window size
--grpc_initial_window_sizeintgrpc initial window size
--grpc_keepalive_timedurationAfter a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default 10s)
--grpc_keepalive_timeoutdurationAfter having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s)
--grpc_max_message_sizeintMaximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216)
--grpc_prometheusEnable gRPC monitoring with Prometheus
--jaeger-agent-hoststringhost and port to send spans to. if empty, no tracing will be done
--keep_logsdurationkeep logs for this long (using ctime) (zero to keep forever)
--keep_logs_by_mtimedurationkeep logs for this long (using mtime) (zero to keep forever)
--log_backtrace_atvaluewhen logging hits line file:N, emit a stack trace
--log_dirstringIf non-empty, write log files in this directory
--log_err_stackslog stack traces for errors
--log_rotate_max_sizeuintsize in bytes at which logs are rotated (glog.MaxSize) (default 1887436800)
--logtostderrlog to standard error instead of files
--mysql_server_versionstringMySQL server version to advertise.
--pprofstringsenable profiling
--purge_logs_intervaldurationhow often try to remove old logs (default 1h0m0s)
--remote_operation_timeoutdurationtime to wait for a remote operation (default 30s)
--s3_backup_aws_endpointstringendpoint of the S3 backend (region must be provided)
--s3_backup_aws_regionstringAWS region to use (default "us-east-1")
--s3_backup_aws_retriesintAWS request retries (default -1)
--s3_backup_force_path_styleforce the s3 path style
--s3_backup_log_levelstringdetermine the S3 loglevel to use from LogOff, LogDebug, LogDebugWithSigning, LogDebugWithHTTPBody, LogDebugWithRequestRetries, LogDebugWithRequestErrors (default "LogOff")
--s3_backup_server_side_encryptionstringserver-side encryption algorithm (e.g., AES256, aws:kms)
--s3_backup_storage_bucketstringS3 bucket to use for backups
--s3_backup_storage_rootstringroot prefix for all backup-related object names
--s3_backup_tls_skip_verify_certskip the 'certificate is valid' check for SSL connections
--security_policystringthe name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only)
--service_mapvaluecomma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice
--sql-max-length-errorsinttruncate queries in error logs to the given length (default unlimited)
--sql-max-length-uiinttruncate queries in debug UIs to the given length (default 512) (default 512)
--stderrthresholdvaluelogs at or above this threshold go to stderr (default 1)
--tablet_grpc_castringthe server ca to use to validate servers when connecting
--tablet_grpc_certstringthe cert to use to connect
--tablet_grpc_crlstringthe server crl to use to validate server certificates when connecting
--tablet_grpc_keystringthe key to use to connect
--tablet_grpc_server_namestringthe server name to use to validate server certificate
--tablet_manager_grpc_castringthe server ca to use to validate servers when connecting
--tablet_manager_grpc_certstringthe cert to use to connect
--tablet_manager_grpc_concurrencyintconcurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8)
--tablet_manager_grpc_connpool_sizeintnumber of tablets to keep tmclient connections open to (default 100)
--tablet_manager_grpc_crlstringthe server crl to use to validate server certificates when connecting
--tablet_manager_grpc_keystringthe key to use to connect
--tablet_manager_grpc_server_namestringthe server name to use to validate server certificate
--tablet_manager_protocolstringthe protocol to use to talk to vttablet (default "grpc")
--tablet_protocolstringhow to talk to the vttablets (default "grpc")
--topo_consul_lock_session_ttlstringTTL for consul session.
--topo_consul_watch_poll_durationdurationtime of the long poll for watch queries. (default 30s)
--topo_etcd_lease_ttlintLease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30)
--topo_etcd_tls_castringpath to the ca to use to validate the server cert when connecting to the etcd topo server
--topo_etcd_tls_certstringpath to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS
--topo_etcd_tls_keystringpath to the client key to use to connect to the etcd topo server, enables TLS
--topo_global_rootstringthe path of the global topology data in the global topology server
--topo_global_server_addressstringthe address of the global topology server
--topo_implementationstringthe topology implementation to use
--topo_zk_auth_filestringauth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass
--topo_zk_base_timeoutdurationzk base timeout (see zk.Connect) (default 30s)
--topo_zk_max_concurrencyintmaximum number of pending requests to send to a Zookeeper server. (default 64)
--topo_zk_tls_castringthe server ca to use to validate servers when connecting to the zk topo server
--topo_zk_tls_certstringthe cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS
--topo_zk_tls_keystringthe key to use to connect to the zk topo server, enables TLS
--tracerstringtracing service to use (default "noop")
--tracing-enable-loggingwhether to enable logging in the tracing service
--tracing-sampling-ratefloatsampling rate for the probabilistic jaeger sampler (default 0.1)
--tracing-sampling-typestringsampling strategy to use for
--vvaluelog level for V logs
--versionprint binary version
--vmodulevaluecomma-separated list of pattern=N settings for file-filtered logging
--vtctl_healthcheck_retry_delaydurationdelay before retrying a failed healthcheck (default 5s)
--vtctl_healthcheck_timeoutdurationthe health check timeout period (default 1m0s)
--vtctl_healthcheck_topology_refreshdurationrefresh interval for re-reading the topology (default 30s)
--vtgate_grpc_castringthe server ca to use to validate servers when connecting
--vtgate_grpc_certstringthe cert to use to connect
--vtgate_grpc_crlstringthe server crl to use to validate server certificates when connecting
--vtgate_grpc_keystringthe key to use to connect
--vtgate_grpc_server_namestringthe server name to use to validate server certificate
--wait-timedurationtime to wait on an action (default 24h0m0s)