mysqlctl is a command-line tool used for starting mysqld binaries. It is responsible for bootstrapping tasks such as generating a configuration file for mysqld and ensuring that mysql_upgrade is run in the data directory when restoring from backup.

mysqld_safe will be also be utilized when present. This helps ensure that mysqld is automatically restarted after failures.


init [-wait_time=5m] [-init_db_sql_file=(default)]

Bootstraps a new mysqld instance. The MySQL version and flavor will be auto-detected, with a minimal configuration file applied. For example:

export VTDATAROOT=/tmp
mysqlctl \
 -alsologtostderr \
 -tablet_uid 101 \
 -mysql_port 12345 \


Bootstraps the configuration for a new mysqld instance. This command is the same as init except the mysqld server will not be started. For example:

export VTDATAROOT=/tmp
mysqlctl \
 -alsologtostderr \
 -tablet_uid 101 \
 -mysql_port 12345 \


Regenerate new configuration files for an existing mysqld instance. This could be helpful to revert configuration changes, or to pick up changes made to the bundled config in newer Vitess versions. For example:

export VTDATAROOT=/tmp
mysqlctl \
 -alsologtostderr \
 -tablet_uid 101 \
 -mysql_port 12345 \

teardown [-wait_time=5m] [-force]

Remove the data files for a previously shutdown mysqld instance. This is a destructive operation:

export VTDATAROOT=/tmp
mysqlctl -tablet_uid 101 -alsologtostderr teardown

start [-wait_time=5m]

Resume an existing mysqld instance that was previously bootstrapped with init or init_config:

export VTDATAROOT=/tmp
mysqlctl -tablet_uid 101 -alsologtostderr start

shutdown [-wait_time=5m]

Stop a mysqld instance that was previously started with init or start.

For large mysqld instances, you may need to extend the -wait_time as flushing dirty pages.

export VTDATAROOT=/tmp
mysqlctl -tablet_uid 101 -alsologtostderr shutdown


The following global parameters apply to mysqlctl:

