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

Name Example Usage
(DEPRECATED) InitTablet DEPRECATED InitTablet — [—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>
GetTablet GetTablet <tablet alias>
(DEPRECATED) UpdateTabletAddrs DEPRECATED UpdateTabletAddrs — [—hostname <hostname>] [—ip-addr <ip addr>] [—mysql-port <mysql port>] [—vt-port <vt port>] [—grpc-port <grpc port>] <tablet alias>
DeleteTablet DeleteTablet — [—allow_primary=false] <tablet alias> …
SetReadOnly SetReadOnly <tablet alias>
SetReadWrite SetReadWrite <tablet alias>
StartReplication StartReplication <tablet alias>
StopReplication StopReplication <tablet alias>
ChangeTabletType ChangeTabletType — [—dry-run] <tablet alias> <tablet type>
Ping Ping <tablet alias>
RefreshState RefreshState <tablet alias>
RefreshStateByShard RefreshStateByShard — [—cells=c1,c2,…] <keyspace/shard>
RunHealthCheck RunHealthCheck <tablet alias>
Sleep Sleep <tablet alias> <duration>
ExecuteHook ExecuteHook <tablet alias> <hook name> [<param1=value1> <param2=value2> …]
ExecuteFetchAsApp ExecuteFetchAsApp — [—max_rows=10000] [—json] [—use_pool] <tablet alias> <sql command>
ExecuteFetchAsDba ExecuteFetchAsDba — [—max_rows=10000] [—disable_binlogs] [—json] <tablet alias> <sql command>
VReplicationExec VReplicationExec — [—json] <tablet alias> <sql command>
Backup Backup — [—concurrency=4] [—allow_primary=false] [—upgrade-safe=false] [—incremental-from-pos=<pos>] <tablet alias>
RestoreFromBackup RestoreFromBackup <tablet alias>
ReparentTablet ReparentTablet <tablet alias>

Shards

Name Example Usage
CreateShard CreateShard — [—force] [—parent] <keyspace/shard>
GetShard GetShard <keyspace/shard>
ValidateShard ValidateShard — [—ping-tablets] <keyspace/shard>
ShardReplicationPositions ShardReplicationPositions <keyspace/shard>
ListShardTablets ListShardTablets <keyspace/shard>
SetShardIsPrimaryServing SetShardIsPrimaryServing <keyspace/shard> <is_serving>
SetShardTabletControl SetShardTabletControl — [—cells=c1,c2,…] [—denied_tables=t1,t2,…] [—remove] [—disable_query_service] <keyspace/shard> <tablet type>
UpdateSrvKeyspacePartition UpdateSrvKeyspacePartition — [—cells=c1,c2,…] [—remove] <keyspace/shard> <tablet type>
SourceShardDelete SourceShardDelete <keyspace/shard> <uid>
SourceShardAdd SourceShardAdd — [—key_range=<keyrange>] [—tables=<table1,table2,…>] <keyspace/shard> <uid> <source keyspace/shard>
ShardReplicationFix ShardReplicationFix <cell> <keyspace/shard>
WaitForFilteredReplication WaitForFilteredReplication — [—max_delay <max_delay, default 30s>] <keyspace/shard>
RemoveShardCell RemoveShardCell — [—force] [—recursive] <keyspace/shard> <cell>
DeleteShard DeleteShard — [—recursive] [—even_if_serving] <keyspace/shard> …
ListBackups ListBackups <keyspace/shard>
BackupShard BackupShard — [—allow_primary=false] [—upgrade-safe=false] <keyspace/shard> [—incremental_from_pos=]
RemoveBackup RemoveBackup <keyspace/shard> <backup name>
(DEPRECATED) InitShardPrimary InitShardPrimary — [—force] [—wait_replicas_timeout=<duration>] <keyspace/shard> <tablet alias>
PlannedReparentShard PlannedReparentShard — —keyspace_shard=<keyspace/shard> [—new_primary=<tablet alias>] [—avoid_tablet=<tablet alias>] [—wait_replicas_timeout=<duration>]
EmergencyReparentShard EmergencyReparentShard — —keyspace_shard=<keyspace/shard> [—new_primary=<tablet alias>] [—wait_replicas_timeout=<duration>] [—ignore_replicas=<tablet alias list>] [—prevent_cross_cell_promotion=<true/false>]
TabletExternallyReparented TabletExternallyReparented <tablet alias>
GenerateShardRanges GenerateShardRanges <num shards>

Keyspaces

Name Example Usage
CreateKeyspace CreateKeyspace — [—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>
DeleteKeyspace DeleteKeyspace — [—recursive] <keyspace>
RemoveKeyspaceCell RemoveKeyspaceCell — [—force] [—recursive] <keyspace> <cell>
GetKeyspace GetKeyspace <keyspace>
GetKeyspaces GetKeyspaces
RebuildKeyspaceGraph RebuildKeyspaceGraph — [—cells=c1,c2,…] <keyspace> …
ValidateKeyspace ValidateKeyspace — [—ping-tablets] <keyspace name>
CreateLookupVindex CreateLookupVindex — [—cell=<cell>] [—tablet_types=<source_tablet_types>] <keyspace> <json_spec>
ExternalizeVindex ExternalizeVindex <keyspace>.<vindex>
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”}]}’
VDiff VDiff — [—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>]
FindAllShardsInKeyspace FindAllShardsInKeyspace <keyspace>

Generic

Name Example Usage
Validate Validate — [—ping-tablets]
ListAllTablets ListAllTablets — [—keyspace=’’] [—tablet_type=<PRIMARY,REPLICA,RDONLY,SPARE>] [<cell_name1>,<cell_name2>,…]
ListTablets ListTablets <tablet alias> …
Help Help [command name]

Schema, Version, Permissions

Name Example Usage
GetSchema GetSchema — [—tables=<table1>,<table2>,…] [—exclude_tables=<table1>,<table2>,…] [—include-views] <tablet alias>
ReloadSchema ReloadSchema <tablet alias>
ReloadSchemaShard ReloadSchemaShard — [—concurrency=10] [—include_primary=false] <keyspace/shard>
ReloadSchemaKeyspace ReloadSchemaKeyspace — [—concurrency=10] [—include_primary=false] <keyspace>
ValidateSchemaShard ValidateSchemaShard — [—exclude_tables=’’] [—include-views] <keyspace/shard>
ValidateSchemaKeyspace ValidateSchemaKeyspace — [—exclude_tables=’’] [—include-views] <keyspace name>
ApplySchema ApplySchema — [—wait_replicas_timeout=10s] {—sql=<sql> || —sql-file=<filename>} [—batch-size=100] <keyspace>
CopySchemaShard CopySchemaShard — [—tables=<table1>,<table2>,…] [—exclude_tables=<table1>,<table2>,…] [—include-views] [—skip-verify] [—wait_replicas_timeout=10s] {<source keyspace/shard> || <source tablet alias>} <destination keyspace/shard>
ValidateVersionShard ValidateVersionShard <keyspace/shard>
ValidateVersionKeyspace ValidateVersionKeyspace <keyspace name>
GetPermissions GetPermissions <tablet alias>
ValidatePermissionsShard ValidatePermissionsShard <keyspace/shard>
ValidatePermissionsKeyspace ValidatePermissionsKeyspace <keyspace name>
GetVSchema GetVSchema <keyspace>
ApplyVSchema ApplyVSchema — {—vschema=<vschema> || —vschema_file=<vschema file> || —sql=<sql> || —sql_file=<sql file>} [—cells=c1,c2,…] [—skip_rebuild] [—dry-run] <keyspace>
GetRoutingRules GetRoutingRules
ApplyRoutingRules ApplyRoutingRules — {—rules=<rules> || —rules_file=<rules_file>} [—cells=c1,c2,…] [—skip_rebuild] [—dry-run]
RebuildVSchemaGraph RebuildVSchemaGraph — [—cells=c1,c2,…]

Serving Graph

Name Example Usage
GetSrvKeyspaceNames GetSrvKeyspaceNames <cell>
GetSrvKeyspace GetSrvKeyspace <cell> <keyspace>
GetSrvVSchema GetSrvVSchema <cell>
DeleteSrvVSchema DeleteSrvVSchema <cell>

Replication Graph

Name Example Usage
GetShardReplication GetShardReplication <cell> <keyspace/shard>

Cells

Name Example Usage
AddCellInfo AddCellInfo — [—server_address <addr>] [—root <root>] <cell>
UpdateCellInfo UpdateCellInfo — [—server_address <addr>] [—root <root>] <cell>
DeleteCellInfo DeleteCellInfo — [—force] <cell>
GetCellInfoNames GetCellInfoNames
GetCellInfo GetCellInfo <cell>

CellsAliases

Name Example Usage
AddCellsAlias AddCellsAlias — [—cells <cell,cell2…>] <alias>
UpdateCellsAlias UpdateCellsAlias — [—cells <cell,cell2,…>] <alias>
DeleteCellsAlias DeleteCellsAlias <alias>
GetCellsAliases GetCellsAliases

Topo

Name Example Usage
TopoCat TopoCat — [—cell <cell>] [—decode_proto] [—decode_proto_json] [—long] <path> [<path>…]
TopoCp TopoCp — [—cell <cell>] [—to_topo] <src> <dst>

Throttler

Name Example Usage
UpdateThrottlerConfig `UpdateThrottlerConfig — [—enable

Options

The following global options apply to vtctl:

Name Type Definition
—alsologtostderr log to standard error as well as files
—azblob_backup_account_key_file string Path 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_name string Azure Storage Account name for backups; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_NAME will be used
—azblob_backup_buffer_size int The memory buffer size to use in bytes, per file or stripe, when streaming to Azure Blob Service. (default 104857600)
—azblob_backup_container_name string Azure Blob Container Name
—azblob_backup_parallelism int Azure Blob operation parallelism (requires extra memory when increased — a multiple of azblob_backup_buffer_size). (default 1)
—azblob_backup_storage_root string Root prefix for all backup-related Azure Blobs; this should exclude both initial and trailing ‘/‘ (e.g. just ‘a/b’ not ‘/a/b/‘)
—backup_engine_implementation string Specifies 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_size int if 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_compress if set, the backup files will be compressed (default is true).
—backup_storage_implementation string which implementation to use for the backup storage feature
—backup_storage_number_blocks int if 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_config string Path to JSON config file for ceph backup storage (default “ceph_backup_config.json”)
—consul_auth_static_file string JSON File to read the topos/tokens from.
—datadog-agent-host string host to send spans to. if empty, no tracing will be done
—datadog-agent-port string port to send spans to. if empty, no tracing will be done
—detach detached mode - run vtcl detached from the terminal
-file_backup_storage_root string root 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_bucket string Google Cloud Storage bucket to use for backups
—gcs_backup_storage_root string root prefix for all backup-related object names
—grpc_auth_static_client_creds string when using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server
—grpc_compression string how to compress gRPC, default: nothing, supported: snappy
—grpc_enable_tracing Enable GRPC tracing
—grpc_initial_conn_window_size int grpc initial connection window size
—grpc_initial_window_size int grpc initial window size
—grpc_keepalive_time duration After 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_timeout duration After 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_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error ‘exceeding the max size’. (default 16777216)
—grpc_prometheus Enable gRPC monitoring with Prometheus
—jaeger-agent-host string host and port to send spans to. if empty, no tracing will be done
—keep_logs duration keep logs for this long (using ctime) (zero to keep forever)
—keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever)
—log_backtrace_at value when logging hits line file:N, emit a stack trace
—log_dir string If non-empty, write log files in this directory
—log_err_stacks log stack traces for errors
—log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800)
—logtostderr log to standard error instead of files
—mysql_server_version string MySQL server version to advertise.
—pprof strings enable profiling
—purge_logs_interval duration how often try to remove old logs (default 1h0m0s)
—remote_operation_timeout duration time to wait for a remote operation (default 30s)
—s3_backup_aws_endpoint string endpoint of the S3 backend (region must be provided)
—s3_backup_aws_region string AWS region to use (default “us-east-1”)
—s3_backup_aws_retries int AWS request retries (default -1)
—s3_backup_force_path_style force the s3 path style
—s3_backup_log_level string determine the S3 loglevel to use from LogOff, LogDebug, LogDebugWithSigning, LogDebugWithHTTPBody, LogDebugWithRequestRetries, LogDebugWithRequestErrors (default “LogOff”)
—s3_backup_server_side_encryption string server-side encryption algorithm (e.g., AES256, aws:kms)
—s3_backup_storage_bucket string S3 bucket to use for backups
—s3_backup_storage_root string root prefix for all backup-related object names
—s3_backup_tls_skip_verify_cert skip the ‘certificate is valid’ check for SSL connections
—security_policy string the 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_map value comma separated list of services to enable (or disable if prefixed with ‘-‘) Example: grpc-queryservice
—sql-max-length-errors int truncate queries in error logs to the given length (default unlimited)
—sql-max-length-ui int truncate queries in debug UIs to the given length (default 512) (default 512)
—stderrthreshold value logs at or above this threshold go to stderr (default 1)
—tablet_grpc_ca string the server ca to use to validate servers when connecting
—tablet_grpc_cert string the cert to use to connect
—tablet_grpc_crl string the server crl to use to validate server certificates when connecting
—tablet_grpc_key string the key to use to connect
—tablet_grpc_server_name string the server name to use to validate server certificate
—tablet_manager_grpc_ca string the server ca to use to validate servers when connecting
—tablet_manager_grpc_cert string the cert to use to connect
—tablet_manager_grpc_concurrency int concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8)
—tablet_manager_grpc_connpool_size int number of tablets to keep tmclient connections open to (default 100)
—tablet_manager_grpc_crl string the server crl to use to validate server certificates when connecting
—tablet_manager_grpc_key string the key to use to connect
—tablet_manager_grpc_server_name string the server name to use to validate server certificate
—tablet_manager_protocol string the protocol to use to talk to vttablet (default “grpc”)
—tablet_protocol string how to talk to the vttablets (default “grpc”)
—topo_consul_lock_session_ttl string TTL for consul session.
—topo_consul_watch_poll_duration duration time of the long poll for watch queries. (default 30s)
—topo_etcd_lease_ttl int Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30)
—topo_etcd_tls_ca string path to the ca to use to validate the server cert when connecting to the etcd topo server
—topo_etcd_tls_cert string path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS
—topo_etcd_tls_key string path to the client key to use to connect to the etcd topo server, enables TLS
—topo_global_root string the path of the global topology data in the global topology server
—topo_global_server_address string the address of the global topology server
—topo_implementation string the topology implementation to use
—topo_zk_auth_file string auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass
—topo_zk_base_timeout duration zk base timeout (see zk.Connect) (default 30s)
—topo_zk_max_concurrency int maximum number of pending requests to send to a Zookeeper server. (default 64)
—topo_zk_tls_ca string the server ca to use to validate servers when connecting to the zk topo server
—topo_zk_tls_cert string the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS
—topo_zk_tls_key string the key to use to connect to the zk topo server, enables TLS
—tracer string tracing service to use (default “noop”)
—tracing-enable-logging whether to enable logging in the tracing service
—tracing-sampling-rate float sampling rate for the probabilistic jaeger sampler (default 0.1)
—tracing-sampling-type string sampling strategy to use for
—v value log level for V logs
—version print binary version
—vmodule value comma-separated list of pattern=N settings for file-filtered logging
—vtctl_healthcheck_retry_delay duration delay before retrying a failed healthcheck (default 5s)
—vtctl_healthcheck_timeout duration the health check timeout period (default 1m0s)
—vtctl_healthcheck_topology_refresh duration refresh interval for re-reading the topology (default 30s)
—vtgate_grpc_ca string the server ca to use to validate servers when connecting
—vtgate_grpc_cert string the cert to use to connect
—vtgate_grpc_crl string the server crl to use to validate server certificates when connecting
—vtgate_grpc_key string the key to use to connect
—vtgate_grpc_server_name string the server name to use to validate server certificate
—wait-time duration time to wait on an action (default 24h0m0s)