alsologtostderrbooleanlog to standard error as well as files
app_idle_timeoutdurationIdle timeout for app connections (default 1m0s)
app_pool_sizeintSize of the connection pool for app connections (default 40)
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_compressbooleanif set, the backup files will be compressed (default is true). Set to false for instance if a backup_storage_hook is specified and it compresses the data. (default true)
backup_storage_hookstringif set, we send the contents of the backup files through this hook.
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)
cpu_profilestringwrite cpu profile to file
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
db-credentials-filestringdb credentials file; send SIGHUP to reload this file
db-credentials-serverstringdb credentials server type (use ‘file’ for the file implementation) (default “file”)
db_charsetstringCharacter set. Only utf8 or latin1 based character sets are supported.
db_connect_timeout_msintconnection timeout to mysqld in milliseconds (0 for no timeout)
db_dba_passwordstringdb dba password
db_dba_use_sslbooleanSet this flag to false to make the dba connection to not use ssl (default true)
db_dba_userstringdb dba user userKey (default “vt_dba”)
db_flagsuintFlag values as defined by MySQL.
db_flavorstringFlavor overrid. Valid value is FilePos.
db_hoststringThe host name for the tcp connection.
db_portinttcp port
db_server_namestringserver name of the DB we are connecting to.
db_socketstringThe unix socket to connect on. If this is specified, host and port will not be used.
db_ssl_castringconnection ssl ca
db_ssl_ca_pathstringconnection ssl ca path
db_ssl_certstringconnection ssl certificate
db_ssl_keystringconnection ssl key
dba_idle_timeoutdurationIdle timeout for dba connections (default 1m0s)
dba_pool_sizeintSize of the connection pool for dba connections (default 20)
disable_active_reparentsbooleanif set, do not allow active reparents. Use this to protect a cluster using external reparents.
emit_statsbooleantrue iff we should emit stats to push-based monitoring/stats backends
grpc_auth_modestringWhich auth plugin implementation to use (eg: static)
grpc_auth_mtls_allowed_substringsstringList of substrings of at least one of the client certificate names (separated by colon).
grpc_auth_static_client_credsstringwhen using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server
grpc_auth_static_password_filestringJSON File to read the users/passwords from.
grpc_castringca to use, requires TLS, and enforces client cert check
grpc_certstringcertificate to use, requires grpc_key, enables TLS
grpc_compressionstringhow to compress gRPC, default: nothing, supported: snappy
grpc_enable_tracingbooleanEnable 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_keystringkey to use, requires grpc_cert, enables TLS
grpc_max_connection_agedurationMaximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s)
grpc_max_connection_age_gracedurationAdditional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s)
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_portintPort to listen on for gRPC calls
grpc_prometheusbooleanEnable gRPC monitoring with Prometheus
grpc_server_initial_conn_window_sizeintgRPC server initial connection window size
grpc_server_initial_window_sizeintgRPC server initial window size
grpc_server_keepalive_enforcement_policy_min_timedurationgRPC server minimum keepalive time (default 5m0s)
grpc_server_keepalive_enforcement_policy_permit_without_streambooleangRPC server permit client keepalive pings even when there are no active streams (RPCs)
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)
lameduck-perioddurationkeep running at least this long after SIGTERM before stopping (default 50ms)
log_backtrace_atvaluewhen logging hits line file:N, emit a stack trace
log_dirstringIf non-empty, write log files in this directory
log_err_stacksbooleanlog stack traces for errors
log_rotate_max_sizeuintsize in bytes at which logs are rotated (glog.MaxSize) (default 1887436800)
logtostderrbooleanlog to standard error instead of files
master_connect_retrydurationhow long to wait in between replica reconnect attempts. Only precise to the second. (default 10s)
mem-profile-rateintprofile every n bytes allocated (default 524288)
mutex-profile-fractionintprofile every n mutex contention events (see runtime.SetMutexProfileFraction)
mysql_auth_server_static_filestringJSON File to read the users/passwords from.
mysql_auth_server_static_stringstringJSON representation of the users/passwords config.
mysql_auth_static_reload_intervaldurationTicker to reload credentials
mysql_clientcert_auth_methodstringclient-side authentication method to use. Supported values: mysql_clear_password, dialog. (default “mysql_clear_password”)
mysql_portintmysql port (default 3306)
mysql_server_flush_delaydurationDelay after which buffered response will be flushed to the client. (default 100ms)
mysql_socketstringpath to the mysql socket
mysqlctl_client_protocolstringthe protocol to use to talk to the mysqlctl server (default “grpc”)
mysqlctl_mycnf_templatestringtemplate file to use for generating the my.cnf file during server init
mysqlctl_socketstringsocket file to use for remote mysqlctl actions (empty for local actions)
onterm_timeoutdurationwait no more than this for OnTermSync handlers before stopping (default 10s)
pid_filestringIf set, the process will write its pid to the named file, and delete it on graceful shutdown.
pool_hostname_resolve_intervaldurationif set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled)
portintvttablet port (default 6612)
purge_logs_intervaldurationhow often try to remove old logs (default 1h0m0s)
remote_operation_timeoutdurationtime to wait for a remote operation (default 30s)
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-vtworker
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)
stats_backendstringThe name of the registered push-based monitoring/stats backend to use
stats_combine_dimensionsstringList of dimensions to be combined into a single “all” value in exported stats vars
stats_drop_variablesstringVariables to be dropped from the list of exported variables.
stats_emit_perioddurationInterval between emitting stats to all registered backends (default 1m0s)
stderrthresholdvaluelogs at or above this threshold go to stderr (default 1)
tablet_dirstringThe directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid.
tablet_manager_protocolstringthe protocol to use to talk to vttablet (default “grpc”)
tablet_uiduinttablet uid (default 41983)
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
tracerstringtracing service to use (default “noop”)
tracing-sampling-ratefloatsampling rate for the probabilistic jaeger sampler (default 0.1)
vvaluelog level for V logs
versionbooleanprint binary version
vmodulevaluecomma-separated list of pattern=N settings for file-filtered logging
xbstream_restore_flagsstringflags to pass to xbstream command during restore. These should be space separated and will be added to the end of the command. These need to match the ones used for backup e.g. –compress / –decompress, –encrypt / –decrypt
xtrabackup_backup_flagsstringflags to pass to backup command. These should be space separated and will be added to the end of the command
xtrabackup_prepare_flagsstringflags to pass to prepare command. These should be space separated and will be added to the end of the command
xtrabackup_root_pathstringdirectory location of the xtrabackup executable, e.g., /usr/bin
xtrabackup_stream_modestringwhich mode to use if streaming, valid values are tar and xbstream (default “tar”)
xtrabackup_stripe_block_sizeuintSize in bytes of each block that gets sent to a given stripe before rotating to the next stripe (default 102400)
xtrabackup_stripesuintIf greater than 0, use data striping across this many destination files to parallelize data transfer and decompression
xtrabackup_userstringUser that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation.