diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 608fd7977..ddbadb8b4 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -4,20 +4,3 @@ description: Everything you need to know about the world's most scalable open-so notoc: true --- -Vitess is a database solution for deploying, scaling and managing large clusters of MySQL instances. It's built to run with equal effectiveness on public cloud architecture, private cloud architecture, and dedicated hardware. - -## Vitess and MySQL - -Vitess combines and extends the important features of MySQL with the scalability of a NoSQL database. Vitess can help you with a variety of problems, including: - -* Scaling a MySQL database, using sharding, while keeping application changes to a minimum -* Migrating your MySQL installation from bare metal to a private or public cloud -* Deploying and managing a large number of MySQL instances - -## Vitess database drivers - -Vitess includes compliant [JDBC](https://github.com/vitessio/vitess/tree/master/java) and [Go](https://godoc.org/vitess.io/vitess/go) (Golang) database drivers using a native query protocol. Additionally, it implements the [MySQL server protocol](https://dev.mysql.com/doc/internals/en/client-server-protocol.html), which is compatible with virtually any other language. - -## Vitess in action - -Vitess has been serving all YouTube database traffic since 2011, and has now been adopted by many enterprises for their production needs. diff --git a/content/en/docs/reference/features/_index.md b/content/en/docs/reference/features/_index.md new file mode 100644 index 000000000..d20dc7715 --- /dev/null +++ b/content/en/docs/reference/features/_index.md @@ -0,0 +1,5 @@ +--- +title: Features +description: Reference documents for Vitess features +--- + diff --git a/content/en/docs/reference/messaging.md b/content/en/docs/reference/features/messaging.md similarity index 98% rename from content/en/docs/reference/messaging.md rename to content/en/docs/reference/features/messaging.md index 1f581cd6c..e7476ce01 100644 --- a/content/en/docs/reference/messaging.md +++ b/content/en/docs/reference/features/messaging.md @@ -1,6 +1,6 @@ --- -title: Vitess Messaging -aliases: ['/docs/advanced/messaging/'] +title: Messaging +aliases: ['/docs/advanced/messaging/','/docs/reference/messaging/'] --- Vitess messaging gives the application an easy way to schedule and manage work diff --git a/content/en/docs/reference/mysql-replication.md b/content/en/docs/reference/features/mysql-replication.md similarity index 98% rename from content/en/docs/reference/mysql-replication.md rename to content/en/docs/reference/features/mysql-replication.md index c40749d33..4c9fa8808 100644 --- a/content/en/docs/reference/mysql-replication.md +++ b/content/en/docs/reference/features/mysql-replication.md @@ -1,7 +1,7 @@ --- -title: MySQL Replication +title: Replication weight: 5 -aliases: ['/docs/reference/row-based-replication/','/docs/reference/vitess-replication/'] +aliases: ['/docs/reference/row-based-replication/','/docs/reference/vitess-replication/','/docs/reference/mysql-replication/'] --- {{< warning >}} diff --git a/content/en/docs/reference/schema-management.md b/content/en/docs/reference/features/schema-management.md similarity index 99% rename from content/en/docs/reference/schema-management.md rename to content/en/docs/reference/features/schema-management.md index a2f8c259f..ae8785bf3 100644 --- a/content/en/docs/reference/schema-management.md +++ b/content/en/docs/reference/features/schema-management.md @@ -1,6 +1,6 @@ --- title: Schema Management -aliases: ['/docs/schema-management/','/docs/user-guides/schema-management/'] +aliases: ['/docs/schema-management/','/docs/user-guides/schema-management/','/docs/reference/schema-management/'] --- Using Vitess requires you to work with two different types of schemas: diff --git a/content/en/docs/reference/schema-routing-rules.md b/content/en/docs/reference/features/schema-routing-rules.md similarity index 97% rename from content/en/docs/reference/schema-routing-rules.md rename to content/en/docs/reference/features/schema-routing-rules.md index e3b59194e..706e691f2 100644 --- a/content/en/docs/reference/schema-routing-rules.md +++ b/content/en/docs/reference/features/schema-routing-rules.md @@ -1,6 +1,6 @@ --- title: Schema Routing Rules -aliases: ['/docs/schema-management/routing-rules/'] +aliases: ['/docs/schema-management/routing-rules/','/docs/reference/schema-routing-rules/'] --- The Vitess routing rules feature is a powerful mechanism for directing traffic to the right keyspaces, shards or tablet types. diff --git a/content/en/docs/reference/sharding.md b/content/en/docs/reference/features/sharding.md similarity index 98% rename from content/en/docs/reference/sharding.md rename to content/en/docs/reference/features/sharding.md index 538289f89..323304cc1 100644 --- a/content/en/docs/reference/sharding.md +++ b/content/en/docs/reference/features/sharding.md @@ -2,7 +2,7 @@ title: Sharding description: Shard widely, shard often. weight: 5 -aliases: ['/docs/sharding/','/user-guide/sharding.html'] +aliases: ['/docs/sharding/','/user-guide/sharding.html','/docs/reference/sharding/'] --- Sharding is a method of horizontally partitioning a database to store data across two or more database servers. This document explains how sharding works in Vitess and the types of sharding that Vitess supports. diff --git a/content/en/docs/reference/topology-service.md b/content/en/docs/reference/features/topology-service.md similarity index 99% rename from content/en/docs/reference/topology-service.md rename to content/en/docs/reference/features/topology-service.md index 13b0a5a80..b808b2874 100644 --- a/content/en/docs/reference/topology-service.md +++ b/content/en/docs/reference/features/topology-service.md @@ -1,6 +1,6 @@ --- title: Topology Service -aliases: ['/docs/user-guides/topology-service/'] +aliases: ['/docs/user-guides/topology-service/','/docs/reference/topology-service/'] --- This document describes the Topology Service, a key part of the Vitess architecture. This service is exposed to all Vitess processes, and is used to store small pieces of configuration data about the Vitess cluster, and provide cluster-wide locks. It also supports watches, and master election. diff --git a/content/en/docs/reference/transport-security-model.md b/content/en/docs/reference/features/transport-security-model.md similarity index 97% rename from content/en/docs/reference/transport-security-model.md rename to content/en/docs/reference/features/transport-security-model.md index 5a1e7e08b..709a9b6e8 100644 --- a/content/en/docs/reference/transport-security-model.md +++ b/content/en/docs/reference/features/transport-security-model.md @@ -1,6 +1,6 @@ --- title: Transport Security Model -aliases: ['/docs/user-guides/transport-security-model/'] +aliases: ['/docs/user-guides/transport-security-model/','/docs/reference/transport-security-model/'] --- Vitess exposes a few RPC services, and internally also uses RPCs. These RPCs may use secure transport options. This document explains how to use these features. diff --git a/content/en/docs/reference/two-phase-commit.md b/content/en/docs/reference/features/two-phase-commit.md similarity index 98% rename from content/en/docs/reference/two-phase-commit.md rename to content/en/docs/reference/features/two-phase-commit.md index 0986d972b..42bd4ee2b 100644 --- a/content/en/docs/reference/two-phase-commit.md +++ b/content/en/docs/reference/features/two-phase-commit.md @@ -1,6 +1,6 @@ --- title: Two-Phase Commit -aliases: ['/docs/launching/twopc/'] +aliases: ['/docs/launching/twopc/','/docs/reference/two-phase-commit/'] --- {{< warning >}} diff --git a/content/en/docs/reference/vindexes.md b/content/en/docs/reference/features/vindexes.md similarity index 99% rename from content/en/docs/reference/vindexes.md rename to content/en/docs/reference/features/vindexes.md index 2da231562..9d63666fa 100644 --- a/content/en/docs/reference/vindexes.md +++ b/content/en/docs/reference/features/vindexes.md @@ -1,6 +1,6 @@ --- title: Vindexes -aliases: ['/docs/schema-management/consistent-lookup/'] +aliases: ['/docs/schema-management/consistent-lookup/','/docs/reference/vindexes/'] --- ## A Vindex maps column values to keyspace IDs diff --git a/content/en/docs/reference/vitess-sequences.md b/content/en/docs/reference/features/vitess-sequences.md similarity index 99% rename from content/en/docs/reference/vitess-sequences.md rename to content/en/docs/reference/features/vitess-sequences.md index 11c4b284e..a9da8e0d5 100644 --- a/content/en/docs/reference/vitess-sequences.md +++ b/content/en/docs/reference/features/vitess-sequences.md @@ -1,6 +1,7 @@ --- -title: Vitess Sequences +title: Sequences weight: 3 +aliases: ['/docs/reference/vitess-sequences/'] --- This document describes the Vitess Sequences feature, and how to use it. diff --git a/content/en/docs/reference/vreplication.md b/content/en/docs/reference/features/vreplication.md similarity index 99% rename from content/en/docs/reference/vreplication.md rename to content/en/docs/reference/features/vreplication.md index 6c4d843fd..ada693495 100644 --- a/content/en/docs/reference/vreplication.md +++ b/content/en/docs/reference/features/vreplication.md @@ -1,6 +1,6 @@ --- title: VReplication -aliases: ['/docs/advanced/vreplication/','/user-guide/update-stream/'] +aliases: ['/docs/advanced/vreplication/','/user-guide/update-stream/','/docs/reference/vreplication/'] --- VReplication is a core component of Vitess that can be used to compose diff --git a/content/en/docs/reference/vschema.md b/content/en/docs/reference/features/vschema.md similarity index 99% rename from content/en/docs/reference/vschema.md rename to content/en/docs/reference/features/vschema.md index 441de9d2e..376fec002 100644 --- a/content/en/docs/reference/vschema.md +++ b/content/en/docs/reference/features/vschema.md @@ -1,6 +1,6 @@ --- title: VSchema -aliases: ['/docs/schema-management/vschema/'] +aliases: ['/docs/schema-management/vschema/','/docs/reference/vschema/'] --- ## VSchemas describe how to shard data diff --git a/content/en/docs/reference/programs/_index.md b/content/en/docs/reference/programs/_index.md new file mode 100644 index 000000000..343c211c7 --- /dev/null +++ b/content/en/docs/reference/programs/_index.md @@ -0,0 +1,6 @@ +--- +title: Programs +description: Reference documents for list of Vitess programs +notoc: true +--- + diff --git a/content/en/docs/reference/programs/mysqlctl.md b/content/en/docs/reference/programs/mysqlctl.md new file mode 100644 index 000000000..4d189576a --- /dev/null +++ b/content/en/docs/reference/programs/mysqlctl.md @@ -0,0 +1,195 @@ +--- +title: mysqlctl +--- + +`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. + +## Commands + +### 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: + +```bash +export VTDATAROOT=/tmp +mysqlctl \ + -alsologtostderr \ + -tablet_uid 101 \ + -mysql_port 12345 \ + init +``` + +### init_config + +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: + +```bash +export VTDATAROOT=/tmp +mysqlctl \ + -alsologtostderr \ + -tablet_uid 101 \ + -mysql_port 12345 \ + init_config +``` + +### reinit_config + +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: + +```bash +export VTDATAROOT=/tmp +mysqlctl \ + -alsologtostderr \ + -tablet_uid 101 \ + -mysql_port 12345 \ + reinit_config +``` + +### teardown [-wait_time=5m] [-force] + +Remove the data files for a previously shutdown `mysqld` instance. This is a destructive operation: + +```bash +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`: + +```bash +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. + +```bash +export VTDATAROOT=/tmp +mysqlctl -tablet_uid 101 -alsologtostderr shutdown +``` + +## Options + +The following global parameters apply to `mysqlctl`: + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| alsologtostderr | boolean | log to standard error as well as files | +| app_idle_timeout | duration | Idle timeout for app connections (default 1m0s) | +| app_pool_size | int | Size of the connection pool for app connections (default 40) | +| 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 | boolean | if 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_hook | string | if set, we send the contents of the backup files through this hook. | +| 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) | +| cpu_profile | string | write cpu profile to file | +| 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 | +| db-credentials-file | string | db credentials file; send SIGHUP to reload this file | +| db-credentials-server | string | db credentials server type (use 'file' for the file implementation) (default "file") | +| db_charset | string | Character set. Only utf8 or latin1 based character sets are supported. | +| db_connect_timeout_ms | int | connection timeout to mysqld in milliseconds (0 for no timeout) | +| db_dba_password | string | db dba password | +| db_dba_use_ssl | boolean | Set this flag to false to make the dba connection to not use ssl (default true) | +| db_dba_user | string | db dba user userKey (default "vt_dba") | +| db_flags | uint | Flag values as defined by MySQL. | +| db_flavor | string | Flavor overrid. Valid value is FilePos. | +| db_host | string | The host name for the tcp connection. | +| db_port | int | tcp port | +| db_server_name | string | server name of the DB we are connecting to. | +| db_socket | string | The unix socket to connect on. If this is specified, host and port will not be used. | +| db_ssl_ca | string | connection ssl ca | +| db_ssl_ca_path | string | connection ssl ca path | +| db_ssl_cert | string | connection ssl certificate | +| db_ssl_key | string | connection ssl key | +| dba_idle_timeout | duration | Idle timeout for dba connections (default 1m0s) | +| dba_pool_size | int | Size of the connection pool for dba connections (default 20) | +| disable_active_reparents | boolean | if set, do not allow active reparents. Use this to protect a cluster using external reparents. | +| emit_stats | boolean | true iff we should emit stats to push-based monitoring/stats backends | +| grpc_auth_mode | string | Which auth plugin implementation to use (eg: static) | +| grpc_auth_mtls_allowed_substrings | string | List of substrings of at least one of the client certificate names (separated by colon). | +| 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_auth_static_password_file | string | JSON File to read the users/passwords from. | +| grpc_ca | string | ca to use, requires TLS, and enforces client cert check | +| grpc_cert | string | certificate to use, requires grpc_key, enables TLS | +| grpc_compression | string | how to compress gRPC, default: nothing, supported: snappy | +| grpc_enable_tracing | boolean | 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_key | string | key to use, requires grpc_cert, enables TLS | +| grpc_max_connection_age | duration | Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) | +| grpc_max_connection_age_grace | duration | Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) | +| 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_port | int | Port to listen on for gRPC calls | +| grpc_prometheus | boolean | Enable gRPC monitoring with Prometheus | +| grpc_server_initial_conn_window_size | int | gRPC server initial connection window size | +| grpc_server_initial_window_size | int | gRPC server initial window size | +| grpc_server_keepalive_enforcement_policy_min_time | duration | gRPC server minimum keepalive time (default 5m0s) | +| grpc_server_keepalive_enforcement_policy_permit_without_stream | boolean | gRPC server permit client keepalive pings even when there are no active streams (RPCs) | +| 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) | +| lameduck-period | duration | keep running at least this long after SIGTERM before stopping (default 50ms) | +| 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 | boolean | log stack traces for errors | +| log_rotate_max_size | uint | size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) | +| logtostderr | boolean | log to standard error instead of files | +| master_connect_retry | duration | how long to wait in between slave -> connection attempts. Only precise to the second. (default 10s) | +| mem-profile-rate | int | profile every n bytes allocated (default 524288) | +| mutex-profile-fraction | int | profile every n mutex contention events (see runtime.SetMutexProfileFraction) | +| mysql_auth_server_static_file | string | JSON File to read the users/passwords from. | +| mysql_auth_server_static_string | string | JSON representation of the users/passwords config. | +| mysql_auth_static_reload_interval | duration | Ticker to reload credentials | +| mysql_clientcert_auth_method | string | client-side authentication method to use. Supported values: mysql_clear_password, dialog. (default "mysql_clear_password") | +| mysql_port | int | mysql port (default 3306) | +| mysql_server_flush_delay | duration | Delay after which buffered response will be flushed to the client. (default 100ms) | +| mysql_socket | string | path to the mysql socket | +| mysqlctl_client_protocol | string | the protocol to use to talk to the mysqlctl server (default "grpc") | +| mysqlctl_mycnf_template | string | template file to use for generating the my.cnf file during server init | +| mysqlctl_socket | string | socket file to use for remote mysqlctl actions (empty for local actions) | +| onterm_timeout | duration | wait no more than this for OnTermSync handlers before stopping (default 10s) | +| pid_file | string | If set, the process will write its pid to the named file, and delete it on graceful shutdown. | +| pool_hostname_resolve_interval | duration | if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) | +| port | int | vttablet port (default 6612) | +| 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) | +| 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-vtworker | +| 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) | +| stats_backend | string | The name of the registered push-based monitoring/stats backend to use | +| stats_combine_dimensions | string | List of dimensions to be combined into a single "all" value in exported stats vars | +| stats_drop_variables | string | Variables to be dropped from the list of exported variables. | +| stats_emit_period | duration | Interval between emitting stats to all registered backends (default 1m0s) | +| stderrthreshold | value | logs at or above this threshold go to stderr (default 1) | +| tablet_dir | string | The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. | +| tablet_manager_protocol | string | the protocol to use to talk to vttablet (default "grpc") | +| tablet_uid | uint | tablet uid (default 41983) | +| 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 | +| tracer | string | tracing service to use (default "noop") | +| tracing-sampling-rate | float | sampling rate for the probabilistic jaeger sampler (default 0.1) | +| v | value | log level for V logs | +| version | boolean | print binary version | +| vmodule | value | comma-separated list of pattern=N settings for file-filtered logging | +| xbstream_restore_flags | string | flags 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_flags | string | flags to pass to backup command. These should be space separated and will be added to the end of the command | +| xtrabackup_prepare_flags | string | flags to pass to prepare command. These should be space separated and will be added to the end of the command | +| xtrabackup_root_path | string | directory location of the xtrabackup executable, e.g., /usr/bin | +| xtrabackup_stream_mode | string | which mode to use if streaming, valid values are tar and xbstream (default "tar") | +| xtrabackup_stripe_block_size | uint | Size in bytes of each block that gets sent to a given stripe before rotating to the next stripe (default 102400) | +| xtrabackup_stripes | uint | If greater than 0, use data striping across this many destination files to parallelize data transfer and decompression | +| xtrabackup_user | string | User that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation. diff --git a/content/en/docs/reference/programs/regular-expression.txt b/content/en/docs/reference/programs/regular-expression.txt new file mode 100644 index 000000000..92dd1960c --- /dev/null +++ b/content/en/docs/reference/programs/regular-expression.txt @@ -0,0 +1,11 @@ +Format Options: + + +Find: \n ([^ ]+) ?(.+)?\n \t(.+) +Replace: | \1 | \2 | \3 |\n + + +Format vtctl table: + +Find: ([a-z]+)(.+) +Replace: | [\1](../vtctl/serving-graph#\1) | `\1 \2` | \ No newline at end of file diff --git a/content/en/docs/reference/programs/vtctl.md b/content/en/docs/reference/programs/vtctl.md new file mode 100644 index 000000000..7cea0d1e4 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl.md @@ -0,0 +1,428 @@ +--- +title: vtctl +description: vtctl Command Index +aliases: ['/docs/reference/vitess-api/','/docs/reference/vtctl/'] +--- + +`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. + +## Commands + +### Tablets + +| Name | Example Usage | +| :-------- | :--------- | +| [InitTablet](../vtctl/tablets#inittablet) | `InitTablet [-allow_update] [-allow_different_shard] [-allow_master_override] [-parent] [-db_name_override=] [-hostname=] [-mysql_port=] [-port=] [-grpc_port=] [-tags=tag1:value1,tag2:value2] -keyspace= -shard= ` | +| [GetTablet](../vtctl/tablets#gettablet) | `GetTablet ` | +| [UpdateTabletAddrs](../vtctl/tablets#updatetabletaddrs) | `UpdateTabletAddrs [-hostname ] [-ip-addr ] [-mysql-port ] [-vt-port ] [-grpc-port ] ` | +| [DeleteTablet](../vtctl/tablets#deletetablet) | `DeleteTablet [-allow_master] ...` | +| [SetReadOnly](../vtctl/tablets#setreadonly) | `SetReadOnly ` | +| [SetReadWrite](../vtctl/tablets#setreadwrite) | `SetReadWrite ` | +| [StartSlave](../vtctl/tablets#startslave) | `StartSlave ` | +| [StopSlave](../vtctl/tablets#stopslave) | `StopSlave ` | +| [ChangeSlaveType](../vtctl/tablets#changeslavetype) | `ChangeSlaveType [-dry-run] ` | +| [Ping](../vtctl/tablets#ping) | `Ping ` | +| [RefreshState](../vtctl/tablets#refreshstate) | `RefreshState ` | +| [RefreshStateByShard](../vtctl/tablets#refreshstatebyshard) | `RefreshStateByShard [-cells=c1,c2,...] ` | +| [RunHealthCheck](../vtctl/tablets#runhealthcheck) | `RunHealthCheck ` | +| [IgnoreHealthError](../vtctl/tablets#ignorehealtherror) | `IgnoreHealthError ` | +| [Sleep](../vtctl/tablets#sleep) | `Sleep ` | +| [ExecuteHook](../vtctl/tablets#executehook) | `ExecuteHook [ ...]` | +| [ExecuteFetchAsApp](../vtctl/tablets#executefetchasapp) | `ExecuteFetchAsApp [-max_rows=10000] [-json] [-use_pool] ` | +| [ExecuteFetchAsDba](../vtctl/tablets#executefetchasdba) | `ExecuteFetchAsDba [-max_rows=10000] [-disable_binlogs] [-json] ` | +| [VReplicationExec](../vtctl/tablets#vreplicationexec) | `VReplicationExec [-json] ` | +| [Backup](../vtctl/tablets#backup) | `Backup [-concurrency=4] [-allow_master=false] ` | +| [RestoreFromBackup](../vtctl/tablets#restorefrombackup) | `RestoreFromBackup ` | +| [ReparentTablet](../vtctl/tablets#reparenttablet) | `ReparentTablet ` | + +### Shards + +| Name | Example Usage | +| :-------- | :--------- | +| [CreateShard](../vtctl/shards#createshard) | `CreateShard [-force] [-parent] ` | +| [GetShard](../vtctl/shards#getshard) | `GetShard ` | +| [ValidateShard](../vtctl/shards#validateshard) | `ValidateShard [-ping-tablets] ` | +| [ShardReplicationPositions](../vtctl/shards#shardreplicationpositions) | `ShardReplicationPositions ` | +| [ListShardTablets](../vtctl/shards#listshardtablets) | `ListShardTablets ` | +| [SetShardIsMasterServing](../vtctl/shards#setshardismasterserving) | `SetShardIsMasterServing ` | +| [SetShardTabletControl](../vtctl/shards#setshardtabletcontrol) | `SetShardTabletControl [--cells=c1,c2,...] [--blacklisted_tables=t1,t2,...] [--remove] [--disable_query_service] ` | +| [UpdateSrvKeyspacePartition](../vtctl/shards#updatesrvkeyspacepartition)| `UpdateSrvKeyspacePartition [--cells=c1,c2,...] [--remove] ` | +| [SourceShardDelete](../vtctl/shards#sourcesharddelete) | `SourceShardDelete ` | +| [SourceShardAdd](../vtctl/shards#sourceshardadd) | `SourceShardAdd [--key_range=] [--tables=] ` | +| [ShardReplicationFix](../vtctl/shards#shardreplicationfix) | `ShardReplicationFix ` | +| [WaitForFilteredReplication](../vtctl/shards#waitforfilteredreplication) | `WaitForFilteredReplication [-max_delay ] ` | +| [RemoveShardCell](../vtctl/shards#removeshardcell) | `RemoveShardCell [-force] [-recursive] ` | +| [DeleteShard](../vtctl/shards#deleteshard) | `DeleteShard [-recursive] [-even_if_serving] ...` | +| [ListBackups](../vtctl/shards#listbackups) | `ListBackups ` | +| [BackupShard](../vtctl/shards#backupshard) | `BackupShard [-allow_master=false] ` | +| [RemoveBackup](../vtctl/shards#removebackup) | `RemoveBackup ` | +| [InitShardMaster](../vtctl/shards#initshardmaster) | `InitShardMaster [-force] [-wait_slave_timeout=] ` | +| [PlannedReparentShard](../vtctl/shards#plannedreparentshard) | `PlannedReparentShard -keyspace_shard= [-new_master=] [-avoid_master=] [-wait_slave_timeout=]` | +| [EmergencyReparentShard](../vtctl/shards#emergencyreparentshard) | `EmergencyReparentShard -keyspace_shard= -new_master=` | +| [TabletExternallyReparented](../vtctl/shards#tabletexternallyreparented) | `TabletExternallyReparented ` | + +### Keyspaces + +| Name | Example Usage | +| :-------- | :--------- | +| [CreateKeyspace](../vtctl/keyspaces#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] ` | +| [DeleteKeyspace](../vtctl/keyspaces#deletekeyspace) | `DeleteKeyspace [-recursive] ` | +| [RemoveKeyspaceCell](../vtctl/keyspaces#removekeyspacesell) | `RemoveKeyspaceCell [-force] [-recursive] ` | +| [GetKeyspace](../vtctl/keyspaces#getkeyspace) | `GetKeyspace ` | +| [GetKeyspaces](../vtctl/keyspaces#getkeyspaces) | `GetKeyspaces ` | +| [SetKeyspaceShardingInfo](../vtctl/keyspaces#setkeyspaceshardinginfo) | `SetKeyspaceShardingInfo [-force] [] []` | +| [SetKeyspaceServedFrom](../vtctl/keyspaces#setkeyspaceservedfrom) | `SetKeyspaceServedFrom [-source=] [-remove] [-cells=c1,c2,...] ` | +| [RebuildKeyspaceGraph](../vtctl/keyspaces#rebuildkeyspacegraph) | `RebuildKeyspaceGraph [-cells=c1,c2,...] ...` | +| [ValidateKeyspace](../vtctl/keyspaces#validatekeyspace) | `ValidateKeyspace [-ping-tablets] ` | +| [Reshard](../vtctl/keyspaces#reshard) | `Reshard [-skip_schema_copy] ` | +| [MoveTables](../vtctl/keyspaces#movetables) | `MoveTables [-cell=] [-tablet_types=] -workflow= ` | +| [DropSources](../vtctl/keyspaces#dropsources) | `DropSources [-dry_run] ` | +| [CreateLookupVindex](../vtctl/keyspaces#createLookupvindex) | `CreateLookupVindex [-cell=] [-tablet_types=] ` | +| [ExternalizeVindex](../vtctl/keyspaces#externalizevindex) | `ExternalizeVindex .` | +| [Materialize](../vtctl/keyspaces#materialize) | `Materialize , example : '{"workflow": "aaa", "source_keyspace": "source", "target_keyspace": "target", "table_settings": [{"target_table": "customer", "source_expression": "select * from customer", "create_ddl": "copy"}]}'` | +| [SplitClone](../vtctl/keyspaces#splitclone) | `SplitClone ` | +| [VerticalSplitClone](../vtctl/keyspaces#verticalsplitclone) | `VerticalSplitClone ` | +| [VDiff](../vtctl/keyspaces#VDiff) | `VDiff [-source_cell=] [-target_cell=] [-tablet_types=replica] [-filtered_replication_wait_time=30s] ` | +| [MigrateServedTypes](../vtctl/keyspaces#migrateservedtypes) | `MigrateServedTypes [-cells=c1,c2,...] [-reverse] [-skip-refresh-state] ` | +| [MigrateServedFrom](../vtctl/keyspaces#migrateservedfrom) | `MigrateServedFrom [-cells=c1,c2,...] [-reverse] ` | +| [SwitchReads](../vtctl/keyspaces#switchreads) | `SwitchReads [-cells=c1,c2,...] [-reverse] -tablet_type={replica|rdonly} [-dry-run] ` | +| [SwitchWrites](../vtctl/keyspaces#switchwrites) | `SwitchWrites [-filtered_replication_wait_time=30s] [-cancel] [-reverse_replication=false] [-dry-run] ` | +| [CancelResharding](../vtctl/keyspaces#cancelresharding) | `CancelResharding ` | +| [ShowResharding](../vtctl/keyspaces#showresharding) | `ShowResharding ` | +| [FindAllShardsInKeyspace](../vtctl/keyspaces#findallshardsinkeyspace) | `FindAllShardsInKeyspace ` | +| [WaitForDrain](../vtctl/keyspaces#waitfordrain) | `WaitForDrain [-timeout ] [-retry_delay ] [-initial_wait ] ` | + +### Generic + +| Name | Example Usage | +| :-------- | :--------- | +| [Validate](../vtctl/generic#validate) | `Validate [-ping-tablets]` | +| [ListAllTablets](../vtctl/generic#listalltablets) | `ListAllTablets , , ...` | +| [ListTablets](../vtctl/generic#listtablets) | `ListTablets ...` | +| [Help](../vtctl/generic#help) | `Help [command name]` | + +### Schema, Version, Permissions + +| Name | Example Usage | +| :-------- | :--------- | +| [GetSchema](../vtctl/schema-version-permissions#getschema) | `GetSchema [-tables=,,...] [-exclude_tables=,,...] [-include-views] ` | +| [ReloadSchema](../vtctl/schema-version-permissions#reloadschema) | `ReloadSchema ` | +| [ReloadSchemaShard](../vtctl/schema-version-permissions#reloadschemashard) | `ReloadSchemaShard [-concurrency=10] [-include_master=false] ` | +| [ReloadSchemaKeyspace](../vtctl/schema-version-permissions#reloadschemakeyspace) | `ReloadSchemaKeyspace [-concurrency=10] [-include_master=false] ` | +| [ValidateSchemaShard](../vtctl/schema-version-permissions#validateschemashard) | `ValidateSchemaShard [-exclude_tables=''] [-include-views] ` | +| [ValidateSchemaKeyspace](../vtctl/schema-version-permissions#validateschemakeyspace) | `ValidateSchemaKeyspace [-exclude_tables=''] [-include-views] ` | +| [ApplySchema](../vtctl/schema-version-permissions#applyschema) | `ApplySchema [-allow_long_unavailability] [-wait_slave_timeout=10s] {-sql= || -sql-file=} ` | +| [CopySchemaShard](../vtctl/schema-version-permissions#copyschemashard) | `CopySchemaShard [-tables=,,...] [-exclude_tables=,,...] [-include-views] [-skip-verify] [-wait_slave_timeout=10s] { || } ` | +| [ValidateVersionShard](../vtctl/schema-version-permissions#validateversionshard) | `ValidateVersionShard ` | +| [ValidateVersionKeyspace](../vtctl/schema-version-permissions#validateversionkeyspace) | `ValidateVersionKeyspace ` | +| [GetPermissions](../vtctl/schema-version-permissions#getpermissions) | `GetPermissions ` | +| [ValidatePermissionsShard](../vtctl/schema-version-permissions#validatepermissionsshard) | `ValidatePermissionsShard ` | +| [ValidatePermissionsKeyspace](../vtctl/schema-version-permissions#validatepermissionskeyspace) | `ValidatePermissionsKeyspace ` | +| [GetVSchema](../vtctl/schema-version-permissions#getvschema) | `GetVSchema ` | +| [ApplyVSchema](../vtctl/schema-version-permissions#applyvschema) | `ApplyVSchema {-vschema= || -vschema_file= || -sql= || -sql_file=} [-cells=c1,c2,...] [-skip_rebuild] [-dry-run] ` | +| [GetRoutingRules](../vtctl/schema-version-permissions#getroutingrules) | `GetRoutingRules ` | +| [ApplyRoutingRules](../vtctl/schema-version-permissions#applyroutingrules) | `ApplyRoutingRules {-rules= || -rules_file=} [-cells=c1,c2,...] [-skip_rebuild] [-dry-run]` | +| [RebuildVSchemaGraph](../vtctl/schema-version-permissions#rebuildvschemagraph) | `RebuildVSchemaGraph [-cells=c1,c2,...]` | + +### Serving Graph + +| Name | Example Usage | +| :-------- | :--------- | +| [GetSrvKeyspaceNames](../vtctl/serving-graph#getsrvkeyspacenames) | `GetSrvKeyspaceNames ` | +| [GetSrvKeyspace](../vtctl/serving-graph#getsrvkeyspace) | `GetSrvKeyspace ` | +| [GetSrvVSchema](../vtctl/serving-graph#getsrvsvchema) | `GetSrvVSchema ` | +| [DeleteSrvVSchema](../vtctl/serving-graph#deletesrvvschema) | `DeleteSrvVSchema ` | + +### Replication Graph + +| Name | Example Usage | +| :-------- | :--------- | +| [GetShardReplication](../vtctl/replication-graph#getshardreplication) | `GetShardReplication ` | + +### Cells + +| Name | Example Usage | +| :-------- | :--------- | +| [AddCellInfo](../vtctl/cells#addcellinfo) | `AddCellInfo [-server_address ] [-root ] ` | +| [UpdateCellInfo](../vtctl/cells#updatecellinfo) | `UpdateCellInfo [-server_address ] [-root ] ` | +| [DeleteCellInfo](../vtctl/cells#deletecellinfo) | `DeleteCellInfo [-force] ` | +| [GetCellInfoNames](../vtctl/cells#getcellinfonames) | `GetCellInfoNames ` | +| [GetCellInfo](../vtctl/cells#getcellinfo) | `GetCellInfo ` | + +### CellsAliases + +| Name | Example Usage | +| :-------- | :--------- | +| [AddCellsAlias](../vtctl/cell-aliases#addcellsalias) | `AddCellsAlias [-cells ] ` | +| [UpdateCellsAlias](../vtctl/cell-aliases#updatecellsalias) | `UpdateCellsAlias [-cells ] ` | +| [DeleteCellsAlias](../vtctl/cell-aliases#deletecellsalias) | `DeleteCellsAlias ` | +| [GetCellsAliases](../vtctl/cell-aliases#getcellsaliases) | `GetCellsAliases ` | + +### Queries + +| Name | Example Usage | +| :-------- | :--------- | +| [VtGateExecute](../vtctl/queries#vtgateexecute) | `VtGateExecute -server [-bind_variables ] [-keyspace ] [-tablet_type ] [-options ] [-json] ` | +| [VtTabletExecute](../vtctl/queries#vttabletexecute) | `VtTabletExecute [-username ] [-transaction_id ] [-options ] [-json] ` | +| [VtTabletBegin](../vtctl/queries#vttabletbegin) | `VtTabletBegin [-username ] ` | +| [VtTabletCommit](../vtctl/queries#vttabletcommit) | `VtTabletCommit [-username ] ` | +| [VtTabletRollback](../vtctl/queries#vttabletrollback) | `VtTabletRollback [-username ] ` | +| [VtTabletStreamHealth](../vtctl/queries#vttabletstreamhealth) | `VtTabletStreamHealth [-count ] ` | + +### Resharding Throttler + +| Name | Example Usage | +| :-------- | :--------- | +| [ThrottlerMaxRates](../vtctl/resharding-throttler#throttlermaxrates) | `ThrottlerMaxRates -server ` | +| [ThrottlerSetMaxRate](../vtctl/resharding-throttler#throttlersetmaxrate) | `ThrottlerSetMaxRate -server ` | +| [GetThrottlerConfiguration](../vtctl/resharding-throttler#getthrottlerconfiguration) | `GetThrottlerConfiguration -server []` | +| [UpdateThrottlerConfiguration](../vtctl/resharding-throttler#updatethrottlerconfiguration) | `UpdateThrottlerConfiguration -server [-copy_zero_values] "" []` | +| [ResetThrottlerConfiguration](../vtctl/resharding-throttler#resetthrottlerconfiguration) | `ResetThrottlerConfiguration -server []` | + +### Topo + +| Name | Example Usage | +| :-------- | :--------- | +| [TopoCat](../vtctl/topo#topocat) | `TopoCat [-cell ] [-decode_proto] [-decode_proto_json] [-long] [...]` | +| [TopoCp](../vtctl/topo#topocp) | `TopoCp [-cell ] [-to_topo] ` | + +### Workflows + +| Name | Example Usage | +| :-------- | :--------- | +| [WorkflowCreate](../vtctl/workflows#workflowcreate) | `WorkflowCreate [-skip_start] [parameters...]` | +| [WorkflowStart](../vtctl/workflows#workflowstart) | `WorkflowStart ` | +| [WorkflowStop](../vtctl/workflows#workflowstop) | `WorkflowStop ` | +| [WorkflowDelete](../vtctl/workflows#workflowdelete) | `WorkflowDelete ` | +| [WorkflowWait](../vtctl/workflows#workflowwait) | `WorkflowWait ` | +| [WorkflowTree](../vtctl/workflows#workflowtree) | `WorkflowTree ` | +| [WorkflowAction](../vtctl/workflows#workflowaction) | `WorkflowAction ` | + +## Options + +The following global options apply to `vtctl`: + + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| -alsologtostderr | | log to standard error as well as files| -app_idle_timeout | duration | Idle timeout for app connections (default 1m0s) | +| -app_pool_size | int | Size of the connection pool for app connections (default 40) | +| -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_container_name | string | Azure Blob Container Name | +| -azblob_backup_parallelism | int | Azure Blob operation parallelism (requires extra memory when increased) (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). Set to false for instance if a backup_storage_hook is specified and it compresses the data. (default true)| -backup_storage_hook | string | if set, we send the contents of the backup files through this hook. | +| -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) | +| -binlog_player_protocol | string | the protocol to download binlogs from a vttablet (default "grpc") | +| -binlog_use_v3_resharding_mode | | True iff the binlog streamer should use V3-style sharding, which doesn't require a preset sharding key column. (default true)| -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. | +| -cpu_profile | string | write cpu profile to file | +| -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 | +| -db-credentials-file | string | db credentials file; send SIGHUP to reload this file | +| -db-credentials-server | string | db credentials server type (use 'file' for the file implementation) (default "file") | +| -dba_idle_timeout | duration | Idle timeout for dba connections (default 1m0s) | +| -dba_pool_size | int | Size of the connection pool for dba connections (default 20) | +| -detach | | detached mode - run vtcl detached from the terminal | +| -disable_active_reparents | | if set, do not allow active reparents. Use this to protect a cluster using external reparents. | +| -discovery_high_replication_lag_minimum_serving | duration | the replication lag that is considered too high when selecting the minimum num vttablets for serving (default 2h0m0s) | +| -discovery_low_replication_lag | duration | the replication lag that is considered low enough to be healthy (default 30s) | +| -emit_stats | | true iff we should emit stats to push-based monitoring/stats backends | +| -enable-consolidator | | This option enables the query consolidator. (default true) | +| -enable-consolidator-replicas | | This option enables the query consolidator only on replicas. | +| -enable-query-plan-field-caching | | This option fetches & caches fields (columns) when storing query plans (default true) | +| -enable-tx-throttler | | If true replication-lag-based throttling on transactions will be enabled. | +| -enable_hot_row_protection | | If true, incoming transactions for the same row (range) will be queued and cannot consume all txpool slots. | +| -enable_hot_row_protection_dry_run | | If true, hot row protection is not enforced but logs if transactions would have been queued. | +| -enable_queries | | if set, allows vtgate and vttablet queries. May have security implications, as the queries will be run from this process. | +| -enable_transaction_limit | | If true, limit on number of transactions open at the same time will be enforced for all users. User trying to open a new transaction after exhausting their limit will receive an error immediately, regardless of whether there are available slots or not. | +| -enable_transaction_limit_dry_run | | If true, limit on number of transactions open at the same time will be tracked for all users, but not enforced. | +| -enforce_strict_trans_tables | | If true, vttablet requires MySQL to run with STRICT_TRANS_TABLES or STRICT_ALL_TABLES on. It is recommended to not turn this flag off. Otherwise MySQL may alter your supplied values before saving them to the database. (default true)| -file_backup_storage_root | string | root directory for the file backup storage | +| -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_mode | string | Which auth plugin implementation to use (eg: static) | +| -grpc_auth_mtls_allowed_substrings | string | List of substrings of at least one of the client certificate names (separated by colon). | +| -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_auth_static_password_file | string | JSON File to read the users/passwords from. | +| -grpc_ca | string | ca to use, requires TLS, and enforces client cert check | +| -grpc_cert | string | certificate to use, requires grpc_key, enables TLS | +| -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_key | string | key to use, requires grpc_cert, enables TLS | +| -grpc_max_connection_age | duration | Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) | +| -grpc_max_connection_age_grace | duration | Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) | +| -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_port | int | Port to listen on for gRPC calls | +| -grpc_prometheus | | Enable gRPC monitoring with Prometheus | +| -grpc_server_initial_conn_window_size | int | grpc server initial connection window size | +| -grpc_server_initial_window_size | int | grpc server initial window size | +| -grpc_server_keepalive_enforcement_policy_min_time | duration | grpc server minimum keepalive time (default 5m0s) | +| -grpc_server_keepalive_enforcement_policy_permit_without_stream | | grpc server permit client keepalive pings even when there are no active streams (RPCs) | +| -heartbeat_enable | | If true, vttablet records (if master) or checks (if replica) the current time of a replication heartbeat in the table _vt.heartbeat. The result is used to inform the serving state of the vttablet via healthchecks.| -heartbeat_interval | duration | How frequently to read and write replication heartbeat. (default 1s) | +| -hot_row_protection_concurrent_transactions | int | Number of concurrent transactions let through to the txpool/MySQL for the same hot row. Should be > 1 to have enough 'ready' transactions in MySQL and benefit from a pipelining effect. (default 5) | +| -hot_row_protection_max_global_queue_size | int | Global queue limit across all row (ranges). Useful to prevent that the queue can grow unbounded. (default 1000) | +| -hot_row_protection_max_queue_size | int | Maximum number of BeginExecute RPCs which will be queued for the same row (range). (default 20) | +| -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) | +| -lameduck-period | duration | keep running at least this long after SIGTERM before stopping (default 50ms) | +| -legacy_replication_lag_algorithm | | use the legacy algorithm when selecting the vttablets for serving (default true) | +| -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 | +| -master_connect_retry | duration | how long to wait in between slave -> connection attempts. Only precise to the second. (default 10s) | +| -mem-profile-rate | int | profile every n bytes allocated (default 524288) | +| -min_number_serving_vttablets | int | the minimum number of vttablets that will be continue to be used even with low replication lag (default 2) | +| -mutex-profile-fraction | int | profile every n mutex contention events (see runtime.SetMutexProfileFraction) | +| -mysql_auth_server_static_file | string | JSON File to read the users/passwords from. | +| -mysql_auth_server_static_string | string | JSON representation of the users/passwords config. | +| -mysql_auth_static_reload_interval | duration | Ticker to reload credentials | +| -mysql_clientcert_auth_method | string | client-side authentication method to use. Supported values: mysql_clear_password, dialog. (default "mysql_clear_password") | +| -mysql_server_flush_delay | duration | Delay after which buffered response will flushed to client. (default 100ms) | +| -mysqlctl_client_protocol | string | the protocol to use to talk to the mysqlctl server (default "grpc") | +| -mysqlctl_mycnf_template | string | template file to use for generating the my.cnf file during server init | +| -mysqlctl_socket | string | socket file to use for remote mysqlctl actions (empty for local actions) | +| -onterm_timeout | duration | wait no more than this for OnTermSync handlers before stopping (default 10s) | +| -pid_file | string | If set, the process will write its pid to the named file, and delete it on graceful shutdown. | +| -pool_hostname_resolve_interval | duration | if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) | +| -purge_logs_interval | duration | how often try to remove old logs (default 1h0m0s) | +| -query-log-stream-handler | string | URL handler for streaming queries log (default "/debug/querylog") | +| -querylog-filter-tag | string | string that must be present in the query for it to be logged | +| -querylog-format | string | format for query logs ("text" or "json") (default "text") | +| -queryserver-config-acl-exempt-acl | string | an acl that exempt from table acl checking (this acl is free to access any vitess tables). | +| -queryserver-config-enable-table-acl-dry-run | | If this flag is enabled, tabletserver will emit monitoring metrics and let the request pass regardless of table acl check results | +| -queryserver-config-idle-timeout | int | query server idle timeout (in seconds), vttablet manages various mysql connection pools. This config means if a connection has not been used in given idle timeout, this connection will be removed from pool. This effectively manages number of connection objects and optimize the pool performance. (default 1800) | +| -queryserver-config-max-dml-rows | int | query server max dml rows per statement, maximum number of rows allowed to return at a time for an update or delete with either 1) an equality where clauses on primary keys, or 2) a subselect statement. For update and delete statements in above two categories, vttablet will split the original query into multiple small queries based on this configuration value. | +| -queryserver-config-max-result-size | int | query server max result size, maximum number of rows allowed to return from vttablet for non-streaming queries. (default 10000) | +| -queryserver-config-message-conn-pool-prefill-parallelism | int | DEPRECATED: Unused. | +| -queryserver-config-message-conn-pool-size | int | DEPRECATED | +| -queryserver-config-message-postpone-cap | int | query server message postpone cap is the maximum number of messages that can be postponed at any given time. Set this number to substantially lower than transaction cap, so that the transaction pool isn't exhausted by the message subsystem. (default 4) | +| -queryserver-config-passthrough-dmls | query server pass through all dml statements without rewriting | +| -queryserver-config-pool-prefill-parallelism | int | query server read pool prefill parallelism, a non-zero value will prefill the pool using the specified parallism. | +| -queryserver-config-pool-size | int | query server read pool size, connection pool is used by regular queries (non streaming, not in a transaction) (default 16) | +| -queryserver-config-query-cache-size | int | query server query cache size, maximum number of queries to be cached. vttablet analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 5000) | +| -queryserver-config-query-pool-timeout | int | query server query pool timeout (in seconds), it is how long vttablet waits for a connection from the query pool. If set to 0 (default) then the overall query timeout is used instead. | +| -queryserver-config-query-pool-waiter-cap | int | query server query pool waiter limit, this is the maximum number of queries that can be queued waiting to get a connection (default 5000) | +| -queryserver-config-query-timeout | int | query server query timeout (in seconds), this is the query timeout in vttablet side. If a query takes more than this timeout, it will be killed. (default 30) | +| -queryserver-config-schema-reload-time | int | query server schema reload time, how often vttablet reloads schemas from underlying MySQL instance in seconds. vttablet keeps table schemas in its own memory and periodically refreshes it from MySQL. This config controls the reload time. (default 1800) | +| -queryserver-config-stream-buffer-size | int | query server stream buffer size, the maximum number of bytes sent from vttablet for each stream call. It's recommended to keep this value in sync with vtgate's stream_buffer_size. (default 32768) | +| -queryserver-config-stream-pool-prefill-parallelism | int | query server stream pool prefill parallelism, a non-zero value will prefill the pool using the specified parallelism | +| -queryserver-config-stream-pool-size | int | query server stream connection pool size, stream pool is used by stream queries: queries that return results to client in a streaming fashion (default 200) | +| -queryserver-config-strict-table-acl | | only allow queries that pass table acl checks | +| -queryserver-config-terse-errors | | prevent bind vars from escaping in returned errors | +| -queryserver-config-transaction-cap | int | query server transaction cap is the maximum number of transactions allowed to happen at any given point of a time for a single vttablet. E.g. by setting transaction cap to 100, there are at most 100 transactions will be processed by a vttablet and the 101th transaction will be blocked (and fail if it cannot get connection within specified timeout) (default 20) | +| -queryserver-config-transaction-prefill-parallelism | int | query server transaction prefill parallelism, a non-zero value will prefill the pool using the specified parallism. | +| -queryserver-config-transaction-timeout | int | query server transaction timeout (in seconds), a transaction will be killed if it takes longer than this value (default 30) | +| -queryserver-config-txpool-timeout | int | query server transaction pool timeout, it is how long vttablet waits if tx pool is full (default 1) | +| -queryserver-config-txpool-waiter-cap | int | query server transaction pool waiter limit, this is the maximum number of transactions that can be queued waiting to get a connection (default 5000) | +| -queryserver-config-warn-result-size | int | query server result size warning threshold, warn if number of rows returned from vttablet for non-streaming queries exceeds this | +| -redact-debug-ui-queries | | redact full queries and bind variables from debug UI | +| -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-vtworker | +| -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) | +| -srv_topo_cache_refresh | duration | how frequently to refresh the topology for cached entries (default 1s) | +| -srv_topo_cache_ttl | duration | how long to use cached entries for topology (default 1s) | +| -stats_backend | string | The name of the registered push-based monitoring/stats backend to use | +| -stats_combine_dimensions | string | List of dimensions to be combined into a single "all" value in exported stats vars | +| -stats_drop_variables | string | Variables to be dropped from the list of exported variables. | +| -stats_emit_period | duration | Interval between emitting stats to all registered backends (default 1m0s) | +| -stderrthreshold | value | logs at or above this threshold go to stderr (default 1) | +| -tablet_dir | string | The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. | +| -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_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_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") | +| -tablet_url_template | string | format string describing debug tablet url formatting. See the Go code for getTabletDebugURL() how to customize this. (default "http://{{.GetTabletHostPort}}") | +| -throttler_client_grpc_ca | string | the server ca to use to validate servers when connecting | +| -throttler_client_grpc_cert | string | the cert to use to connect | +| -throttler_client_grpc_key | string | the key to use to connect | +| -throttler_client_grpc_server_name | string | the server name to use to validate server certificate | +| -throttler_client_protocol | string | the protocol to use to talk to the integrated throttler service (default "grpc") | +| -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 master 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_k8s_context | string | The kubeconfig context to use, overrides the 'current-context' from the config | +| -topo_k8s_kubeconfig | string | Path to a valid kubeconfig file. | +| -topo_k8s_namespace | string | The kubernetes namespace to use for all objects. Default comes from the context or in-cluster config | +| -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-sampling-rate | float | sampling rate for the probabilistic jaeger sampler (default 0.1) | +| -transaction-log-stream-handler | string | URL handler for streaming transactions log (default "/debug/txlog") | +| -transaction_limit_by_component | | Include CallerID.component when considering who the user is for the purpose of transaction limit. | +| -transaction_limit_by_principal | | Include CallerID.principal when considering who the user is for the purpose of transaction limit. (default true) | +| -transaction_limit_by_subcomponent | | Include CallerID.subcomponent when considering who the user is for the purpose of transaction limit. | +| -transaction_limit_by_username | | Include VTGateCallerID.username when considering who the user is for the purpose of transaction limit. (default true)| +| -transaction_limit_per_user | float | Maximum number of transactions a single user is allowed to use at any time, represented as fraction of -transaction_cap. (default 0.4) | +| -transaction_shutdown_grace_period | int | how long to wait (in seconds) for transactions to complete during graceful shutdown. | +| -twopc_abandon_age | float | time in seconds. Any unresolved transaction older than this time will be sent to the coordinator to be resolved. | +| -twopc_coordinator_address | string | address of the (VTGate) process(es) that will be used to notify of abandoned transactions. | +| -twopc_enable | if the flag is on, 2pc is enabled. Other 2pc flags must be supplied.| -tx-throttler-config | string | The configuration of the transaction throttler as a text formatted throttlerdata.Configuration protocol buffer message (default "target_replication_lag_sec: 2\nmax_replication_lag_sec: 10\ninitial_rate: 100\nmax_increase: 1\nemergency_decrease: 0.5\nmin_duration_between_increases_sec: 40\nmax_duration_between_increases_sec: 62\nmin_duration_between_decreases_sec: 20\nspread_backlog_across_sec: 20\nage_bad_rate_after_sec: 180\nbad_rate_increase: 0.1\nmax_rate_approach_threshold: 0.9\n") | +| -tx-throttler-healthcheck-cells | value | A comma-separated list of cells. Only tabletservers running in these cells will be monitored for replication lag by the transaction throttler. | +| -v | value | log level for V logs | +| -version | | print binary version | +| -vmodule | value | comma-separated list of pattern=N settings for file-filtered logging | +| -vreplication_healthcheck_retry_delay | duration | healthcheck retry delay (default 5s) | +| -vreplication_healthcheck_timeout | duration | healthcheck retry delay (default 1m0s) | +| -vreplication_healthcheck_topology_refresh | duration | refresh interval for re-reading the topology (default 30s) | +| -vreplication_retry_delay | duration | delay before retrying a failed binlog connection (default 5s) | +| -vreplication_tablet_type | string | comma separated list of tablet types used as a source (default "REPLICA") | +| -vstream_packet_size | int | Suggested packet size for VReplication streamer. This is used only as a recommendation. The actual packet size may be more or less than this amount. (default 30000) | +| -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_key | string | the key to use to connect | +| -vtgate_grpc_server_name | string | the server name to use to validate server certificate | +| -vtgate_protocol | string | how to talk to vtgate (default "grpc") | +| -wait-time | duration | time to wait on an action (default 24h0m0s) | +| -wait_for_drain_sleep_rdonly | duration | time to wait before shutting the query service on old RDONLY tablets during MigrateServedTypes (default 5s) | +| -wait_for_drain_sleep_replica | duration | time to wait before shutting the query service on old REPLICA tablets during MigrateServedTypes (default 15s) | +| -watch_replication_stream | | When enabled, vttablet will stream the MySQL replication stream from the local server, and use it to support the include_event_token ExecuteOptions. | +| -xbstream_restore_flags | string | flags 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_flags | string | flags to pass to backup command. These should be space separated and will be added to the end of the command | +| -xtrabackup_prepare_flags | string | flags to pass to prepare command. These should be space separated and will be added to the end of the command | +| -xtrabackup_root_path | string | directory location of the xtrabackup executable, e.g., /usr/bin | +| -xtrabackup_stream_mode | string | which mode to use if streaming, valid values are tar and xbstream (default "tar") | +| -xtrabackup_stripe_block_size | uint | Size in bytes of each block that gets sent to a given stripe before rotating to the next stripe (default 102400) | +| -xtrabackup_stripes | uint | If greater than 0, use data striping across this many destination files to parallelize data transfer and decompression | +| -xtrabackup_user | string | User that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation. | + diff --git a/content/en/docs/reference/programs/vtctl/cell-aliases.md b/content/en/docs/reference/programs/vtctl/cell-aliases.md new file mode 100644 index 000000000..6399d3e49 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/cell-aliases.md @@ -0,0 +1,79 @@ +--- +title: vtctl Cell Aliases Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering Cell Aliases. + +## Commands + +### AddCellsAlias + +Defines a group of cells within which replica/rdonly traffic can be routed across cells. By default, Vitess does not allow traffic between replicas that are part of different cells. Between cells that are not in the same group (alias), only master traffic can be routed. + + +#### Example + +
AddCellsAlias [-cells <cell1,cell2,cell3>] <alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | The list of cell names that are members of this alias. | + + +#### Arguments + +* <alias> – Required. Alias name for this grouping. + +#### Errors + +* the <alias> argument is required for the <AddCellsAlias> command This error occurs if the command is not called with exactly one argument. + +### UpdateCellsAlias + +Updates the content of a CellAlias with the provided parameters. Empty values and intersections with other aliases are not supported. + +#### Example + +
UpdateCellsAliases [-cells <cell1,cell2,cell3>] <alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string |The list of cell names that are members of this alias. | + + +#### Arguments + +* <alias> – Required. Alias name group to update. + +#### Errors + +* the <alias> argument is required for the <UpdateCellsAlias> command This error occurs if the command is not called with exactly one argument. + +### DeleteCellsAlias + +Deletes the CellsAlias for the provided alias. After deleting an alias, cells that were part of the group are not going to be able to route replica/rdonly traffic to the rest of the cells that were part of the grouping. + +#### Example + +
DeleteCellsAlias <alias>
+ +#### Errors + +* the <alias> argument is required for the <DeleteCellsAlias> command This error occurs if the command is not called with exactly one argument. + +### GetCellsAliases + +Fetches in json format all the existent cells alias groups. + +#### Example + +
GetCellsAliases
+ +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/cells.md b/content/en/docs/reference/programs/vtctl/cells.md new file mode 100644 index 000000000..943cc9128 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/cells.md @@ -0,0 +1,113 @@ +--- +title: vtctl Cell Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering Cells. + +## Commands + +### AddCellInfo + +Registers a local topology service in a new cell by creating the CellInfo with the provided parameters. The address will be used to connect to the topology service, and we'll put Vitess data starting at the provided root. + +#### Example + +
AddCellInfo [-server_address <addr>] [-root <root>] <cell>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| root | string | The root path the topology service is using for that cell. | +| server_address | string | The address the topology service is using for that cell. | + + +#### Arguments + +* <addr> – Required. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <AddCellInfo> command This error occurs if the command is not called with exactly one argument. + +### DeleteCellInfo + +Deletes the CellInfo for the provided cell. The cell cannot be referenced by any Shard record. + +#### Example + +
DeleteCellInfo <cell>
+ +#### Errors + +* the <cell> argument is required for the <DeleteCellInfo> command This error occurs if the command is not called with exactly one argument. + + +### GetCellInfo + +Prints a JSON representation of the CellInfo for a cell. + +#### Example + +
GetCellInfo <cell>
+ +#### Errors + +* the <cell> argument is required for the <GetCellInfo> command This error occurs if the command is not called with exactly one argument. + +### GetCellInfoNames + +Lists all the cells for which we have a CellInfo object, meaning we have a local topology service registered. + +#### Example + +
GetCellInfoNames
+ +#### Errors + +* <GetCellInfoNames> command takes no parameter This error occurs if the command is not called with exactly 0 arguments. + + +### UpdateCellInfo + +Updates the content of a CellInfo with the provided parameters. If a value is empty, it is not updated. The CellInfo will be created if it doesn't exist. + +#### Example + +
UpdateCellInfo [-server_address <addr>] [-root <root>] <cell>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| root | string | The root path the topology service is using for that cell. | +| server_address | string | The address the topology service is using for that cell. | + + +#### Arguments + +* <addr> – Required. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <UpdateCellInfo> command This error occurs if the command is not called with exactly one argument. + +### GetCellInfo + +Prints a JSON representation of the CellInfo for a cell. + +#### Example + +
GetCellInfo <cell>
+ +#### Errors + +* the <cell> argument is required for the <GetCellInfo> command This error occurs if the command is not called with exactly one argument. + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/generic.md b/content/en/docs/reference/programs/vtctl/generic.md new file mode 100644 index 000000000..b26d5c206 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/generic.md @@ -0,0 +1,69 @@ +--- +title: vtctl Generic Command Reference +series: vtctl +--- + +The following generic `vtctl` commands are available for administering Vitess. + +## Commands + +### Validate + +Validates that all nodes reachable from the global replication graph and that all tablets in all discoverable cells are consistent. + +#### Example + +
Validate [-ping-tablets]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process | + + +### ListAllTablets + +Lists all tablets in an awk-friendly way. + +#### Example + +
ListAllTablets <cell name>
+ +#### Arguments + +* <cell name> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell name> argument is required for the <ListAllTablets> command This error occurs if the command is not called with exactly one argument. + +### ListTablets + +Lists specified tablets in an awk-friendly way. + +#### Example + +
ListTablets <tablet alias> ...
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <tablet alias> argument is required for the <ListTablets> command This error occurs if the command is not called with at least one argument. + +### Help + +Provides help for a command. + +#### Example + +``` +Help [command name] +``` + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/keyspaces.md b/content/en/docs/reference/programs/vtctl/keyspaces.md new file mode 100644 index 000000000..f4775f4a9 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/keyspaces.md @@ -0,0 +1,471 @@ +--- +title: vtctl Keyspace Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering Keyspaces. + +## Commands + +### CreateKeyspace + +Creates the specified keyspace. + +#### Example + +
CreateKeyspace [-sharding_column_name=name] [-sharding_column_type=type] [-served_from=tablettype1:ks1,tablettype2,ks2,...] [-force] <keyspace name>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds even if the keyspace already exists | +| served_from | string | Specifies a comma-separated list of dbtype:keyspace pairs used to serve traffic | +| sharding_column_name | string | Specifies the column to use for sharding operations | +| sharding_column_type | string | Specifies the type of the column to use for sharding operations | + + +#### 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 <CreateKeyspace> command This error occurs if the command is not called with exactly one argument. + +### DeleteKeyspace + +Deletes the specified keyspace. In recursive mode, it also recursively deletes all shards in the keyspace. Otherwise, there must be no shards left in the keyspace. + +#### Example + +
DeleteKeyspace [-recursive] <keyspace>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| recursive | Boolean | Also recursively delete all shards in the 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 + +* must specify the <keyspace> argument for <DeleteKeyspace> This error occurs if the command is not called with exactly one argument. + +### RemoveKeyspaceCell + +Removes the cell from the Cells list for all shards in the keyspace, and the SrvKeyspace for that keyspace in that cell. + +#### Example + +
RemoveKeyspaceCell [-force] [-recursive] <keyspace> <cell>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds even if the cell's topology service cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. | +| recursive | Boolean | Also delete all tablets in that cell belonging to the specified 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. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <keyspace> and <cell> arguments are required for the <RemoveKeyspaceCell> command This error occurs if the command is not called with exactly 2 arguments. + +### GetKeyspace + +Outputs a JSON structure that contains information about the Keyspace. + +#### Example + +
GetKeyspace <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 <GetKeyspace> command This error occurs if the command is not called with exactly one argument. + +### GetKeyspaces + +Outputs a sorted list of all keyspaces. + + +### MigrateServedFrom + +Makes the <destination keyspace/shard> serve the given type. This command also rebuilds the serving graph. + +#### Example + +
MigrateServedFrom [-cells=c1,c2,...] [-reverse] <destination keyspace/shard> <served tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to update | +| filtered_replication_wait_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations | +| reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble | + + +#### Arguments + +* <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>. +* <served tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
+ * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + +#### Errors + +* the <destination keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedFrom> command This error occurs if the command is not called with exactly 2 arguments. + +### SetKeyspaceShardingInfo + +Updates the sharding information for a keyspace. + +#### Example + +
SetKeyspaceShardingInfo [-force] <keyspace name> [<column name>] [<column type>]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Updates fields even if they are already set. Use caution before calling this command. | + + +#### 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. +* <column name> – Optional. +* <column type> – Optional. + +#### Errors + +* the <keyspace name> argument is required for the <SetKeyspaceShardingInfo> command. The <column name> and <column type> arguments are both optional This error occurs if the command is not called with between 1 and 3 arguments. +* both <column name> and <column type> must be set, or both must be unset + + +### SetKeyspaceServedFrom + +Changes the ServedFromMap manually. This command is intended for emergency fixes. This field is automatically set when you call the *MigrateServedFrom* command. This command does not rebuild the serving graph. + +#### Example + +
SetKeyspaceServedFrom [-source=<source keyspace name>] [-remove] [-cells=c1,c2,...] <keyspace name> <tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to affect | +| remove | Boolean | Indicates whether to add (default) or remove the served from record | +| source | string | Specifies the source 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. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
+ * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + +#### Errors + +* the <keyspace name> and <tablet type> arguments are required for the <SetKeyspaceServedFrom> command This error occurs if the command is not called with exactly 2 arguments. + +### RebuildKeyspaceGraph + +Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients. + +#### Example + +
RebuildKeyspaceGraph [-cells=c1,c2,...] <keyspace> ...
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to update | + + +#### 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. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <keyspace> argument must be used to specify at least one keyspace when calling the <RebuildKeyspaceGraph> command This error occurs if the command is not called with at least one argument. + + +### ValidateKeyspace + + +Validates that all nodes reachable from the specified keyspace are consistent. + +#### Example + +
ValidateKeyspace [-ping-tablets] <keyspace name>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| ping-tablets | Boolean | Specifies whether all tablets will be pinged during the validation process | + + +#### 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 <ValidateKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### Reshard +``` +Reshard [-skip_schema_copy] +``` + +### MoveTables +``` +MoveTables [-cell=] [-tablet_types=] -workflow= +``` + +### DropSources +``` +DropSources [-dry_run] +``` + +### CreateLookupVindex +``` +CreateLookupVindex [-cell=] [-tablet_types=] +``` + +### ExternalizeVindex +``` +ExternalizeVindex . +``` + +### Materialize +``` +Materialize , example : '{"workflow": "aaa", "source_keyspace": "source", "target_keyspace": "target", "table_settings": [{"target_table": "customer", "source_expression": "select * from customer", "create_ddl": "copy"}]}' +``` + +### SplitClone +``` +SplitClone +``` + +### VerticalSplitClone +``` +VerticalSplitClone +``` + +### VDiff +``` +VDiff [-source_cell=] [-target_cell=] [-tablet_types=replica] [-filtered_replication_wait_time=30s] +``` + +### MigrateServedTypes + +Migrates a serving type from the source shard to the shards that it replicates to. This command also rebuilds the serving graph. The <keyspace/shard> argument can specify any of the shards involved in the migration. + +#### Example + +
MigrateServedTypes [-cells=c1,c2,...] [-reverse] [-skip-refresh-state] <keyspace/shard> <served tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to update | +| filtered\_replication\_wait\_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations | +| reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble | +| skip-refresh-state | Boolean | Skips refreshing the state of the source tablets after the migration, meaning that the refresh will need to be done manually, replica and rdonly only) | +| reverse\_replication | Boolean | For master migration, enabling this flag reverses replication which allows you to rollback | + + +#### 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>. +* <served tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
+ * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + +#### Errors + +* the <source keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedTypes> command This error occurs if the command is not called with exactly 2 arguments. +* the <skip-refresh-state> flag can only be specified for non-master migrations + + +### MigrateServedFrom + +Makes the <destination keyspace/shard> serve the given type. This command also rebuilds the serving graph. + +#### Example + +
MigrateServedFrom [-cells=c1,c2,...] [-reverse] <destination keyspace/shard> <served tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to update | +| filtered_replication_wait_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations | +| reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble | + + +#### Arguments + +* <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>. +* <served tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
+ * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + +#### Errors + +* the <destination keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedFrom> command This error occurs if the command is not called with exactly 2 arguments. + +### SwitchReads +``` +SwitchReads [-cells=c1,c2,...] [-reverse] -tablet_type={replica|rdonly} [-dry-run] +``` + +### SwitchWrites +``` +SwitchWrites [-filtered_replication_wait_time=30s] [-cancel] [-reverse_replication=false] [-dry-run] +``` + +### CancelResharding + +Permanently cancels a resharding in progress. All resharding related metadata will be deleted. + +#### 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>. + +### ShowResharding + +Displays all metadata about a resharding in progress. + +#### 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>. + + +### FindAllShardsInKeyspace + +Displays all of the shards in the specified keyspace. + +#### Example + +
FindAllShardsInKeyspace <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 <FindAllShardsInKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### WaitForDrain + +Blocks until no new queries were observed on all tablets with the given tablet type in the specified keyspace. This can be used as sanity check to ensure that the tablets were drained after running vtctl MigrateServedTypes and vtgate is no longer using them. If -timeout is set, it fails when the timeout is reached. + +#### Example + +
WaitForDrain [-timeout <duration>] [-retry_delay <duration>] [-initial_wait <duration>] <keyspace/shard> <served tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to look for tablets | +| initial_wait | Duration | Time to wait for all tablets to check in | +| retry_delay | Duration | Time to wait between two checks | +| timeout | Duration | Timeout after which the command fails | + + +#### 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>. +* <served tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
+ * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + +#### Errors + +* the <keyspace/shard> and <tablet type> arguments are both required for the <WaitForDrain> command This error occurs if the command is not called with exactly 2 arguments. + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/queries.md b/content/en/docs/reference/programs/vtctl/queries.md new file mode 100644 index 000000000..bbc1a67d7 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/queries.md @@ -0,0 +1,179 @@ +--- +title: vtctl Query Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering queries. + +## Commands + +### VtGateExecute + +Executes the given SQL query with the provided bound variables against the vtgate server. + +#### Example + +
VtGateExecute -server <vtgate> [-bind_variables <JSON map>] [-keyspace <default keyspace>] [-tablet_type <tablet type>] [-options <proto text options>] [-json] <sql>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| json | Boolean | Output JSON instead of human-readable table | +| options | string | execute options values as a text encoded proto of the ExecuteOptions structure | +| server | string | VtGate server to connect to | +| target | string | keyspace:shard@tablet_type | + + +#### Arguments + +* <vtgate> – Required. +* <sql> – Required. + +#### Errors + +* the <sql> argument is required for the <VtGateExecute> command This error occurs if the command is not called with exactly one argument. +* query commands are disabled (set the -enable_queries flag to enable) +* error connecting to vtgate '%v': %v +* Execute failed: %v + +### VtTabletExecute + +Executes the given query on the given tablet. -transaction_id is optional. Use VtTabletBegin to start a transaction. + +#### Example + +
VtTabletExecute [-username <TableACL user>] [-transaction_id <transaction_id>] [-options <proto text options>] [-json] <tablet alias> <sql>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| json | Boolean | Output JSON instead of human-readable table | +| options | string | execute options values as a text encoded proto of the ExecuteOptions structure | +| transaction_id | Int | transaction id to use, if inside a transaction. | +| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | + + +#### Arguments + +* <TableACL user> – Required. +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <sql> – Required. + +#### Errors + +* the <tablet_alias> and <sql> arguments are required for the <VtTabletExecute> command This error occurs if the command is not called with exactly 2 arguments. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v +* Execute failed: %v + +### VtTabletBegin + +Starts a transaction on the provided server. + +#### Example + +
VtTabletBegin [-username <TableACL user>] <tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | + + +#### Arguments + +* <TableACL user> – Required. +* <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 <VtTabletBegin> command This error occurs if the command is not called with exactly one argument. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v +* Begin failed: %v + +### VtTabletCommit + +Commits the given transaction on the provided server. + +#### Example + +
VtTabletCommit [-username <TableACL user>] <transaction_id>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | + + +#### Arguments + +* <TableACL user> – Required. +* <transaction_id> – Required. + +#### Errors + +* the <tablet_alias> and <transaction_id> arguments are required for the <VtTabletCommit> command This error occurs if the command is not called with exactly 2 arguments. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v + +### VtTabletRollback + +Rollbacks the given transaction on the provided server. + +#### Example + +
VtTabletRollback [-username <TableACL user>] <tablet alias> <transaction_id>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | + + +#### Arguments + +* <TableACL user> – Required. +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <transaction_id> – Required. + +#### Errors + +* the <tablet_alias> and <transaction_id> arguments are required for the <VtTabletRollback> command This error occurs if the command is not called with exactly 2 arguments. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v + +### VtTabletStreamHealth + +Executes the StreamHealth streaming query to a vttablet process. Will stop after getting <count> answers. + +#### Example + +
VtTabletStreamHealth [-count <count, default 1>] <tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| count | Int | number of responses to wait for | + + +#### Arguments + +* <count default 1> – Required. +* <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 <VtTabletStreamHealth> command This error occurs if the command is not called with exactly one argument. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/replication-graph.md b/content/en/docs/reference/programs/vtctl/replication-graph.md new file mode 100644 index 000000000..a34742dd3 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/replication-graph.md @@ -0,0 +1,29 @@ +--- +title: vtctl Replication Graph Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering the Replication Graph. + +## Commands + +### GetShardReplication + +Outputs a JSON structure that contains information about the ShardReplication. + +#### Example + +
GetShardReplication <cell> <keyspace/shard>
+ +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <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 <cell> and <keyspace/shard> arguments are required for the <GetShardReplication> command This error occurs if the command is not called with exactly 2 arguments. + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/resharding-throttler.md b/content/en/docs/reference/programs/vtctl/resharding-throttler.md new file mode 100644 index 000000000..b9c2392e0 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/resharding-throttler.md @@ -0,0 +1,146 @@ +--- +title: vtctl Resharding Throttler Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering Resharding Throttler. + +## Commands + +### ThrottlerMaxRates + +Returns the current max rate of all active resharding throttlers on the server. + +#### Example + +
ThrottlerMaxRates -server <vtworker or vttablet>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| server | string | vtworker or vttablet to connect to | + + +#### Arguments + +* <vtworker or vttablet> – Required. + +#### Errors + +* the ThrottlerSetMaxRate command does not accept any positional parameters This error occurs if the command is not called with exactly 0 arguments. +* error creating a throttler client for <server> '%v': %v +* failed to get the throttler rate from <server> '%v': %v + +### ThrottlerSetMaxRate + +Sets the max rate for all active resharding throttlers on the server. + +#### Example + +
ThrottlerSetMaxRate -server <vtworker or vttablet> <rate>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| server | string | vtworker or vttablet to connect to | + + +#### Arguments + +* <vtworker or vttablet> – Required. +* <rate> – Required. + +#### Errors + +* the <rate> argument is required for the <ThrottlerSetMaxRate> command This error occurs if the command is not called with exactly one argument. +* failed to parse rate '%v' as integer value: %v +* error creating a throttler client for <server> '%v': %v +* failed to set the throttler rate on <server> '%v': %v + + +### GetThrottlerConfiguration + +Returns the current configuration of the MaxReplicationLag module. If no throttler name is specified, the configuration of all throttlers will be returned. + +#### Example + +
GetThrottlerConfiguration -server <vtworker or vttablet> [<throttler name>]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| server | string | vtworker or vttablet to connect to | + + +#### Arguments + +* <vtworker or vttablet> – Required. +* <throttler name> – Optional. + +#### Errors + +* the <GetThrottlerConfiguration> command accepts only <throttler name> as optional positional parameter This error occurs if the command is not called with more than 1 arguments. +* error creating a throttler client for <server> '%v': %v +* failed to get the throttler configuration from <server> '%v': %v + +### UpdateThrottlerConfiguration + +Updates the configuration of the MaxReplicationLag module. The configuration must be specified as protobuf text. If a field is omitted or has a zero value, it will be ignored unless -copy_zero_values is specified. If no throttler name is specified, all throttlers will be updated. + +#### Example + +
UpdateThrottlerConfiguration `-server <vtworker or vttablet> [-copy_zero_values] "<configuration protobuf text>" [<throttler name>]`
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| copy_zero_values | Boolean | If true, fields with zero values will be copied as well | +| server | string | vtworker or vttablet to connect to | + + +#### Arguments + +* <vtworker or vttablet> – Required. +* <throttler name> – Optional. + +#### Errors + +* Failed to unmarshal the configuration protobuf text (%v) into a protobuf instance: %v +* error creating a throttler client for <server> '%v': %v +* failed to update the throttler configuration on <server> '%v': %v + + +### ResetThrottlerConfiguration + +Resets the current configuration of the MaxReplicationLag module. If no throttler name is specified, the configuration of all throttlers will be reset. + +#### Example + +
ResetThrottlerConfiguration -server <vtworker or vttablet> [<throttler name>]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| server | string | vtworker or vttablet to connect to | + + +#### Arguments + +* <vtworker or vttablet> – Required. +* <throttler name> – Optional. + +#### Errors + +* the <ResetThrottlerConfiguration> command accepts only <throttler name> as optional positional parameter This error occurs if the command is not called with more than 1 arguments. +* error creating a throttler client for <server> '%v': %v +* failed to get the throttler configuration from <server> '%v': %v + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/schema-version-permissions.md b/content/en/docs/reference/programs/vtctl/schema-version-permissions.md new file mode 100644 index 000000000..110d093d5 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/schema-version-permissions.md @@ -0,0 +1,359 @@ +--- +title: vtctl Schema, Version, Permissions Command Reference +series: vtctl +--- + +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 + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes views in the output | +| table_names_only | Boolean | Only displays table names that match | +| tables | string | Specifies 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_master=false] <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| concurrency | Int | How many tablets to reload in parallel | +| include_master | Boolean | Include the master 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_master=false] <keyspace>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| concurrency | Int | How many tablets to reload in parallel | +| include_master | Boolean | Include the master 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 master schema matches all of the slaves. + +#### Example + +
ValidateSchemaShard [-exclude_tables=''] [-include-views] <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes 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 master schema from shard 0 matches the schema on all of the other tablets in the keyspace. + +#### Example + +
ValidateSchemaKeyspace [-exclude_tables=''] [-include-views] <keyspace name>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes 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 master, running in parallel on all shards. The changes are then propagated to slaves 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. + +#### Example + +
ApplySchema [-allow_long_unavailability] [-wait_slave_timeout=10s] {-sql=<sql> || -sql-file=<filename>} <keyspace>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| allow_long_unavailability | Boolean | Allow large schema changes which incur a longer unavailability of the database. | +| sql | string | A list of semicolon-delimited SQL commands | +| sql-file | string | Identifies the file that contains the SQL commands | +| wait_slave_timeout | Duration | The amount of time to wait for slaves to receive the schema change via replication. | + + +#### 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. + +### CopySchemaShard + +Copies the schema from a source shard's master (or a specific tablet) to a destination shard. The schema is applied directly on the master 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_slave_timeout=10s] {<source keyspace/shard> || <source tablet alias>} <destination keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes views in the output | +| tables | string | Specifies a comma-separated list of tables to copy. Each is either an exact match, or a regular expression of the form /regexp/ | +| wait_slave_timeout | Duration | The amount of time to wait for slaves to receive the schema change via replication. | + + +#### Arguments + +* <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 master version matches all of the slaves. + +#### 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 master version from 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 master permissions match all the slaves. + +#### 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 master permissions from 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>} [-cells=c1,c2,...] [-skip_rebuild] <keyspace>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | If specified, limits the rebuild to the cells, after upload. Ignored if skipRebuild is set. | +| skip_rebuild | Boolean | If set, do no rebuild the SrvSchema objects. | +| vschema | string | Identifies the VTGate routing schema | +| vschema_file | string | Identifies 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 + +### GetRoutingRules + +``` +GetRoutingRules +``` + +### ApplyRoutingRules + +``` +ApplyRoutingRules {-rules= +| -rules_file=} [-cells=c1,c2,...] [-skip_rebuild] [-dry-run] +``` + +### 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 + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies 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 + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/serving-graph.md b/content/en/docs/reference/programs/vtctl/serving-graph.md new file mode 100644 index 000000000..bbad0662e --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/serving-graph.md @@ -0,0 +1,69 @@ +--- +title: vtctl Serving Graph Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering the Serving Graph. + +## Commands + +### GetSrvKeyspaceNames + +Outputs a list of keyspace names. + +#### Example + +
GetSrvKeyspaceNames <cell>
+ +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <GetSrvKeyspaceNames> command This error occurs if the command is not called with exactly one argument. + + +### GetSrvKeyspace + +Outputs a JSON structure that contains information about the SrvKeyspace. + +#### Example + +
GetSrvKeyspace <cell> <keyspace>
+ +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <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 <cell> and <keyspace> arguments are required for the <GetSrvKeyspace> command This error occurs if the command is not called with exactly 2 arguments. + +### GetSrvVSchema + +Outputs a JSON structure that contains information about the SrvVSchema. + +#### Example + +
GetSrvVSchema <cell>
+ +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <GetSrvVSchema> command This error occurs if the command is not called with exactly one argument. + +### DeleteSrvVSchema + +``` +DeleteSrvVSchema +``` + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/shards.md b/content/en/docs/reference/programs/vtctl/shards.md new file mode 100644 index 000000000..116dbe113 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/shards.md @@ -0,0 +1,410 @@ +--- +title: vtctl Shard Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering shards. + +## Commands + +### CreateShard + +Creates the specified shard. + +#### Example + +
CreateShard [-force] [-parent] <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds with the command even if the keyspace already exists | +| parent | Boolean | Creates the parent keyspace if it doesn't already exist | + + +#### 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 <CreateShard> command This error occurs if the command is not called with exactly one argument. + +### GetShard + +Outputs a JSON structure that contains information about the Shard. + +#### Example + +
GetShard <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 <GetShard> command This error occurs if the command is not called with exactly one argument. + +### ValidateShard + +Validates that all nodes that are reachable from this shard are consistent. + +#### Example + +
ValidateShard [-ping-tablets] <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process | + + +#### 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 <ValidateShard> command This error occurs if the command is not called with exactly one argument. + +### ShardReplicationPositions + +Shows the replication status of each slave machine in the shard graph. In this case, the status refers to the replication lag between the master vttablet and the slave vttablet. In Vitess, data is always written to the master vttablet first and then replicated to all slave vttablets. Output is sorted by tablet type, then replication position. Use ctrl-C to interrupt command and see partial result if needed. + +#### Example + +
ShardReplicationPositions <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 <ShardReplicationPositions> command This error occurs if the command is not called with exactly one argument. + + +### ListShardTablets + +Lists all tablets in the specified shard. + +#### Example + +
ListShardTablets <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 <ListShardTablets> command This error occurs if the command is not called with exactly one argument. + +### SetShardIsMasterServing + +``` +SetShardIsMasterServing +``` + +### SetShardTabletControl + +Sets the TabletControl record for a shard and type. Only use this for an emergency fix or after a finished vertical split. The *MigrateServedFrom* and *MigrateServedType* commands set this field appropriately already. Always specify the blacklisted_tables flag for vertical splits, but never for horizontal splits.

To set the DisableQueryServiceFlag, keep 'blacklisted_tables' empty, and set 'disable_query_service' to true or false. Useful to fix horizontal splits gone wrong.

To change the blacklisted tables list, specify the 'blacklisted_tables' parameter with the new list. Useful to fix tables that are being blocked after a vertical split.

To just remove the ShardTabletControl entirely, use the 'remove' flag, useful after a vertical split is finished to remove serving restrictions. + +#### Example + +
SetShardTabletControl [--cells=c1,c2,...] [--blacklisted_tables=t1,t2,...] [--remove] [--disable_query_service] <keyspace/shard> <tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| blacklisted_tables | string | Specifies a comma-separated list of tables to blacklist (used for vertical split). Each is either an exact match, or a regular expression of the form '/regexp/'. | +| cells | string | Specifies a comma-separated list of cells to update | +| disable_query_service | Boolean | Disables query service on the provided nodes. This flag requires 'blacklisted_tables' and 'remove' to be unset, otherwise it's ignored. | +| remove | Boolean | Removes cells for vertical splits. | + + +#### 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>. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
+ * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + +#### Errors + +* the <keyspace/shard> and <tablet type> arguments are both required for the <SetShardTabletControl> command This error occurs if the command is not called with exactly 2 arguments. + +### UpdateSrvKeyspacePartition + +``` +UpdateSrvKeyspacePartition [--cells=c1,c2,...] [--remove] +``` + +### SourceShardDelete + +Deletes the SourceShard record with the provided index. This is meant as an emergency cleanup function. It does not call RefreshState for the shard master. + +#### Example + +
SourceShardDelete <keyspace/shard> <uid>
+ +#### 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>. +* <uid> – Required. + +#### Errors + +* the <keyspace/shard> and <uid> arguments are both required for the <SourceShardDelete> command This error occurs if the command is not called with at least 2 arguments. + +### SourceShardAdd + +Adds the SourceShard record with the provided index. This is meant as an emergency function. It does not call RefreshState for the shard master. + +#### Example + +
SourceShardAdd [--key_range=<keyrange>] [--tables=<table1,table2,...>] <keyspace/shard> <uid> <source keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| key_range | string | Identifies the key range to use for the SourceShard | +| tables | string | Specifies a comma-separated list of tables to replicate (used for vertical split). Each is either an exact match, or a regular expression of the form /regexp/ | + + +#### 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>. +* <uid> – Required. +* <source 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>, <uid>, and <source keyspace/shard> arguments are all required for the <SourceShardAdd> command This error occurs if the command is not called with exactly 3 arguments. + +### ShardReplicationFix + +Walks through a ShardReplication object and fixes the first error that it encounters. + +#### Example + +
ShardReplicationFix <cell> <keyspace/shard>
+ +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <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 <cell> and <keyspace/shard> arguments are required for the ShardReplicationRemove command This error occurs if the command is not called with exactly 2 arguments. + +### WaitForFilteredReplication + +Blocks until the specified shard has caught up with the filtered replication of its source shard. + +#### Example + +
WaitForFilteredReplication [-max_delay <max_delay, default 30s>] <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 <WaitForFilteredReplication> command This error occurs if the command is not called with exactly one argument. + +### RemoveShardCell + +Removes the cell from the shard's Cells list. + +#### Example + +
RemoveShardCell [-force] [-recursive] <keyspace/shard> <cell>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds even if the cell's topology service cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. | +| recursive | Boolean | Also delete all tablets in that cell belonging to the specified 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>. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <keyspace/shard> and <cell> arguments are required for the <RemoveShardCell> command This error occurs if the command is not called with exactly 2 arguments. + +### DeleteShard + +Deletes the specified shard(s). In recursive mode, it also deletes all tablets belonging to the shard. Otherwise, there must be no tablets left in the shard. + +#### Example + +
DeleteShard [-recursive] [-even_if_serving] <keyspace/shard> ...
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| even_if_serving | Boolean | Remove the shard even if it is serving. Use with caution. | +| recursive | Boolean | Also delete all tablets belonging to the 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>. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <keyspace/shard> argument must be used to identify at least one keyspace and shard when calling the <DeleteShard> command This error occurs if the command is not called with at least one argument. + +### ListBackups + +Lists all the backups for a shard. + +#### Example + +
ListBackups <keyspace/shard>
+ +#### Errors + +* action <ListBackups> requires <keyspace/shard> This error occurs if the command is not called with exactly one argument. + +### BackupShard + +``` +BackupShard [-allow_master=false] +``` + +### RemoveBackup + +Removes a backup for the BackupStorage. + +#### Example + +
RemoveBackup <keyspace/shard> <backup name>
+ +#### Arguments + +* <backup name> – Required. + +#### Errors + +* action <RemoveBackup> requires <keyspace/shard> <backup name> This error occurs if the command is not called with exactly 2 arguments. + +### InitShardMaster + +Sets the initial master for a shard. Will make all other tablets in the shard slaves of the provided master. WARNING: this could cause data loss on an already replicating shard. PlannedReparentShard or EmergencyReparentShard should be used instead. + +#### Example + +
InitShardMaster [-force] [-wait_slave_timeout=<duration>] <keyspace/shard> <tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | will force the reparent even if the provided tablet is not a master or the shard master | +| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting | + + +#### 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>. +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* action <InitShardMaster> requires <keyspace/shard> <tablet alias> This error occurs if the command is not called with exactly 2 arguments. +* active reparent commands disabled (unset the -disable_active_reparents flag to enable) + +### PlannedReparentShard + +Reparents the shard to the new master, or away from old master. Both old and new master need to be up and running. + +#### Example + +
PlannedReparentShard -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| avoid_master | string | alias of a tablet that should not be the master, i.e. reparent to any other tablet if this one is the master | +| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented | +| new_master | string | alias of a tablet that should be the new master | +| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting | + + +#### Errors + +* action <PlannedReparentShard> requires -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>] This error occurs if the command is not called with exactly 0 arguments. +* active reparent commands disabled (unset the -disable_active_reparents flag to enable) +* cannot use legacy syntax and flags -<keyspace_shard> and -<new_master> for action <PlannedReparentShard> at the same time + +### EmergencyReparentShard + +Reparents the shard to the new master. Assumes the old master is dead and not responding. + +#### Example + +
EmergencyReparentShard -keyspace_shard=<keyspace/shard> -new_master=<tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented | +| new_master | string | alias of a tablet that should be the new master | +| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting | + + +#### Errors + +* action <EmergencyReparentShard> requires -keyspace_shard=<keyspace/shard> -new_master=<tablet alias> This error occurs if the command is not called with exactly 0 arguments. +* active reparent commands disabled (unset the -disable_active_reparents flag to enable) +* cannot use legacy syntax and flag -<new_master> for action <EmergencyReparentShard> at the same time + + +### TabletExternallyReparented + +Changes metadata in the topology service to acknowledge a shard master change performed by an external tool. See [Reparenting](../../user-guides/reparenting/#external-reparenting) for more information. + +#### Example + +
TabletExternallyReparented <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 <TabletExternallyReparented> command This error occurs if the command is not called with exactly one argument. + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/tablets.md b/content/en/docs/reference/programs/vtctl/tablets.md new file mode 100644 index 000000000..77feffdb7 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/tablets.md @@ -0,0 +1,479 @@ +--- +title: vtctl Tablet Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering tablets. + +## Commands + +### InitTablet + +Initializes a tablet in the topology. + +#### Example + +
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>] -keyspace=<keyspace> -shard=<shard> <tablet alias> <tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| allow_master_override | Boolean | Use this flag to force initialization if a tablet is created as master, and a master for the keyspace/shard already exists. Use with caution. | +| allow_update | Boolean | Use this flag to force initialization if a tablet with the same name already exists. Use with caution. | +| db_name_override | string | Overrides the name of the database that the vttablet uses | +| grpc_port | Int | The gRPC port for the vttablet process | +| hostname | string | The server on which the tablet is running | +| keyspace | string | The keyspace to which this tablet belongs | +| mysql_host | string | The mysql host for the mysql server | +| mysql_port | Int | The mysql port for the mysql server | +| parent | Boolean | Creates the parent shard and keyspace if they don't yet exist | +| port | Int | The main port for the vttablet process | +| shard | string | The shard to which this tablet belongs | +| tags | string | A comma-separated list of key:value pairs that are used to tag the tablet | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
+ * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + +#### Errors + +* the <tablet alias> and <tablet type> arguments are both required for the <InitTablet> command This error occurs if the command is not called with exactly 2 arguments. + + +### GetTablet + +Outputs a JSON structure that contains information about the Tablet. + +#### Example + +
GetTablet <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 <GetTablet> command This error occurs if the command is not called with exactly one argument. + + +### IgnoreHealthError + +Sets the regexp for health check errors to ignore on the specified tablet. The pattern has implicit ^$ anchors. Set to empty string or restart vttablet to stop ignoring anything. + +#### Example + +
IgnoreHealthError <tablet alias> <ignore regexp>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <ignore regexp> – Required. + +#### Errors + +* the <tablet alias> and <ignore regexp> arguments are required for the <IgnoreHealthError> command This error occurs if the command is not called with exactly 2 arguments. + +### UpdateTabletAddrs + +Updates the IP address and port numbers of a tablet. + +#### Example + +
UpdateTabletAddrs [-hostname <hostname>] [-ip-addr <ip addr>] [-mysql-port <mysql port>] [-vt-port <vt port>] [-grpc-port <grpc port>] <tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| grpc-port | Int | The gRPC port for the vttablet process | +| hostname | string | The fully qualified host name of the server on which the tablet is running. | +| mysql-port | Int | The mysql port for the mysql daemon | +| mysql_host | string | The mysql host for the mysql server | +| vt-port | Int | The main port for the vttablet process | + + +#### 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 <UpdateTabletAddrs> command This error occurs if the command is not called with exactly one argument. + +### DeleteTablet + +Deletes tablet(s) from the topology. + +#### Example + +
DeleteTablet [-allow_master] <tablet alias> ...
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| allow_master | Boolean | Allows for the master tablet of a shard to be deleted. Use with caution. | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <tablet alias> argument must be used to specify at least one tablet when calling the <DeleteTablet> command This error occurs if the command is not called with at least one argument. + +### SetReadOnly + +Sets the tablet as read-only. + +#### Example + +
SetReadOnly <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 <SetReadOnly> command This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + +### SetReadWrite + +Sets the tablet as read-write. + +#### Example + +
SetReadWrite <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 <SetReadWrite> command This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + +### StartSlave + +Starts replication on the specified tablet. + +#### Example + +
StartSlave <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* action <StartSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + +### StopSlave + +Stops replication on the specified tablet. + +#### Example + +
StopSlave <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* action <StopSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + +### ChangeSlaveType + +Changes the db type for the specified tablet, if possible. This command is used primarily to arrange replicas, and it will not convert a master.

NOTE: This command automatically updates the serving graph.

+ +#### Example + +
ChangeSlaveType [-dry-run] <tablet alias> <tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| dry-run | Boolean | Lists the proposed change without actually executing it | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
+ * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + +#### Errors + +* the <tablet alias> and <db type> arguments are required for the <ChangeSlaveType> command This error occurs if the command is not called with exactly 2 arguments. +* failed reading tablet %v: %v +* invalid type transition %v: %v -> %v + +### Ping + +hecks that the specified tablet is awake and responding to RPCs. This command can be blocked by other in-flight operations. + +#### Example + +
Ping <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 <Ping> command This error occurs if the command is not called with exactly one argument. + +### RefreshState + +Reloads the tablet record on the specified tablet. + +#### Example + +
RefreshState <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 <RefreshState> command This error occurs if the command is not called with exactly one argument. + +### RefreshStateByShard + +Runs 'RefreshState' on all tablets in the given shard. + +#### Example + +
RefreshStateByShard [-cells=c1,c2,...] <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells whose tablets are included. If empty, all cells are considered. | + + +#### 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 <RefreshStateByShard> command This error occurs if the command is not called with exactly one argument. + +### RunHealthCheck + +Runs a health check on a remote tablet. + +#### Example + +
RunHealthCheck <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 <RunHealthCheck> command This error occurs if the command is not called with exactly one argument. + +### IgnoreHealthError + +Sets the regexp for health check errors to ignore on the specified tablet. The pattern has implicit ^$ anchors. Set to empty string or restart vttablet to stop ignoring anything. + +#### Example + +
IgnoreHealthError <tablet alias> <ignore regexp>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <ignore regexp> – Required. + +#### Errors + +* the <tablet alias> and <ignore regexp> arguments are required for the <IgnoreHealthError> command This error occurs if the command is not called with exactly 2 arguments. + +### Sleep + +Blocks the action queue on the specified tablet for the specified amount of time. This is typically used for testing. + +#### Example + +
Sleep <tablet alias> <duration>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <duration> – Required. The amount of time that the action queue should be blocked. The value is a string that contains a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms" or "1h45m". See the definition of the Go language's ParseDuration function for more details. Note that, in practice, the value should be a positively signed value. + +#### Errors + +* the <tablet alias> and <duration> arguments are required for the <Sleep> command This error occurs if the command is not called with exactly 2 arguments. + +### ExecuteHook + +Runs the specified hook on the given tablet. A hook is a script that resides in the $VTROOT/vthook directory. You can put any script into that directory and use this command to run that script.

For this command, the param=value arguments are parameters that the command passes to the specified hook. + +#### Example + +
ExecuteHook <tablet alias> <hook name> [<param1=value1> <param2=value2> ...]
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <hook name> – Required. +* <param1=value1> <param2=value2> . – Optional. + +#### Errors + +* the <tablet alias> and <hook name> arguments are required for the <ExecuteHook> command This error occurs if the command is not called with at least 2 arguments. + +### ExecuteFetchAsApp + +``` +ExecuteFetchAsApp [-max_rows=10000] [-json] [-use_pool] +``` + +### ExecuteFetchAsDba + +Runs the given SQL command as a DBA on the remote tablet. + +#### Example + +
ExecuteFetchAsDba [-max_rows=10000] [-disable_binlogs] [-json] <tablet alias> <sql command>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| disable_binlogs | Boolean | Disables writing to binlogs during the query | +| json | Boolean | Output JSON instead of human-readable table | +| max_rows | Int | Specifies the maximum number of rows to allow in reset | +| reload_schema | Boolean | Indicates whether the tablet schema will be reloaded after executing the SQL command. The default value is false, which indicates that the tablet schema will not be reloaded. | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <sql command> – Required. + +#### Errors + +* the <tablet alias> and <sql command> arguments are required for the <ExecuteFetchAsDba> command This error occurs if the command is not called with exactly 2 arguments. + +### VReplicationExec + +``` +VReplicationExec [-json] +``` + +### Backup + +Stops mysqld and uses the BackupStorage service to store a new backup. This function also remembers if the tablet was replicating so that it can restore the same state after the backup completes. + +#### Example + +
Backup [-concurrency=4] <tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| concurrency | Int | Specifies the number of compression/checksum jobs to run simultaneously | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <Backup> command requires the <tablet alias> argument This error occurs if the command is not called with exactly one argument. + + +### ChangeSlaveType + +Changes the db type for the specified tablet, if possible. This command is used primarily to arrange replicas, and it will not convert a master.

NOTE: This command automatically updates the serving graph.

+ +#### Example + +
ChangeSlaveType [-dry-run] <tablet alias> <tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| dry-run | Boolean | Lists the proposed change without actually executing it | + + +### RestoreFromBackup + +Stops mysqld and restores the data from the latest backup. + +#### Example + +
RestoreFromBackup <tablet alias>
+ +#### Errors + +* the <RestoreFromBackup> command requires the <tablet alias> argument This error occurs if the command is not called with exactly one argument. + + +### ReparentTablet + +Reparent a tablet to the current master in the shard. This only works if the current slave position matches the last known reparent action. + +#### Example + +
ReparentTablet <tablet alias>
+ +#### Errors + +* action <ReparentTablet> requires <tablet alias> This error occurs if the command is not called with exactly one argument. +* active reparent commands disabled (unset the -disable_active_reparents flag to enable) + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/topo.md b/content/en/docs/reference/programs/vtctl/topo.md new file mode 100644 index 000000000..6a19f2723 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/topo.md @@ -0,0 +1,48 @@ +--- +title: vtctl Topo Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering Topology Services. + +## Commands + +### TopoCat + +Retrieves the file(s) at <path> from the topo service, and displays it. It can resolve wildcards, and decode the proto-encoded data. + +#### Example + +
TopoCat [-cell <cell>] [-decode_proto] [-long] <path> [<path>...]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cell | string | topology cell to cat the file from. Defaults to global cell. | +| decode_proto | Boolean | decode proto files and display them as text | +| long | Boolean | long listing. | + + +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <path> – Required. +* <path>. – Optional. + +#### Errors + +* <TopoCat>: no path specified This error occurs if the command is not called with at least one argument. +* <TopoCat>: invalid wildcards: %v +* <TopoCat>: some paths had errors + +### TopoCp + +``` +TopoCp [-cell ] [-to_topo] +``` + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctl/workflows.md b/content/en/docs/reference/programs/vtctl/workflows.md new file mode 100644 index 000000000..4abf898a5 --- /dev/null +++ b/content/en/docs/reference/programs/vtctl/workflows.md @@ -0,0 +1,101 @@ +--- +title: vtctl Workflow Command Reference +series: vtctl +--- + +The following `vtctl` commands are available for administering workflows. + +## Commands + +### WorkflowCreate + +Creates the workflow with the provided parameters. The workflow is also started, unless -skip_start is specified. + +#### Example + +
WorkflowCreate [-skip_start] <factoryName> [parameters...]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| skip_start | Boolean | If set, the workflow will not be started. | + + +#### Arguments + +* <factoryName> – Required. + +#### Errors + +* the <factoryName> argument is required for the <WorkflowCreate> command This error occurs if the command is not called with at least one argument. +* no workflow.Manager registered + + +### WorkflowStart + +Starts the workflow. + +#### Example + +
WorkflowStart <uuid>
+ +#### Errors + +* the <uuid> argument is required for the <WorkflowStart> command This error occurs if the command is not called with exactly one argument. +* no workflow.Manager registered + + +### WorkflowStop + +Stops the workflow. + +#### Example + +
WorkflowStop <uuid>
+ +#### Errors + +* the <uuid> argument is required for the <WorkflowStop> command This error occurs if the command is not called with exactly one argument. +* no workflow.Manager registered + +### WorkflowDelete + +Deletes the finished or not started workflow. + +#### Example + +
WorkflowDelete <uuid>
+ +#### Errors + +* the <uuid> argument is required for the <WorkflowDelete> command This error occurs if the command is not called with exactly one argument. +* no workflow.Manager registered + +### WorkflowWait +``` +WorkflowWait +``` + +### WorkflowTree + +Displays a JSON representation of the workflow tree. + +#### Example + +
WorkflowTree
+ +#### Errors + +* the <WorkflowTree> command takes no parameter This error occurs if the command is not called with exactly 0 arguments. +* no workflow.Manager registered + +### WorkflowAction +``` +WorkflowAction +``` + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/reference/programs/vtctld.md b/content/en/docs/reference/programs/vtctld.md new file mode 100644 index 000000000..4cbaaacb3 --- /dev/null +++ b/content/en/docs/reference/programs/vtctld.md @@ -0,0 +1,280 @@ +--- +title: vtctld +description: The Vitess Admin GUI +--- + +`vtctld` is a webserver interface to administer a Vitess cluster. It is usually the first Vitess component to be started after a valid global topology service has been created. + +## Example Usage + +The following example launches the `vtctld` daemon on port 15000: + +```bash +export TOPOLOGY_FLAGS="-topo_implementation etcd2 -topo_global_server_address localhost:2379 -topo_global_root /vitess/global" +export VTDATAROOT="/tmp" + +vtctld \ + $TOPOLOGY_FLAGS \ + -workflow_manager_init \ + -workflow_manager_use_election \ + -service_map 'grpc-vtctl' \ + -backup_storage_implementation file \ + -file_backup_storage_root $VTDATAROOT/backups \ + -log_dir $VTDATAROOT/tmp \ + -port 15000 \ + -grpc_port 15999 +``` + + +## Options + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| -action_timeout | duration | time to wait for an action before resorting to force (default 2m0s) | +| -alsologtostderr | | log to standard error as well as files | +| -app_idle_timeout | duration | Idle timeout for app connections (default 1m0s) | +| -app_pool_size | int | Size of the connection pool for app connections (default 40) | +| -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_container_name | string | Azure Blob Container Name | +| -azblob_backup_parallelism | int | Azure Blob operation parallelism (requires extra memory when increased) (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 | boolean | if 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_hook | string | if set, we send the contents of the backup files through this hook. | +| -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) | +| -binlog_player_protocol | string | the protocol to download binlogs from a vttablet (default "grpc") | +| -binlog_use_v3_resharding_mode | boolean | True iff the binlog streamer should use V3-style sharding, which doesn't require a preset sharding key column. (default true) | +| -cell | string | cell to use | +| -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. | +| -cpu_profile | string | write cpu profile to file | +| -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 | +| -db-credentials-file | string | db credentials file; send SIGHUP to reload this file | +| -db-credentials-server | string | db credentials server type (use 'file' for the file implementation) (default "file") | +| -dba_idle_timeout | duration | Idle timeout for dba connections (default 1m0s) | +| -dba_pool_size | int | Size of the connection pool for dba connections (default 20) | +| -disable_active_reparents | boolean | if set, do not allow active reparents. Use this to protect a cluster using external reparents. | +| -discovery_high_replication_lag_minimum_serving | duration | the replication lag that is considered too high when selecting the minimum num vttablets for serving (default 2h0m0s) | +| -discovery_low_replication_lag | duration | the replication lag that is considered low enough to be healthy (default 30s) | +| -emit_stats | boolean | true iff we should emit stats to push-based monitoring/stats backends | +| -enable-consolidator | boolean | This option enables the query consolidator. (default true) | +| -enable-consolidator-replicas | boolean | This option enables the query consolidator only on replicas. | +| -enable-query-plan-field-caching | boollean | This option fetches & caches fields (columns) when storing query plans (default true) | +| -enable-tx-throttler | boolean | If true replication-lag-based throttling on transactions will be enabled. | +| -enable_hot_row_protection | boolean | If true, incoming transactions for the same row (range) will be queued and cannot consume all txpool slots. | +| -enable_hot_row_protection_dry_run | boolean | If true, hot row protection is not enforced but logs if transactions would have been queued. | +| -enable_queries | boolean | if set, allows vtgate and vttablet queries. May have security implications, as the queries will be run from this process. | +| -enable_realtime_stats | boolean | Required for the Realtime Stats view. If set, vtctld will maintain a streaming RPC to each tablet (in all cells) to gather the realtime health stats. | +| -enable_transaction_limit | boolean | If true, limit on number of transactions open at the same time will be enforced for all users. User trying to open a new transaction after exhausting their limit will receive an error immediately, regardless of whether there are available slots or not. | +| -enable_transaction_limit_dry_run | boolean | If true, limit on number of transactions open at the same time will be tracked for all users, but not enforced. | +| -enforce_strict_trans_tables | boolean | If true, vttablet requires MySQL to run with STRICT_TRANS_TABLES or STRICT_ALL_TABLES on. It is recommended to not turn this flag off. Otherwise MySQL may alter your supplied values before saving them to the database. (default true) | +| -file_backup_storage_root | string | root directory for the file backup storage | +| -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_mode | string | Which auth plugin implementation to use (eg: static) | +| -grpc_auth_mtls_allowed_substrings | string | List of substrings of at least one of the client certificate names (separated by colon). | +| -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_auth_static_password_file | string | JSON File to read the users/passwords from. | +| -grpc_ca | string | ca to use, requires TLS, and enforces client cert check | +| -grpc_cert | string | certificate to use, requires grpc_key, enables TLS | +| -grpc_compression | string | how to compress gRPC, default: nothing, supported: snappy | +| -grpc_enable_tracing | boolean | 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_key | string | key to use, requires grpc_cert, enables TLS | +| -grpc_max_connection_age | duration | Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) | +| -grpc_max_connection_age_grace | duration | Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) | +| -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_port | int | Port to listen on for gRPC calls | +| -grpc_prometheus | boolean | Enable gRPC monitoring with Prometheus | +| -grpc_server_initial_conn_window_size | int | grpc server initial connection window size | +| -grpc_server_initial_window_size | int | grpc server initial window size | +| -grpc_server_keepalive_enforcement_policy_min_time | duration | grpc server minimum keepalive time (default 5m0s) | +| -grpc_server_keepalive_enforcement_policy_permit_without_strea | m | grpc server permit client keepalive pings even when there are no active streams (RPCs) | +| -heartbeat_enable | boolean | If true, vttablet records (if master) or checks (if replica) the current time of a replication heartbeat in the table _vt.heartbeat. The result is used to inform the serving state of the vttablet via healthchecks. | +| -heartbeat_interval | duration | How frequently to read and write replication heartbeat. (default 1s) | +| -hot_row_protection_concurrent_transactions | int | Number of concurrent transactions let through to the txpool/MySQL for the same hot row. Should be > 1 to have enough 'ready' transactions in MySQL and benefit from a pipelining effect. (default 5) | +| -hot_row_protection_max_global_queue_size | int | Global queue limit across all row (ranges). Useful to prevent that the queue can grow unbounded. (default 1000) | +| -hot_row_protection_max_queue_size | int | Maximum number of BeginExecute RPCs which will be queued for the same row (range). (default 20) | +| -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) | +| -lameduck-period | duration | keep running at least this long after SIGTERM before stopping (default 50ms) | +| -legacy_replication_lag_algorithm | boolean | use the legacy algorithm when selecting the vttablets for serving (default true) | +| -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 | boolean | log stack traces for errors | +| -log_rotate_max_size | uint | size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) | +| -logtostderr | boolean | log to standard error instead of files | +| -master_connect_retry | duration | how long to wait in between slave -> connection attempts. Only precise to the second. (default 10s) | +| -mem-profile-rate | int | profile every n bytes allocated (default 524288) | +| -min_number_serving_vttablets | int | the minimum number of vttablets that will be continue to be used even with low replication lag (default 2) | +| -mutex-profile-fraction | int | profile every n mutex contention events (see runtime.SetMutexProfileFraction) | +| -mysql_auth_server_static_file | string | JSON File to read the users/passwords from. | +| -mysql_auth_server_static_string | string | JSON representation of the users/passwords config. | +| -mysql_auth_static_reload_interval | duration | Ticker to reload credentials | +| -mysql_clientcert_auth_method | string | client-side authentication method to use. Supported values: mysql_clear_password, dialog. (default "mysql_clear_password") | +| -mysql_server_flush_delay | duration | Delay after which buffered response will flushed to client. (default 100ms) | +| -mysqlctl_client_protocol | string | the protocol to use to talk to the mysqlctl server (default "grpc") | +| -mysqlctl_mycnf_template | string | template file to use for generating the my.cnf file during server init | +| -mysqlctl_socket | string | socket file to use for remote mysqlctl actions (empty for local actions) | +| -onterm_timeout | duration | wait no more than this for OnTermSync handlers before stopping (default 10s) | +| -opentsdb_uri | string | URI of opentsdb /api/put method | +| -pid_file | string | If set, the process will write its pid to the named file, and delete it on graceful shutdown. | +| -pool_hostname_resolve_interval | duration | if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) | +| -port | int | port for the server | +| -proxy_tablets | boolean | Setting this true will make vtctld proxy the tablet status instead of redirecting to them | +| -purge_logs_interval | duration | how often try to remove old logs (default 1h0m0s) | +| -query-log-stream-handler | string | URL handler for streaming queries log (default "/debug/querylog") | +| -querylog-filter-tag | string | string that must be present in the query for it to be logged | +| -querylog-format | string | format for query logs ("text" or "json") (default "text") | +| -queryserver-config-acl-exempt-acl | string | an acl that exempt from table acl checking (this acl is free to access any vitess tables). | +| -queryserver-config-enable-table-acl-dry-run | boolean | If this flag is enabled, tabletserver will emit monitoring metrics and let the request pass regardless of table acl check results | +| -queryserver-config-idle-timeout | int | query server idle timeout (in seconds), vttablet manages various mysql connection pools. This config means if a connection has not been used in given idle timeout, this connection will be removed from pool. This effectively manages number of connection objects and optimize the pool performance. (default 1800) | +| -queryserver-config-max-dml-rows | int | query server max dml rows per statement, maximum number of rows allowed to return at a time for an update or delete with either 1) an equality where clauses on primary keys, or 2) a subselect statement. For update and delete statements in above two categories, vttablet will split the original query into multiple small queries based on this configuration value. | +| -queryserver-config-max-result-size | int | query server max result size, maximum number of rows allowed to return from vttablet for non-streaming queries. (default 10000) | +| -queryserver-config-message-postpone-cap | int | query server message postpone cap is the maximum number of messages that can be postponed at any given time. Set this number to substantially lower than transaction cap, so that the transaction pool isn't exhausted by the message subsystem. (default 4) | +| -queryserver-config-passthrough-dmls | boolean | query server pass through all dml statements without rewriting | +| -queryserver-config-pool-prefill-parallelism | int | query server read pool prefill parallelism, a non-zero value will prefill the pool using the specified parallism. | +| -queryserver-config-pool-size | int | query server read pool size, connection pool is used by regular queries (non streaming, not in a transaction) (default 16) | +| -queryserver-config-query-cache-size | int | query server query cache size, maximum number of queries to be cached. vttablet analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 5000) | +| -queryserver-config-query-pool-timeout | int | query server query pool timeout (in seconds), it is how long vttablet waits for a connection from the query pool. If set to 0 (default) then the overall query timeout is used instead. | +| -queryserver-config-query-pool-waiter-cap | int | query server query pool waiter limit, this is the maximum number of queries that can be queued waiting to get a connection (default 5000) | +| -queryserver-config-query-timeout | int | query server query timeout (in seconds), this is the query timeout in vttablet side. If a query takes more than this timeout, it will be killed. (default 30) | +| -queryserver-config-schema-reload-time | int | query server schema reload time, how often vttablet reloads schemas from underlying MySQL instance in seconds. vttablet keeps table schemas in its own memory and periodically refreshes it from MySQL. This config controls the reload time. (default 1800) | +| -queryserver-config-stream-buffer-size | int | query server stream buffer size, the maximum number of bytes sent from vttablet for each stream call. It's recommended to keep this value in sync with vtgate's stream_buffer_size. (default 32768) | +| -queryserver-config-stream-pool-prefill-parallelism | int | query server stream pool prefill parallelism, a non-zero value will prefill the pool using the specified parallelism | +| -queryserver-config-stream-pool-size | int | query server stream connection pool size, stream pool is used by stream queries: queries that return results to client in a streaming fashion (default 200) | +| -queryserver-config-strict-table-acl | boolean | only allow queries that pass table acl checks | +| -queryserver-config-terse-errors | boolean | prevent bind vars from escaping in returned errors | +| -queryserver-config-transaction-cap | int | query server transaction cap is the maximum number of transactions allowed to happen at any given point of a time for a single vttablet. E.g. by setting transaction cap to 100, there are at most 100 transactions will be processed by a vttablet and the 101th transaction will be blocked (and fail if it cannot get connection within specified timeout) (default 20) | +| -queryserver-config-transaction-prefill-parallelism | int | query server transaction prefill parallelism, a non-zero value will prefill the pool using the specified parallism. | +| -queryserver-config-transaction-timeout | int | query server transaction timeout (in seconds), a transaction will be killed if it takes longer than this value (default 30) | +| -queryserver-config-txpool-timeout | int | query server transaction pool timeout, it is how long vttablet waits if tx pool is full (default 1) | +| -queryserver-config-txpool-waiter-cap | int | query server transaction pool waiter limit, this is the maximum number of transactions that can be queued waiting to get a connection (default 5000) | +| -queryserver-config-warn-result-size | int | query server result size warning threshold, warn if number of rows returned from vttablet for non-streaming queries exceeds this | +| -redact-debug-ui-queries | boolean | redact full queries and bind variables from debug UI | +| -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 | boolean | 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 | boolean | skip the 'certificate is valid' check for SSL connections | +| -schema_change_check_interval | int | this value decides how often we check schema change dir, in seconds (default 60) | +| -schema_change_controller | string | schema change controller is responsible for finding schema changes and responding to schema change events | +| -schema_change_dir | string | directory contains schema changes for all keyspaces. Each keyspace has its own directory and schema changes are expected to live in '$KEYSPACE/input' dir. e.g. test_keyspace/input/*sql, each sql file represents a schema change | +| -schema_change_slave_timeout | duration | how long to wait for slaves to receive the schema change (default 10s) | +| -schema_change_user | string | The user who submits this schema change. | +| -schema_swap_admin_query_timeout | duration | timeout for SQL queries used to save and retrieve meta information for schema swap process (default 30s) | +| -schema_swap_backup_concurrency | int | number of simultaneous compression/checksum jobs to run for seed backup during schema swap (default 4) | +| -schema_swap_delay_between_errors | duration | time to wait after a retryable error happened in the schema swap process (default 1m0s) | +| -schema_swap_reparent_timeout | duration | timeout to wait for slaves when doing reparent during schema swap (default 30s) | +| -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-vtworker | +| -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) | +| -srv_topo_cache_refresh | duration | how frequently to refresh the topology for cached entries (default 1s) | +| -srv_topo_cache_ttl | duration | how long to use cached entries for topology (default 1s) | +| -stats_backend | string | The name of the registered push-based monitoring/stats backend to use | +| -stats_combine_dimensions | string | List of dimensions to be combined into a single "all" value in exported stats vars | +| -stats_drop_variables | string | Variables to be dropped from the list of exported variables. | +| -stats_emit_period | duration | Interval between emitting stats to all registered backends (default 1m0s) | +| -stderrthreshold | value | logs at or above this threshold go to stderr (default 1) | +| -tablet_dir | string | The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. | +| -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_key | string | the key to use to connect | +| -tablet_grpc_server_name | string | the server name to use to validate server certificate | +| -tablet_health_keep_alive | duration | close streaming tablet health connection if there are no requests for this long (default 5m0s) | +| -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_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") | +| -tablet_url_template | string | format string describing debug tablet url formatting. See the Go code for getTabletDebugURL() how to customize this. (default "http://{{.GetTabletHostPort}}") | +| -throttler_client_grpc_ca | string | the server ca to use to validate servers when connecting | +| -throttler_client_grpc_cert | string | the cert to use to connect | +| -throttler_client_grpc_key | string | the key to use to connect | +| -throttler_client_grpc_server_name | string | the server name to use to validate server certificate | +| -throttler_client_protocol | string | the protocol to use to talk to the integrated throttler service (default "grpc") | +| -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 master 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_k8s_context | string | The kubeconfig context to use, overrides the 'current-context' from the config | +| -topo_k8s_kubeconfig | string | Path to a valid kubeconfig file. | +| -topo_k8s_namespace | string | The kubernetes namespace to use for all objects. Default comes from the context or in-cluster config | +| -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-sampling-rate | float | sampling rate for the probabilistic jaeger sampler (default 0.1) | +| -transaction-log-stream-handler | string | URL handler for streaming transactions log (default "/debug/txlog") | +| -transaction_limit_by_component | boolean | Include CallerID.component when considering who the user is for the purpose of transaction limit. | +| -transaction_limit_by_principal | boolean | Include CallerID.principal when considering who the user is for the purpose of transaction limit. (default true) | +| -transaction_limit_by_subcomponent | boolean | Include CallerID.subcomponent when considering who the user is for the purpose of transaction limit. | +| -transaction_limit_by_username | boolean | Include VTGateCallerID.username when considering who the user is for the purpose of transaction limit. (default true) | +| -transaction_limit_per_user | float | Maximum number of transactions a single user is allowed to use at any time, represented as fraction of -transaction_cap. (default 0.4) | +| -transaction_shutdown_grace_period | int | how long to wait (in seconds) for transactions to complete during graceful shutdown. | +| -twopc_abandon_age | float | time in seconds. Any unresolved transaction older than this time will be sent to the coordinator to be resolved. | +| -twopc_coordinator_address | string | address of the (VTGate) process(es) that will be used to notify of abandoned transactions. | +| -twopc_enable | boolean | if the flag is on, 2pc is enabled. Other 2pc flags must be supplied. | +| -tx-throttler-config | string | The configuration of the transaction throttler as a text formatted throttlerdata.Configuration protocol buffer message (default "target_replication_lag_sec: 2\nmax_replication_lag_sec: 10\ninitial_rate: 100\nmax_increase: 1\nemergency_decrease: 0.5\nmin_duration_between_increases_sec: 40\nmax_duration_between_increases_sec: 62\nmin_duration_between_decreases_sec: 20\nspread_backlog_across_sec: 20\nage_bad_rate_after_sec: 180\nbad_rate_increase: 0.1\nmax_rate_approach_threshold: 0.9\n") | +| -tx-throttler-healthcheck-cells | value | A comma-separated list of cells. Only tabletservers running in these cells will be monitored for replication lag by the transaction throttler. | +| -v | value | log level for V logs | +| -version | | print binary version | +| -vmodule | value | comma-separated list of pattern=N settings for file-filtered logging | +| -vreplication_healthcheck_retry_delay | duration | healthcheck retry delay (default 5s) | +| -vreplication_healthcheck_timeout | duration | healthcheck retry delay (default 1m0s) | +| -vreplication_healthcheck_topology_refresh | duration | refresh interval for re-reading the topology (default 30s) | +| -vreplication_retry_delay | duration | delay before retrying a failed binlog connection (default 5s) | +| -vreplication_tablet_type | string | comma separated list of tablet types used as a source (default "REPLICA") | +| -vstream_packet_size | int | Suggested packet size for VReplication streamer. This is used only as a recommendation. The actual packet size may be more or less than this amount. (default 30000) | +| -vtctl_client_protocol | string | the protocol to use to talk to the vtctl server (default "grpc") | +| -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) | +| -vtctld_show_topology_crud | boolean | Controls the display of the CRUD topology actions in the vtctld UI. (default true) | +| -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_key | string | the key to use to connect | +| -vtgate_grpc_server_name | string | the server name to use to validate server certificate | +| -vtgate_protocol | string | how to talk to vtgate (default "grpc") | +| -vtworker_client_grpc_ca | string | the server ca to use to validate servers when connecting | +| -vtworker_client_grpc_cert | string | the cert to use to connect | +| -vtworker_client_grpc_key | string | the key to use to connect | +| -vtworker_client_grpc_server_name | string | the server name to use to validate server certificate | +| -vtworker_client_protocol | string | the protocol to use to talk to the vtworker server (default "grpc") | +| -wait_for_drain_sleep_rdonly | duration | time to wait before shutting the query service on old RDONLY tablets during MigrateServedTypes (default 5s) | +| -wait_for_drain_sleep_replica | duration | time to wait before shutting the query service on old REPLICA tablets during MigrateServedTypes (default 15s) | +| -watch_replication_stream | boolean | When enabled, vttablet will stream the MySQL replication stream from the local server, and use it to support the include_event_token ExecuteOptions. | +| -workflow_manager_disable | value | comma separated list of workflow types to disable | +| -workflow_manager_init | boolean | Initialize the workflow manager in this vtctld instance. | +| -workflow_manager_use_election | boolean | if specified, will use a topology server-based master election to ensure only one workflow manager is active at a time. | +| -xbstream_restore_flags | string | flags 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_flags | string | flags to pass to backup command. These should be space separated and will be added to the end of the command | +| -xtrabackup_prepare_flags | string | flags to pass to prepare command. These should be space separated and will be added to the end of the command | +| -xtrabackup_root_path | string | directory location of the xtrabackup executable, e.g., /usr/bin | +| -xtrabackup_stream_mode | string | which mode to use if streaming, valid values are tar and xbstream (default "tar") | +| -xtrabackup_stripe_block_size | uint | Size in bytes of each block that gets sent to a given stripe before rotating to the next stripe (default 102400) | +| -xtrabackup_stripes | uint | If greater than 0, use data striping across this many destination files to parallelize data transfer and decompression | +| -xtrabackup_user | string | User that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation. | diff --git a/content/en/docs/reference/programs/vtexplain.md b/content/en/docs/reference/programs/vtexplain.md new file mode 100644 index 000000000..07360b9bc --- /dev/null +++ b/content/en/docs/reference/programs/vtexplain.md @@ -0,0 +1,66 @@ +--- +title: vtexplain +aliases: ['/docs/reference/vtexplain/'] +--- + +`vtexplain` is a command line tool which provides information on how Vitess plans to execute a particular query. It can be used to validate queries for compatibility with Vitess. + +For a user guide that describes how to use the `vtexplain` tool to explain how Vitess executes a particular SQL statement, see [Explaining how Vitess executes a SQL statement](../../user-guides/vtexplain). + +## Example Usage + +Explain how Vitess will execute the query `SELECT * FROM users` using the VSchema contained in `vschemas.json` and the database schema `schema.sql`: + +```bash +vtexplain -vschema-file vschema.json -schema-file schema.sql -sql "SELECT * FROM users" +``` + +Explain how the example will execute on 128 shards using Row-based replication: + +```bash +vtexplain -shards 128 -vschema-file vschema.json -schema-file schema.sql -replication-mode "ROW" -output-mode text -sql "INSERT INTO users (user_id, name) VALUES(1, 'john')" +``` + + +## Options + +The following parameters apply to `mysqlctl`: + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| -output-mode | string | Output in human-friendly text or json (default "text") | +| -normalize | | Whether to enable vtgate normalization (default false) | +| -shards | int | Number of shards per keyspace (default 2) | +| -replication-mode | string | The replication mode to simulate -- must be set to either ROW or STATEMENT (default "ROW") | +| -schema | string | The SQL table schema (default "") | +| -schema-file | string | Identifies the file that contains the SQL table schema (default "") | +| -sql | string | A list of semicolon-delimited SQL commands to analyze (default "") | +| -sql-file | string | Identifies the file that contains the SQL commands to analyze (default "") | +| -vschema | string | Identifies the VTGate routing schema (default "") | +| -vschema-file | string | Identifies the VTGate routing schema file (default "") | +| -dbname | string | Optional database target to override normal routing (default "") | +| -queryserver-config-passthrough-dmls | | query server pass through all dml statements without rewriting (default false) | + + +## Limitations + +### The VSchema must use a keyspace name. + +VTExplain requires a keyspace name for each keyspace in an input VSChema: + +``` +"keyspace_name": { + "_comment": "Keyspace definition goes here." +} +``` + +If no keyspace name is present, VTExplain will return the following error: + +``` +ERROR: initVtgateExecutor: json: cannot unmarshal bool into Go value of type map[string]json.RawMessage +``` + +## See also + ++ [Explaining how Vitess executes a SQL statement](../../../user-guides/vtexplain) + diff --git a/content/en/docs/reference/programs/vtgate.md b/content/en/docs/reference/programs/vtgate.md new file mode 100644 index 000000000..0d1526f9a --- /dev/null +++ b/content/en/docs/reference/programs/vtgate.md @@ -0,0 +1,187 @@ +--- +title: vtgate +--- + +VTGate is a stateless proxy responsible for accepting requests from applications and routing them to the appropriate tablet server(s) for query execution. It speaks both the MySQL Protocol and a gRPC protocol. + +## Example Usage + +Start a vtgate proxy: + +```bash +export TOPOLOGY_FLAGS="-topo_implementation etcd2 -topo_global_server_address localhost:2379 -topo_global_root /vitess/global" +export VTDATAROOT="/tmp" + +vtgate \ + $TOPOLOGY_FLAGS \ + -log_dir $VTDATAROOT/tmp \ + -port 15001 \ + -grpc_port 15991 \ + -mysql_server_port 15306 \ + -cell test \ + -cells_to_watch test \ + -tablet_types_to_wait MASTER,REPLICA \ + -gateway_implementation discoverygateway \ + -service_map 'grpc-vtgateservice' \ + -pid_file $VTDATAROOT/tmp/vtgate.pid \ + -mysql_auth_server_impl none +``` + +## Options + +The following global options apply to `vtgate`: + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| -allowed_tablet_types | value | Specifies the tablet types this vtgate is allowed to route queries to | +| -alsologtostderr | boolean | log to standard error as well as files | +| -buffer_drain_concurrency | int | Maximum number of requests retried simultaneously. More concurrency will increase the load on the MASTER vttablet when draining the buffer. (default 1) | +| -buffer_keyspace_shards | string | If not empty, limit buffering to these entries (comma separated). Entry format: keyspace or keyspace/shard. Requires --enable_buffer=true. | +| -buffer_max_failover_duration | duration | Stop buffering completely if a failover takes longer than this duration. (default 20s) | +| -buffer_min_time_between_failovers | duration | Minimum time between the end of a failover and the start of the next one (tracked per shard). Faster consecutive failovers will not trigger buffering. (default 1m0s) | +| -buffer_size | int | Maximum number of buffered requests in flight (across all ongoing failovers). (default 10) | +| -buffer_window | duration | Duration for how long a request should be buffered at most. (default 10s) | +| -cell | string | cell to use (default "test_nj") | +| -cells_to_watch | string | comma-separated list of cells for watching tablets | +| -consul_auth_static_file | string | JSON File to read the topos/tokens from. | +| -cpu_profile | string | write cpu profile to file | +| -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 | +| -default_tablet_type | value | The default tablet type to set for queries, when one is not explicitly selected (default MASTER) | +| -discovery_high_replication_lag_minimum_serving | duration | the replication lag that is considered too high when selecting the minimum num vttablets for serving (default 2h0m0s) | +| -discovery_low_replication_lag | duration | the replication lag that is considered low enough to be healthy (default 30s) | +| -emit_stats | boolean | true iff we should emit stats to push-based monitoring/stats backends | +| -enable_buffer | boolean | Enable buffering (stalling) of master traffic during failovers. | +| -enable_buffer_dry_run | boolean | Detect and log failover events, but do not actually buffer requests. | +| -gate_query_cache_size | int | gate server query cache size, maximum number of queries to be cached. vtgate analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 10000) | +| -gateway_implementation | string | The implementation of gateway (default "discoverygateway") | +| -gateway_initial_tablet_timeout | duration | At startup, the gateway will wait up to that duration to get one tablet per keyspace/shard/tablettype (default 30s) | +| -grpc_auth_mode | string | Which auth plugin implementation to use (eg: static) | +| -grpc_auth_mtls_allowed_substrings | string | List of substrings of at least one of the client certificate names (separated by colon). | +| -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_auth_static_password_file | string | JSON File to read the users/passwords from. | +| -grpc_ca | string | ca to use, requires TLS, and enforces client cert check | +| -grpc_cert | string | certificate to use, requires grpc_key, enables TLS | +| -grpc_compression | string | how to compress gRPC, default: nothing, supported: snappy | +| -grpc_enable_tracing | boolean | 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_key | string | key to use, requires grpc_cert, enables TLS | +| -grpc_max_connection_age | duration | Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) | +| -grpc_max_connection_age_grace | duration | Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) | +| -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_port | int | Port to listen on for gRPC calls | +| -grpc_prometheus | boolean | Enable gRPC monitoring with Prometheus | +| -grpc_server_initial_conn_window_size | int | grpc server initial connection window size | +| -grpc_server_initial_window_size | int | grpc server initial window size | +| -grpc_server_keepalive_enforcement_policy_min_time | duration | grpc server minimum keepalive time (default 5m0s) | +| -grpc_server_keepalive_enforcement_policy_permit_without_stream | boolean | grpc server permit client keepalive pings even when there are no active streams (RPCs) | +| -grpc_use_effective_callerid | boolean | If set, and SSL is not used, will set the immediate caller id from the effective caller id's principal. | +| -healthcheck_retry_delay | duration | health check retry delay (default 2ms) | +| -healthcheck_timeout | duration | the health check timeout period (default 1m0s) | +| -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) | +| -keyspaces_to_watch | value | Specifies which keyspaces this vtgate should have access to while routing queries or accessing the vschema | +| -lameduck-period | duration | keep running at least this long after SIGTERM before stopping (default 50ms) | +| -legacy_replication_lag_algorithm | boolean | use the legacy algorithm when selecting the vttablets for serving (default true) | +| -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 | boolean | log stack traces for errors | +| -log_queries_to_file | string | Enable query logging to the specified file | +| -log_rotate_max_size | uint | size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) | +| -logtostderr | boolean | log to standard error instead of files | +| -max_memory_rows | int | Maximum number of rows that will be held in memory for intermediate results as well as the final result. (default 300000) | +| -mem-profile-rate | int | profile every n bytes allocated (default 524288) | +| -message_stream_grace_period | duration | the amount of time to give for a vttablet to resume if it ends a message stream, usually because of a reparent. (default 30s) | +| -min_number_serving_vttablets | int | the minimum number of vttablets that will be continue to be used even with low replication lag (default 2) | +| -mutex-profile-fraction | int | profile every n mutex contention events (see runtime.SetMutexProfileFraction) | +| -mysql_allow_clear_text_without_tls | boolean | If set, the server will allow the use of a clear text password over non-SSL connections. | +| -mysql_auth_server_impl | string | Which auth server implementation to use. (default "static") | +| -mysql_auth_server_static_file | string | JSON File to read the users/passwords from. | +| -mysql_auth_server_static_string | string | JSON representation of the users/passwords config. | +| -mysql_auth_static_reload_interval | duration | Ticker to reload credentials | +| -mysql_clientcert_auth_method | string | client-side authentication method to use. Supported values: mysql_clear_password, dialog. (default "mysql_clear_password") | +| -mysql_default_workload | string | Default session workload (OLTP, OLAP, DBA) (default "UNSPECIFIED") | +| -mysql_ldap_auth_config_file | string | JSON File from which to read LDAP server config. | +| -mysql_ldap_auth_config_string | string | JSON representation of LDAP server config. | +| -mysql_ldap_auth_method | string | client-side authentication method to use. Supported values: mysql_clear_password, dialog. (default "mysql_clear_password") | +| -mysql_server_bind_address | string | Binds on this address when listening to MySQL binary protocol. Useful to restrict listening to 'localhost' only for instance. | +| -mysql_server_flush_delay | duration | Delay after which buffered response will flushed to client. (default 100ms) | +| -mysql_server_port | int | If set, also listen for MySQL binary protocol connections on this port. (default -1) | +| -mysql_server_query_timeout | duration | mysql query timeout | +| -mysql_server_read_timeout | duration | connection read timeout | +| -mysql_server_require_secure_transport | boolean | Reject insecure connections but only if mysql_server_ssl_cert and mysql_server_ssl_key are provided | +| -mysql_server_socket_path | string | This option specifies the Unix socket file to use when listening for local connections. By default it will be empty and it won't listen to a unix socket | +| -mysql_server_ssl_ca | string | Path to ssl CA for mysql server plugin SSL. If specified, server will require and validate client certs. | +| -mysql_server_ssl_cert | string | Path to the ssl cert for mysql server plugin SSL | +| -mysql_server_ssl_key | string | Path to ssl key for mysql server plugin SSL | +| -mysql_server_version | string | MySQL server version to advertise. (default "5.7.9-Vitess") | +| -mysql_server_write_timeout | duration | connection write timeout | +| -mysql_slow_connect_warn_threshold | duration | Warn if it takes more than the given threshold for a mysql connection to establish | +| -mysql_tcp_version | string | Select tcp, tcp4, or tcp6 to control the socket type. (default "tcp") | +| -normalize_queries | boolean | Rewrite queries with bind vars. Turn this off if the app itself sends normalized queries with bind vars. (default true) | +| -onterm_timeout | duration | wait no more than this for OnTermSync handlers before stopping (default 10s) | +| -opentsdb_uri | string | URI of opentsdb /api/put method | +| -pid_file | string | If set, the process will write its pid to the named file, and delete it on graceful shutdown. | +| -port | int | port for the server | +| -proxy_protocol | boolean | Enable HAProxy PROXY protocol on MySQL listener socket | +| -purge_logs_interval | duration | how often try to remove old logs (default 1h0m0s) | +| -querylog-filter-tag | string | string that must be present in the query for it to be logged | +| -querylog-format | string | format for query logs ("text" or "json") (default "text") | +| -redact-debug-ui-queries | boolean | redact full queries and bind variables from debug UI | +| -remote_operation_timeout | duration | time to wait for a remote operation (default 30s) | +| -retry-count | int | retry count (default 2) | +| -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-vtworker | +| -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) | +| -srv_topo_cache_refresh | duration | how frequently to refresh the topology for cached entries (default 1s) | +| -srv_topo_cache_ttl | duration | how long to use cached entries for topology (default 1s) | +| -stats_backend | string | The name of the registered push-based monitoring/stats backend to use | +| -stats_combine_dimensions | string | List of dimensions to be combined into a single "all" value in exported stats vars | +| -stats_drop_variables | string | Variables to be dropped from the list of exported variables. | +| -stats_emit_period | duration | Interval between emitting stats to all registered backends (default 1m0s) | +| -stderrthreshold | value | logs at or above this threshold go to stderr (default 1) | +| -stream_buffer_size | int | the number of bytes sent from vtgate for each stream call. It's recommended to keep this value in sync with vttablet's query-server-config-stream-buffer-size. (default 32768) | +| -tablet_filters | value | Specifies a comma-separated list of 'keyspace|shard_name or keyrange' values to filter the tablets to watch | +| -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_key | string | the key to use to connect | +| -tablet_grpc_server_name | string | the server name to use to validate server certificate | +| -tablet_protocol | string | how to talk to the vttablets (default "grpc") | +| -tablet_refresh_interval | duration | tablet refresh interval (default 1m0s) | +| -tablet_refresh_known_tablets | boolean | tablet refresh reloads the tablet address/port map from topo in case it changes (default true) | +| -tablet_types_to_wait | string | wait till connected for specified tablet types during Gateway initialization | +| -tablet_url_template | string | format string describing debug tablet url formatting. See the Go code for getTabletDebugURL() how to customize this. (default "http://{{.GetTabletHostPort}}") | +| -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 master 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_k8s_context | string | The kubeconfig context to use, overrides the 'current-context' from the config | +| -topo_k8s_kubeconfig | string | Path to a valid kubeconfig file. | +| -topo_k8s_namespace | string | The kubernetes namespace to use for all objects. Default comes from the context or in-cluster config | +| -topo_read_concurrency | int | concurrent topo reads (default 32) | +| -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-sampling-rate | float | sampling rate for the probabilistic jaeger sampler (default 0.1) | +| -transaction_mode | string | SINGLE: disallow multi-db transactions, MULTI: allow multi-db transactions with best effort commit, TWOPC: allow multi-db transactions with 2pc commit (default "MULTI") | +| -v | value | log level for V logs | +| -version | boolean | print binary version | +| -vmodule | value | comma-separated list of pattern=N settings for file-filtered logging | +| -vschema_ddl_authorized_users | string | List of users authorized to execute vschema ddl operations, or '%' to allow all users. | +| -vtctld_addr | string | address of a vtctld instance | +| -vtgate-config-terse-errors | boolean | prevent bind vars from escaping in returned errors | +| -warn_memory_rows | int | Warning threshold for in-memory results. A row count higher than this amount will cause the VtGateWarnings.ResultsExceeded counter to be incremented. (default 30000) | + diff --git a/content/en/docs/reference/programs/vttablet.md b/content/en/docs/reference/programs/vttablet.md new file mode 100644 index 000000000..7fc335d78 --- /dev/null +++ b/content/en/docs/reference/programs/vttablet.md @@ -0,0 +1,378 @@ +--- +title: vttablet +aliases: ['/docs/user-guides/vttablet-modes/','/docs/reference/vttablet-modes/'] +--- + +A VTTablet server _controls_ a running MySQL server. VTTablet supports two primary types of deployments: + +* Managed MySQL (most common) +* Unmanaged or Remote MySQL + +In addition to these deployment types, a partially managed VTTablet is also possible by setting `-disable_active_reparents`. + + +## Example Usage + +### Managed MySQL + +In this mode, Vitess actively manages MySQL: + +```bash +export TOPOLOGY_FLAGS="-topo_implementation etcd2 -topo_global_server_address localhost:2379 -topo_global_root /vitess/global" +export VTDATAROOT="/tmp" + +vttablet \ +$TOPOLOGY_FLAGS +-tablet-path $alias +-init_keyspace $keyspace +-init_shard $shard +-init_tablet_type $tablet_type +-port $port +-grpc_port $grpc_port +-service_map 'grpc-queryservice,grpc-tabletmanager,grpc-updatestream' +``` + +`$alias` needs to be of the form: `-id`, and the cell should match one of the local cells that was created in the topology. The id can be left padded with zeroes: `cell-100` and `cell-000000100` are synonymous. + +### Unmanaged or Remote MySQL + +In this mode, an external MySQL can be used such as RDS, Aurora, CloudSQL: + +```bash +mkdir -p $VTDATAROOT/vt_0000000401 +vttablet \ + $TOPOLOGY_FLAGS \ + -logtostderr \ + -log_queries_to_file $VTDATAROOT/tmp/vttablet_0000000401_querylog.txt \ + -tablet-path "zone1-0000000401" \ + -init_keyspace legacy \ + -init_shard 0 \ + -init_tablet_type replica \ + -port 15401 \ + -grpc_port 16401 \ + -service_map 'grpc-queryservice,grpc-tabletmanager,grpc-updatestream' \ + -pid_file $VTDATAROOT/vt_0000000401/vttablet.pid \ + -vtctld_addr http://localhost:15000/ \ + -db_host 127.0.0.1 \ + -db_port 5726 \ + -db_app_user msandbox \ + -db_app_password msandbox \ + -init_db_name_override legacy \ + -init_populate_metadata & + +sleep 10 +vtctlclient InitShardMaster -force legacy/0 zone1-401 +``` + +See [Unmanaged Tablet](../../../user-guides/unmanaged-tablet) for the full guide. + + +## Options + +The following global options apply to `vttablet`: + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| -alsologtostderr | boolean | log to standard error as well as files | +| -app_idle_timeout | duration | Idle timeout for app connections (default 1m0s) | +| -app_pool_size | int | Size of the connection pool for app connections (default 40) | +| -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_container_name | string | Azure Blob Container Name | +| -azblob_backup_parallelism | int | Azure Blob operation parallelism (requires extra memory when increased) (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). Set to false for instance if a backup_storage_hook is specified and it compresses the data. (default true) | +| -backup_storage_hook | string | if set, we send the contents of the backup files through this hook. | +| -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) | +| -binlog_player_grpc_ca | string | the server ca to use to validate servers when connecting | +| -binlog_player_grpc_cert | string | the cert to use to connect | +| -binlog_player_grpc_key | string | the key to use to connect | +| -binlog_player_grpc_server_name | string | the server name to use to validate server certificate | +| -binlog_player_protocol | string | the protocol to download binlogs from a vttablet (default "grpc") | +| -binlog_use_v3_resharding_mode | | True iff the binlog streamer should use V3-style sharding, which doesn't require a preset sharding key column. (default true) | +| -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. | +| -cpu_profile | string | write cpu profile to file | +| -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 | +| -db-credentials-file | string | db credentials file; send SIGHUP to reload this file | +| -db-credentials-server | string | db credentials server type (use 'file' for the file implementation) (default "file") | +| -db_allprivs_password | string | db allprivs password | +| -db_allprivs_use_ssl | | Set this flag to false to make the allprivs connection to not use ssl (default true) | +| -db_allprivs_user | string | db allprivs user userKey (default "vt_allprivs") | +| -db_app_password | string | db app password | +| -db_app_use_ssl | | Set this flag to false to make the app connection to not use ssl (default true) | +| -db_app_user | string | db app user userKey (default "vt_app") | +| -db_appdebug_password | string | db appdebug password | +| -db_appdebug_use_ssl | | Set this flag to false to make the appdebug connection to not use ssl (default true) | +| -db_appdebug_user | string | db appdebug user userKey (default "vt_appdebug") | +| -db_charset | string | Character set. Only utf8 or latin1 based character sets are supported. | +| -db_connect_timeout_ms | int | connection timeout to mysqld in milliseconds (0 for no timeout) | +| -db_dba_password | string | db dba password | +| -db_dba_use_ssl | | Set this flag to false to make the dba connection to not use ssl (default true) | +| -db_dba_user | string | db dba user userKey (default "vt_dba") | +| -db_erepl_password | string | db erepl password | +| -db_erepl_use_ssl | | Set this flag to false to make the erepl connection to not use ssl (default true) | +| -db_erepl_user | string | db erepl user userKey (default "vt_erepl") | +| -db_filtered_password | string | db filtered password | +| -db_filtered_use_ssl | | Set this flag to false to make the filtered connection to not use ssl (default true) | +| -db_filtered_user | string | db filtered user userKey (default "vt_filtered") | +| -db_flags | uint | Flag values as defined by MySQL. | +| -db_flavor | string | Flavor overrid. Valid value is FilePos. | +| -db_host | string | The host name for the tcp connection. | +| -db_port | int | tcp port | +| -db_repl_password | string | db repl password | +| -db_repl_use_ssl | | Set this flag to false to make the repl connection to not use ssl (default true) | +| -db_repl_user | string | db repl user userKey (default "vt_repl") | +| -db_server_name | string | server name of the DB we are connecting to. | +| -db_socket | string | The unix socket to connect on. If this is specified, host and port will not be used. | +| -db_ssl_ca | string | connection ssl ca | +| -db_ssl_ca_path | string | connection ssl ca path | +| -db_ssl_cert | string | connection ssl certificate | +| -db_ssl_key | string | connection ssl key | +| -dba_idle_timeout | duration | Idle timeout for dba connections (default 1m0s) | +| -dba_pool_size | int | Size of the connection pool for dba connections (default 20) | +| -degraded_threshold | duration | replication lag after which a replica is considered degraded (only used in status UI) (default 30s) | +| -demote_master_type | string | the tablet type a demoted master will transition to (default "REPLICA") | +| -disable_active_reparents | | if set, do not allow active reparents. Use this to protect a cluster using external reparents. | +| -discovery_high_replication_lag_minimum_serving | duration | the replication lag that is considered too high when selecting the minimum num vttablets for serving (default 2h0m0s) | +| -discovery_low_replication_lag | duration | the replication lag that is considered low enough to be healthy (default 30s) | +| -emit_stats | | true iff we should emit stats to push-based monitoring/stats backends | +| -enable-consolidator | | This option enables the query consolidator. (default true) | +| -enable-consolidator-replicas | | This option enables the query consolidator only on replicas. | +| -enable-query-plan-field-caching | | This option fetches & caches fields (columns) when storing query plans (default true) | +| -enable-tx-throttler | | If true replication-lag-based throttling on transactions will be enabled. | +| -enable_hot_row_protection | | If true, incoming transactions for the same row (range) will be queued and cannot consume all txpool slots. | +| -enable_hot_row_protection_dry_run | | If true, hot row protection is not enforced but logs if transactions would have been queued. | +| -enable_replication_reporter | | Register the health check module that monitors MySQL replication | +| -enable_semi_sync | | Enable semi-sync when configuring replication, on master and replica tablets only (rdonly tablets will not ack). | +| -enable_transaction_limit | | If true, limit on number of transactions open at the same time will be enforced for all users. User trying to open a new transaction after exhausting their limit will receive an error immediately, regardless of whether there are available slots or not. | +| -enable_transaction_limit_dry_run | | If true, limit on number of transactions open at the same time will be tracked for all users, but not enforced. | +| -enforce-tableacl-config | | if this flag is true, vttablet will fail to start if a valid tableacl config does not exist | +| -enforce_strict_trans_tables | | If true, vttablet requires MySQL to run with STRICT_TRANS_TABLES or STRICT_ALL_TABLES on. It is recommended to not turn this flag off. Otherwise MySQL may alter your supplied values before saving them to the database. (default true) | +| -file_backup_storage_root | string | root directory for the file backup storage | +| -filecustomrules | string | file based custom rule path | +| -finalize_external_reparent_timeout | duration | Timeout for the finalize stage of a fast external reparent reconciliation. (default 30s) | +| -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_mode | string | Which auth plugin implementation to use (eg: static) | +| -grpc_auth_mtls_allowed_substrings | string | List of substrings of at least one of the client certificate names (separated by colon). | +| -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_auth_static_password_file | string | JSON File to read the users/passwords from. | +| -grpc_ca | string | ca to use, requires TLS, and enforces client cert check | +| -grpc_cert | string | certificate to use, requires grpc_key, enables TLS | +| -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_key | string | key to use, requires grpc_cert, enables TLS | +| -grpc_max_connection_age | duration | Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) | +| -grpc_max_connection_age_grace | duration | Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) | +| -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_port | int | Port to listen on for gRPC calls | +| -grpc_prometheus | | Enable gRPC monitoring with Prometheus | +| -grpc_server_initial_conn_window_size | int | grpc server initial connection window size | +| -grpc_server_initial_window_size | int | grpc server initial window size | +| -grpc_server_keepalive_enforcement_policy_min_time | duration | grpc server minimum keepalive time (default 5m0s) | +| -grpc_server_keepalive_enforcement_policy_permit_without_stream | | grpc server permit client keepalive pings even when there are no active streams (RPCs) | +| -health_check_interval | duration | Interval between health checks (default 20s) | +| -heartbeat_enable | | If true, vttablet records (if master) or checks (if replica) the current time of a replication heartbeat in the table _vt.heartbeat. The result is used to inform the serving state of the vttablet via healthchecks. | +| -heartbeat_interval | duration | How frequently to read and write replication heartbeat. (default 1s) | +| -hot_row_protection_concurrent_transactions | int | Number of concurrent transactions let through to the txpool/MySQL for the same hot row. Should be > 1 to have enough 'ready' transactions in MySQL and benefit from a pipelining effect. (default 5) | +| -hot_row_protection_max_global_queue_size | int | Global queue limit across all row (ranges). Useful to prevent that the queue can grow unbounded. (default 1000) | +| -hot_row_protection_max_queue_size | int | Maximum number of BeginExecute RPCs which will be queued for the same row (range). (default 20) | +| -init_db_name_override | string | (init parameter) override the name of the db used by vttablet. Without this flag, the db name defaults to vt_ | +| -init_keyspace | string | (init parameter) keyspace to use for this tablet | +| -init_populate_metadata | | (init parameter) populate metadata tables even if restore_from_backup is disabled. If restore_from_backup is enabled, metadata tables are always populated regardless of this flag. | +| -init_shard | string | (init parameter) shard to use for this tablet | +| -init_tablet_type | string | (init parameter) the tablet type to use for this tablet. | +| -init_tags | value | (init parameter) comma separated list of key:value pairs used to tag the tablet | +| -init_timeout | duration | (init parameter) timeout to use for the init phase. (default 1m0s) | +| -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) | +| -lameduck-period | duration | keep running at least this long after SIGTERM before stopping (default 50ms) | +| -legacy_replication_lag_algorithm | | use the legacy algorithm when selecting the vttablets for serving (default true) | +| -lock_tables_timeout | duration | How long to keep the table locked before timing out (default 1m0s) | +| -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_queries | | Enable query logging to syslog. | +| -log_queries_to_file | string | Enable query logging to the specified file | +| -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 | +| -master_connect_retry | duration | how long to wait in between slave -> connection attempts. Only precise to the second. (default 10s) | +| -mem-profile-rate | int | profile every n bytes allocated (default 524288) | +| -min_number_serving_vttablets | int | the minimum number of vttablets that will be continue to be used even with low replication lag (default 2) | +| -mutex-profile-fraction | int | profile every n mutex contention events (see runtime.SetMutexProfileFraction) | +| -mycnf-file | string | path to my.cnf, if reading all config params from there | +| -mycnf_bin_log_path | string | mysql binlog path | +| -mycnf_data_dir | string | data directory for mysql | +| -mycnf_error_log_path | string | mysql error log path | +| -mycnf_general_log_path | string | mysql general log path | +| -mycnf_innodb_data_home_dir | string | Innodb data home directory | +| -mycnf_innodb_log_group_home_dir | string | Innodb log group home directory | +| -mycnf_master_info_file | string | mysql master.info file | +| -mycnf_mysql_port | int | port mysql is listening on | +| -mycnf_pid_file | string | mysql pid file | +| -mycnf_relay_log_index_path | string | mysql relay log index path | +| -mycnf_relay_log_info_path | string | mysql relay log info path | +| -mycnf_relay_log_path | string | mysql relay log path | +| -mycnf_server_id | int | mysql server id of the server (if specified, mycnf-file will be ignored) | +| -mycnf_slave_load_tmp_dir | string | slave load tmp directory | +| -mycnf_slow_log_path | string | mysql slow query log path | +| -mycnf_socket_file | string | mysql socket file | +| -mycnf_tmp_dir | string | mysql tmp directory | +| -mysql_auth_server_static_file | string | JSON File to read the users/passwords from. | +| -mysql_auth_server_static_string | string | JSON representation of the users/passwords config. | +| -mysql_auth_static_reload_interval | duration | Ticker to reload credentials | +| -mysql_clientcert_auth_method | string | client-side authentication method to use. Supported values: mysql_clear_password, dialog. (default "mysql_clear_password") | +| -mysql_server_flush_delay | duration | Delay after which buffered response will flushed to client. (default 100ms) | +| -mysqlctl_client_protocol | string | the protocol to use to talk to the mysqlctl server (default "grpc") | +| -mysqlctl_mycnf_template | string | template file to use for generating the my.cnf file during server init | +| -mysqlctl_socket | string | socket file to use for remote mysqlctl actions (empty for local actions) | +| -onterm_timeout | duration | wait no more than this for OnTermSync handlers before stopping (default 10s) | +| -opentsdb_uri | string | URI of opentsdb /api/put method | +| -orc_api_password | string | (Optional) Basic auth password to authenticate with Orchestrator's HTTP API. | +| -orc_api_url | string | Address of Orchestrator's HTTP API (e.g. http://host:port/api/). Leave empty to disable Orchestrator integration. | +| -orc_api_user | string | (Optional) Basic auth username to authenticate with Orchestrator's HTTP API. Leave empty to disable basic auth. | +| -orc_discover_interval | duration | How often to ping Orchestrator's HTTP API endpoint to tell it we exist. 0 means never. | +| -orc_timeout | duration | Timeout for calls to Orchestrator's HTTP API (default 30s) | +| -pid_file | string | If set, the process will write its pid to the named file, and delete it on graceful shutdown. | +| -pool_hostname_resolve_interval | duration | if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) | +| -port | int | port for the server | +| -purge_logs_interval | duration | how often try to remove old logs (default 1h0m0s) | +| -query-log-stream-handler | string | URL handler for streaming queries log (default "/debug/querylog") | +| -querylog-filter-tag | string | string that must be present in the query for it to be logged | +| -querylog-format | string | format for query logs ("text" or "json") (default "text") | +| -queryserver-config-acl-exempt-acl | string | an acl that exempt from table acl checking (this acl is free to access any vitess tables). | +| -queryserver-config-enable-table-acl-dry-run | | If this flag is enabled, tabletserver will emit monitoring metrics and let the request pass regardless of table acl check results | +| -queryserver-config-idle-timeout | int | query server idle timeout (in seconds), vttablet manages various mysql connection pools. This config means if a connection has not been used in given idle timeout, this connection will be removed from pool. This effectively manages number of connection objects and optimize the pool performance. (default 1800) | +| -queryserver-config-max-dml-rows | int | query server max dml rows per statement, maximum number of rows allowed to return at a time for an update or delete with either 1) an equality where clauses on primary keys, or 2) a subselect statement. For update and delete statements in above two categories, vttablet will split the original query into multiple small queries based on this configuration value. | +| -queryserver-config-max-result-size | int | query server max result size, maximum number of rows allowed to return from vttablet for non-streaming queries. (default 10000) | +| -queryserver-config-message-postpone-cap | int | query server message postpone cap is the maximum number of messages that can be postponed at any given time. Set this number to substantially lower than transaction cap, so that the transaction pool isn't exhausted by the message subsystem. (default 4) | +| -queryserver-config-passthrough-dmls | | query server pass through all dml statements without rewriting | +| -queryserver-config-pool-prefill-parallelism | int | query server read pool prefill parallelism, a non-zero value will prefill the pool using the specified parallism. | +| -queryserver-config-pool-size | int | query server read pool size, connection pool is used by regular queries (non streaming, not in a transaction) (default 16) | +| -queryserver-config-query-cache-size | int | query server query cache size, maximum number of queries to be cached. vttablet analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 5000) | +| -queryserver-config-query-pool-timeout | int | query server query pool timeout (in seconds), it is how long vttablet waits for a connection from the query pool. If set to 0 (default) then the overall query timeout is used instead. | +| -queryserver-config-query-pool-waiter-cap | int | query server query pool waiter limit, this is the maximum number of queries that can be queued waiting to get a connection (default 5000) | +| -queryserver-config-query-timeout | int | query server query timeout (in seconds), this is the query timeout in vttablet side. If a query takes more than this timeout, it will be killed. (default 30) | +| -queryserver-config-schema-reload-time | int | query server schema reload time, how often vttablet reloads schemas from underlying MySQL instance in seconds. vttablet keeps table schemas in its own memory and periodically refreshes it from MySQL. This config controls the reload time. (default 1800) | +| -queryserver-config-stream-buffer-size | int | query server stream buffer size, the maximum number of bytes sent from vttablet for each stream call. It's recommended to keep this value in sync with vtgate's stream_buffer_size. (default 32768) | +| -queryserver-config-stream-pool-prefill-parallelism | int | query server stream pool prefill parallelism, a non-zero value will prefill the pool using the specified parallelism | +| -queryserver-config-stream-pool-size | int | query server stream connection pool size, stream pool is used by stream queries: queries that return results to client in a streaming fashion (default 200) | +| -queryserver-config-strict-table-acl | | only allow queries that pass table acl checks | +| -queryserver-config-terse-errors | | prevent bind vars from escaping in returned errors | +| -queryserver-config-transaction-cap | int | query server transaction cap is the maximum number of transactions allowed to happen at any given point of a time for a single vttablet. E.g. by setting transaction cap to 100, there are at most 100 transactions will be processed by a vttablet and the 101th transaction will be blocked (and fail if it cannot get connection within specified timeout) (default 20) | +| -queryserver-config-transaction-prefill-parallelism | int | query server transaction prefill parallelism, a non-zero value will prefill the pool using the specified parallism. | +| -queryserver-config-transaction-timeout | int | query server transaction timeout (in seconds), a transaction will be killed if it takes longer than this value (default 30) | +| -queryserver-config-txpool-timeout | int | query server transaction pool timeout, it is how long vttablet waits if tx pool is full (default 1) | +| -queryserver-config-txpool-waiter-cap | int | query server transaction pool waiter limit, this is the maximum number of transactions that can be queued waiting to get a connection (default 5000) | +| -queryserver-config-warn-result-size | int | query server result size warning threshold, warn if number of rows returned from vttablet for non-streaming queries exceeds this | +| -redact-debug-ui-queries | | redact full queries and bind variables from debug UI | +| -remote_operation_timeout | duration | time to wait for a remote operation (default 30s) | +| -restore_concurrency | int | (init restore parameter) how many concurrent files to restore at once (default 4) | +| -restore_from_backup | | (init restore parameter) will check BackupStorage for a recent backup at startup and start there | +| -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-vtworker | +| -serving_state_grace_period | duration | how long to pause after broadcasting health to vtgate, before enforcing a new serving state | +| -shard_sync_retry_delay | duration | delay between retries of updates to keep the tablet and its shard record in sync (default 30s) | +| -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) | +| -srv_topo_cache_refresh | duration | how frequently to refresh the topology for cached entries (default 1s) | +| -srv_topo_cache_ttl | duration | how long to use cached entries for topology (default 1s) | +| -stats_backend | string | The name of the registered push-based monitoring/stats backend to use | +| -stats_combine_dimensions | string | List of dimensions to be combined into a single "all" value in exported stats vars | +| -stats_drop_variables | string | Variables to be dropped from the list of exported variables. | +| -stats_emit_period | duration | Interval between emitting stats to all registered backends (default 1m0s) | +| -stderrthreshold | value | logs at or above this threshold go to stderr (default 1) | +| -table-acl-config | string | path to table access checker config file; send SIGHUP to reload this file | +| -table-acl-config-reload-interval | duration | Ticker to reload ACLs | +| -tablet-path | string | tablet alias | +| -tablet_config | string | YAML file config for tablet | +| -tablet_dir | string | The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. | +| -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_key | string | the key to use to connect | +| -tablet_grpc_server_name | string | the server name to use to validate server certificate | +| -tablet_hostname | string | if not empty, this hostname will be assumed instead of trying to resolve it | +| -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_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") | +| -tablet_url_template | string | format string describing debug tablet url formatting. See the Go code for getTabletDebugURL() how to customize this. (default "http://{{.GetTabletHostPort}}") | +| -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 master 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_k8s_context | string | The kubeconfig context to use, overrides the 'current-context' from the config | +| -topo_k8s_kubeconfig | string | Path to a valid kubeconfig file. | +| -topo_k8s_namespace | string | The kubernetes namespace to use for all objects. Default comes from the context or in-cluster config | +| -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 | +| -topocustomrule_cell | string | topo cell for customrules file. (default "global") | +| -topocustomrule_path | string | path for customrules file. Disabled if empty. | +| -tracer | string | tracing service to use (default "noop") | +| -tracing-sampling-rate | float | sampling rate for the probabilistic jaeger sampler (default 0.1) | +| -transaction-log-stream-handler | string | URL handler for streaming transactions log (default "/debug/txlog") | +| -transaction_limit_by_component | | Include CallerID.component when considering who the user is for the purpose of transaction limit. | +| -transaction_limit_by_principal | | Include CallerID.principal when considering who the user is for the purpose of transaction limit. (default true) | +| -transaction_limit_by_subcomponent | | Include CallerID.subcomponent when considering who the user is for the purpose of transaction limit. | +| -transaction_limit_by_username | | Include VTGateCallerID.username when considering who the user is for the purpose of transaction limit. (default true) | +| -transaction_limit_per_user | float | Maximum number of transactions a single user is allowed to use at any time, represented as fraction of -transaction_cap. (default 0.4) | +| -transaction_shutdown_grace_period | int | how long to wait (in seconds) for transactions to complete during graceful shutdown. | +| -twopc_abandon_age | float | time in seconds. Any unresolved transaction older than this time will be sent to the coordinator to be resolved. | +| -twopc_coordinator_address | string | address of the (VTGate) process(es) that will be used to notify of abandoned transactions. | +| -twopc_enable | | if the flag is on, 2pc is enabled. Other 2pc flags must be supplied. | +| -tx-throttler-config | string | The configuration of the transaction throttler as a text formatted throttlerdata.Configuration protocol buffer message (default "target_replication_lag_sec: 2\nmax_replication_lag_sec: 10\ninitial_rate: 100\nmax_increase: 1\nemergency_decrease: 0.5\nmin_duration_between_increases_sec: 40\nmax_duration_between_increases_sec: 62\nmin_duration_between_decreases_sec: 20\nspread_backlog_across_sec: 20\nage_bad_rate_after_sec: 180\nbad_rate_increase: 0.1\nmax_rate_approach_threshold: 0.9\n") | +| -tx-throttler-healthcheck-cells | value | A comma-separated list of cells. Only tabletservers running in these cells will be monitored for replication lag by the transaction throttler. | +| -unhealthy_threshold | duration | replication lag after which a replica is considered unhealthy (default 2h0m0s) | +| -use_super_read_only | | Set super_read_only flag when performing planned failover. | +| -v | value | log level for V logs | +| -version | | print binary version | +| -vmodule | value | comma-separated list of pattern=N settings for file-filtered logging | +| -vreplication_healthcheck_retry_delay | duration | healthcheck retry delay (default 5s) | +| -vreplication_healthcheck_timeout | duration | healthcheck retry delay (default 1m0s) | +| -vreplication_healthcheck_topology_refresh | duration | refresh interval for re-reading the topology (default 30s) | +| -vreplication_retry_delay | duration | delay before retrying a failed binlog connection (default 5s) | +| -vreplication_tablet_type | string | comma separated list of tablet types used as a source (default "REPLICA") | +| -vstream_packet_size | int | Suggested packet size for VReplication streamer. This is used only as a recommendation. The actual packet size may be more or less than this amount. (default 30000) | +| -vtctld_addr | string | address of a vtctld instance | +| -vtgate_protocol | string | how to talk to vtgate (default "grpc") | +| -wait_for_backup_interval | duration | (init restore parameter) if this is greater than 0, instead of starting up empty when no backups are found, keep checking at this interval for a backup to appear | +| -watch_replication_stream | | When enabled, vttablet will stream the MySQL replication stream from the local server, and use it to support the include_event_token ExecuteOptions. | +| -xbstream_restore_flags | string | flags 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_flags | string | flags to pass to backup command. These should be space separated and will be added to the end of the command | +| -xtrabackup_prepare_flags | string | flags to pass to prepare command. These should be space separated and will be added to the end of the command | +| -xtrabackup_root_path | string | directory location of the xtrabackup executable, e.g., /usr/bin | +| -xtrabackup_stream_mode | string | which mode to use if streaming, valid values are tar and xbstream (default "tar") | +| -xtrabackup_stripe_block_size | uint | Size in bytes of each block that gets sent to a given stripe before rotating to the next stripe (default 102400) | +| -xtrabackup_stripes | uint | If greater than 0, use data striping across this many destination files to parallelize data transfer and decompression | +| -xtrabackup_user | string | User that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation. | + diff --git a/content/en/docs/reference/vitess-api.md b/content/en/docs/reference/vitess-api.md deleted file mode 100644 index 3b545a2d3..000000000 --- a/content/en/docs/reference/vitess-api.md +++ /dev/null @@ -1,1038 +0,0 @@ ---- -title: Vitess API Reference -noToc: true -weight: 1 ---- - -This document describes Vitess API methods that enable your client application to more easily talk to your storage system to query data. API methods are grouped into the following categories: - -* [Range-based Sharding](#range-based-sharding) -* [Transactions](#transactions) -* [Custom Sharding](#custom-sharding) -* [Map Reduce](#map-reduce) -* [Topology](#topology) -* [v3 API (alpha)](#v3-api-(alpha)) - -The following table lists the methods in each group and links to more detail about each method: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Range-based Sharding
ExecuteBatchKeyspaceIdsExecuteBatchKeyspaceIds executes the list of queries based on the specified keyspace ids.
ExecuteEntityIdsExecuteEntityIds executes the query based on the specified external id to keyspace id map.
ExecuteKeyRangesExecuteKeyRanges executes the query based on the specified key ranges.
ExecuteKeyspaceIdsExecuteKeyspaceIds executes the query based on the specified keyspace ids.
StreamExecuteKeyRangesStreamExecuteKeyRanges executes a streaming query based on key ranges. Use this method if the query returns a large number of rows.
StreamExecuteKeyspaceIdsStreamExecuteKeyspaceIds executes a streaming query based on keyspace ids. Use this method if the query returns a large number of rows.
Transactions
BeginBegin a transaction.
CommitCommit a transaction.
ResolveTransactionResolveTransaction resolves a transaction.
RollbackRollback a transaction.
Custom Sharding
ExecuteBatchShardsExecuteBatchShards executes the list of queries on the specified shards.
ExecuteShardsExecuteShards executes the query on the specified shards.
StreamExecuteShardsStreamExecuteShards executes a streaming query based on shards. Use this method if the query returns a large number of rows.
Map Reduce
SplitQuerySplit a query into non-overlapping sub queries
Topology
GetSrvKeyspaceGetSrvKeyspace returns a SrvKeyspace object (as seen by this vtgate). This method is provided as a convenient way for clients to take a look at the sharding configuration for a Keyspace. Looking at the sharding information should not be used for routing queries (as the information may change, use the Execute calls for that). It is convenient for monitoring applications for instance, or if using custom sharding.
v3 API (alpha)
ExecuteExecute tries to route the query to the right shard. It depends on the query and bind variables to provide enough information in conjonction with the vindexes to route the query.
StreamExecuteStreamExecute executes a streaming query based on shards. It depends on the query and bind variables to provide enough information in conjonction with the vindexes to route the query. Use this method if the query returns a large number of rows.
- -## Range-based Sharding -### ExecuteBatchKeyspaceIds - -ExecuteBatchKeyspaceIds executes the list of queries based on the specified keyspace ids. - -#### Request - - ExecuteBatchKeyspaceIdsRequest is the payload to ExecuteBatchKeyspaceId. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| queries
list <[BoundKeyspaceIdQuery](#boundkeyspaceidquery)>| BoundKeyspaceIdQuery represents a single query request for the specified list of keyspace ids. This is used in a list for ExecuteBatchKeyspaceIdsRequest. | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| as_transaction
bool| as_transaction will execute the queries in this batch in a single transaction per shard, created for this purpose. (this can be seen as adding a 'begin' before and 'commit' after the queries). Only makes sense if tablet_type is master. If set, the Session is ignored. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Response - - ExecuteBatchKeyspaceIdsResponse is the returned value from ExecuteBatchKeyspaceId. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| error
[vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| results
list <[query.QueryResult](#query.queryresult)>| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -### ExecuteEntityIds - -ExecuteEntityIds executes the query based on the specified external id to keyspace id map. - -#### Request - - ExecuteEntityIdsRequest is the payload to ExecuteEntityIds. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| keyspace
string| keyspace to target the query to. | -| entity_column_name
string| entity_column_name is the column name to use. | -| entity_keyspace_ids
list <[EntityId](#executeentityidsrequest.entityid)>| entity_keyspace_ids are pairs of entity_column_name values associated with its corresponding keyspace_id. | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| not_in_transaction
bool| not_in_transaction is deprecated and should not be used. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Messages - -##### ExecuteEntityIdsRequest.EntityId - -Properties - -| Name |Description | -| :-------- | :-------- -| type
[query.Type](#query.type)| Type defines the various supported data types in bind vars and query results. | -| value
bytes| value is the value for the entity. Not set if type is NULL_TYPE. | -| keyspace_id
bytes| keyspace_id is the associated keyspace_id for the entity. | - -#### Response - - ExecuteEntityIdsResponse is the returned value from ExecuteEntityIds. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| error
[vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| result
[query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -### ExecuteKeyRanges - -ExecuteKeyRanges executes the query based on the specified key ranges. - -#### Request - - ExecuteKeyRangesRequest is the payload to ExecuteKeyRanges. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| keyspace
string| keyspace to target the query to | -| key_ranges
list <[topodata.KeyRange](#topodata.keyrange)>| KeyRange describes a range of sharding keys, when range-based sharding is used. | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| not_in_transaction
bool| not_in_transaction is deprecated and should not be used. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Response - - ExecuteKeyRangesResponse is the returned value from ExecuteKeyRanges. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| error
[vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| result
[query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -### ExecuteKeyspaceIds - -ExecuteKeyspaceIds executes the query based on the specified keyspace ids. - -#### Request - - ExecuteKeyspaceIdsRequest is the payload to ExecuteKeyspaceIds. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| keyspace
string| keyspace to target the query to. | -| keyspace_ids
list <bytes>| keyspace_ids contains the list of keyspace_ids affected by this query. Will be used to find the shards to send the query to. | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| not_in_transaction
bool| not_in_transaction is deprecated and should not be used. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Response - - ExecuteKeyspaceIdsResponse is the returned value from ExecuteKeyspaceIds. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| error
[vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| result
[query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -### StreamExecuteKeyRanges - -StreamExecuteKeyRanges executes a streaming query based on key ranges. Use this method if the query returns a large number of rows. - -#### Request - - StreamExecuteKeyRangesRequest is the payload to StreamExecuteKeyRanges. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| keyspace
string| keyspace to target the query to. | -| key_ranges
list <[topodata.KeyRange](#topodata.keyrange)>| KeyRange describes a range of sharding keys, when range-based sharding is used. | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Response - - StreamExecuteKeyRangesResponse is the returned value from StreamExecuteKeyRanges. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| result
[query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -### StreamExecuteKeyspaceIds - -StreamExecuteKeyspaceIds executes a streaming query based on keyspace ids. Use this method if the query returns a large number of rows. - -#### Request - - StreamExecuteKeyspaceIdsRequest is the payload to StreamExecuteKeyspaceIds. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| keyspace
string| keyspace to target the query to. | -| keyspace_ids
list <bytes>| keyspace_ids contains the list of keyspace_ids affected by this query. Will be used to find the shards to send the query to. | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Response - - StreamExecuteKeyspaceIdsResponse is the returned value from StreamExecuteKeyspaceIds. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| result
[query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -## Transactions -### Begin - -Begin a transaction. - -#### Request - - BeginRequest is the payload to Begin. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| single_db
bool| single_db specifies if the transaction should be restricted to a single database. | - -#### Response - - BeginResponse is the returned value from Begin. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | - -### Commit - -Commit a transaction. - -#### Request - - CommitRequest is the payload to Commit. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| atomic
bool| atomic specifies if the commit should go through the 2PC workflow to ensure atomicity. | - -#### Response - - CommitResponse is the returned value from Commit. - -##### Properties - -| Name |Description | -| :-------- | :-------- - -### ResolveTransaction - -ResolveTransaction resolves a transaction. - -#### Request - - ResolveTransactionRequest is the payload to ResolveTransaction. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| dtid
string| dtid is the dtid of the transaction to be resolved. | - -#### Response - - ResolveTransactionResponse is the returned value from Rollback. - -##### Properties - -| Name |Description | -| :-------- | :-------- - -### Rollback - -Rollback a transaction. - -#### Request - - RollbackRequest is the payload to Rollback. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | - -#### Response - - RollbackResponse is the returned value from Rollback. - -##### Properties - -| Name |Description | -| :-------- | :-------- - -## Custom Sharding -### ExecuteBatchShards - -ExecuteBatchShards executes the list of queries on the specified shards. - -#### Request - - ExecuteBatchShardsRequest is the payload to ExecuteBatchShards - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| queries
list <[BoundShardQuery](#boundshardquery)>| BoundShardQuery represents a single query request for the specified list of shards. This is used in a list for ExecuteBatchShardsRequest. | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| as_transaction
bool| as_transaction will execute the queries in this batch in a single transaction per shard, created for this purpose. (this can be seen as adding a 'begin' before and 'commit' after the queries). Only makes sense if tablet_type is master. If set, the Session is ignored. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Response - - ExecuteBatchShardsResponse is the returned value from ExecuteBatchShards. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| error
[vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| results
list <[query.QueryResult](#query.queryresult)>| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -### ExecuteShards - -ExecuteShards executes the query on the specified shards. - -#### Request - - ExecuteShardsRequest is the payload to ExecuteShards. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| keyspace
string| keyspace to target the query to. | -| shards
list <string>| shards to target the query to. A DML can only target one shard. | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| not_in_transaction
bool| not_in_transaction is deprecated and should not be used. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Response - - ExecuteShardsResponse is the returned value from ExecuteShards. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| error
[vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| result
[query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -### StreamExecuteShards - -StreamExecuteShards executes a streaming query based on shards. Use this method if the query returns a large number of rows. - -#### Request - - StreamExecuteShardsRequest is the payload to StreamExecuteShards. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| keyspace
string| keyspace to target the query to. | -| shards
list <string>| shards to target the query to. | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Response - - StreamExecuteShardsResponse is the returned value from StreamExecuteShards. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| result
[query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -## Map Reduce -### SplitQuery - -Split a query into non-overlapping sub queries - -#### Request - - SplitQueryRequest is the payload to SplitQuery. SplitQuery takes a "SELECT" query and generates a list of queries called "query-parts". Each query-part consists of the original query with an added WHERE clause that restricts the query-part to operate only on rows whose values in the the columns listed in the "split_column" field of the request (see below) are in a particular range. It is guaranteed that the set of rows obtained from executing each query-part on a database snapshot and merging (without deduping) the results is equal to the set of rows obtained from executing the original query on the same snapshot with the rows containing NULL values in any of the split_column's excluded. This is typically called by the MapReduce master when reading from Vitess. There it's desirable that the sets of rows returned by the query-parts have roughly the same size. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| keyspace
string| keyspace to target the query to. | -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| split_column
list <string>| Each generated query-part will be restricted to rows whose values in the columns listed in this field are in a particular range. The list of columns named here must be a prefix of the list of columns defining some index or primary key of the table referenced in 'query'. For many tables using the primary key columns (in order) is sufficient and this is the default if this field is omitted. See the comment on the 'algorithm' field for more restrictions and information. | -| split_count
int64| You can specify either an estimate of the number of query-parts to generate or an estimate of the number of rows each query-part should return. Thus, exactly one of split_count or num_rows_per_query_part should be nonzero. The non-given parameter is calculated from the given parameter using the formula: split_count * num_rows_per_query_pary = table_size, where table_size is an approximation of the number of rows in the table. Note that if "split_count" is given it is regarded as an estimate. The number of query-parts returned may differ slightly (in particular, if it's not a whole multiple of the number of vitess shards). | -| num_rows_per_query_part
int64| | -| algorithm
query.SplitQueryRequest.Algorithm| The algorithm to use to split the query. The split algorithm is performed on each database shard in parallel. The lists of query-parts generated by the shards are merged and returned to the caller. Two algorithms are supported: EQUAL_SPLITS If this algorithm is selected then only the first 'split_column' given is used (or the first primary key column if the 'split_column' field is empty). In the rest of this algorithm's description, we refer to this column as "the split column". The split column must have numeric type (integral or floating point). The algorithm works by taking the interval [min, max], where min and max are the minimum and maximum values of the split column in the table-shard, respectively, and partitioning it into 'split_count' sub-intervals of equal size. The added WHERE clause of each query-part restricts that part to rows whose value in the split column belongs to a particular sub-interval. This is fast, but requires that the distribution of values of the split column be uniform in [min, max] for the number of rows returned by each query part to be roughly the same. FULL_SCAN If this algorithm is used then the split_column must be the primary key columns (in order). This algorithm performs a full-scan of the table-shard referenced in 'query' to get "boundary" rows that are num_rows_per_query_part apart when the table is ordered by the columns listed in 'split_column'. It then restricts each query-part to the rows located between two successive boundary rows. This algorithm supports multiple split_column's of any type, but is slower than EQUAL_SPLITS. | -| use_split_query_v2
bool| Remove this field after this new server code is released to prod. We must keep it for now, so that clients can still send it to the old server code currently in production. | - -#### Response - - SplitQueryResponse is the returned value from SplitQuery. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| splits
list <[Part](#splitqueryresponse.part)>| splits contains the queries to run to fetch the entire data set. | - -#### Messages - -##### SplitQueryResponse.KeyRangePart - -Properties - -| Name |Description | -| :-------- | :-------- -| keyspace
string| keyspace to target the query to. | -| key_ranges
list <[topodata.KeyRange](#topodata.keyrange)>| KeyRange describes a range of sharding keys, when range-based sharding is used. | - -##### SplitQueryResponse.Part - -Properties - -| Name |Description | -| :-------- | :-------- -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| key_range_part
[KeyRangePart](#splitqueryresponse.keyrangepart)| key_range_part is set if the query should be executed by ExecuteKeyRanges. | -| shard_part
[ShardPart](#splitqueryresponse.shardpart)| shard_part is set if the query should be executed by ExecuteShards. | -| size
int64| size is the approximate number of rows this query will return. | - -##### SplitQueryResponse.ShardPart - -Properties - -| Name |Description | -| :-------- | :-------- -| keyspace
string| keyspace to target the query to. | -| shards
list <string>| shards to target the query to. | - -## Topology -### GetSrvKeyspace - -GetSrvKeyspace returns a SrvKeyspace object (as seen by this vtgate). This method is provided as a convenient way for clients to take a look at the sharding configuration for a Keyspace. Looking at the sharding information should not be used for routing queries (as the information may change, use the Execute calls for that). It is convenient for monitoring applications for instance, or if using custom sharding. - -#### Request - - GetSrvKeyspaceRequest is the payload to GetSrvKeyspace. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| keyspace
string| keyspace name to fetch. | - -#### Response - - GetSrvKeyspaceResponse is the returned value from GetSrvKeyspace. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| srv_keyspace
[topodata.SrvKeyspace](#topodata.srvkeyspace)| SrvKeyspace is a rollup node for the keyspace itself. | - -## v3 API (alpha) -### Execute - -Execute tries to route the query to the right shard. It depends on the query and bind variables to provide enough information in conjonction with the vindexes to route the query. - -#### Request - - ExecuteRequest is the payload to Execute. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| not_in_transaction
bool| not_in_transaction is deprecated and should not be used. | -| keyspace
string| keyspace to target the query to. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Response - - ExecuteResponse is the returned value from Execute. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| error
[vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | -| session
[Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | -| result
[query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -### StreamExecute - -StreamExecute executes a streaming query based on shards. It depends on the query and bind variables to provide enough information in conjonction with the vindexes to route the query. Use this method if the query returns a large number of rows. - -#### Request - - StreamExecuteRequest is the payload to StreamExecute. - -##### Parameters - -| Name |Description | -| :-------- | :-------- -| caller_id
[vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | -| keyspace
string| keyspace to target the query to. | -| options
[query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | - -#### Response - - StreamExecuteResponse is the returned value from StreamExecute. - -##### Properties - -| Name |Description | -| :-------- | :-------- -| result
[query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -## Enums - -### query.Type - - Type defines the various supported data types in bind vars and query results. - -| Name |Value |Description | -| :-------- | :-------- | :-------- -| NULL_TYPE | 0 | NULL_TYPE specifies a NULL type. | -| INT8 | 257 | INT8 specifies a TINYINT type. Properties: 1, IsNumber. | -| UINT8 | 770 | UINT8 specifies a TINYINT UNSIGNED type. Properties: 2, IsNumber, IsUnsigned. | -| INT16 | 259 | INT16 specifies a SMALLINT type. Properties: 3, IsNumber. | -| UINT16 | 772 | UINT16 specifies a SMALLINT UNSIGNED type. Properties: 4, IsNumber, IsUnsigned. | -| INT24 | 261 | INT24 specifies a MEDIUMINT type. Properties: 5, IsNumber. | -| UINT24 | 774 | UINT24 specifies a MEDIUMINT UNSIGNED type. Properties: 6, IsNumber, IsUnsigned. | -| INT32 | 263 | INT32 specifies a INTEGER type. Properties: 7, IsNumber. | -| UINT32 | 776 | UINT32 specifies a INTEGER UNSIGNED type. Properties: 8, IsNumber, IsUnsigned. | -| INT64 | 265 | INT64 specifies a BIGINT type. Properties: 9, IsNumber. | -| UINT64 | 778 | UINT64 specifies a BIGINT UNSIGNED type. Properties: 10, IsNumber, IsUnsigned. | -| FLOAT32 | 1035 | FLOAT32 specifies a FLOAT type. Properties: 11, IsFloat. | -| FLOAT64 | 1036 | FLOAT64 specifies a DOUBLE or REAL type. Properties: 12, IsFloat. | -| TIMESTAMP | 2061 | TIMESTAMP specifies a TIMESTAMP type. Properties: 13, IsQuoted. | -| DATE | 2062 | DATE specifies a DATE type. Properties: 14, IsQuoted. | -| TIME | 2063 | TIME specifies a TIME type. Properties: 15, IsQuoted. | -| DATETIME | 2064 | DATETIME specifies a DATETIME type. Properties: 16, IsQuoted. | -| YEAR | 785 | YEAR specifies a YEAR type. Properties: 17, IsNumber, IsUnsigned. | -| DECIMAL | 18 | DECIMAL specifies a DECIMAL or NUMERIC type. Properties: 18, None. | -| TEXT | 6163 | TEXT specifies a TEXT type. Properties: 19, IsQuoted, IsText. | -| BLOB | 10260 | BLOB specifies a BLOB type. Properties: 20, IsQuoted, IsBinary. | -| VARCHAR | 6165 | VARCHAR specifies a VARCHAR type. Properties: 21, IsQuoted, IsText. | -| VARBINARY | 10262 | VARBINARY specifies a VARBINARY type. Properties: 22, IsQuoted, IsBinary. | -| CHAR | 6167 | CHAR specifies a CHAR type. Properties: 23, IsQuoted, IsText. | -| BINARY | 10264 | BINARY specifies a BINARY type. Properties: 24, IsQuoted, IsBinary. | -| BIT | 2073 | BIT specifies a BIT type. Properties: 25, IsQuoted. | -| ENUM | 2074 | ENUM specifies an ENUM type. Properties: 26, IsQuoted. | -| SET | 2075 | SET specifies a SET type. Properties: 27, IsQuoted. | -| TUPLE | 28 | TUPLE specifies a a tuple. This cannot be returned in a QueryResult, but it can be sent as a bind var. Properties: 28, None. | -| GEOMETRY | 2077 | GEOMETRY specifies a GEOMETRY type. Properties: 29, IsQuoted. | -| JSON | 2078 | JSON specified a JSON type. Properties: 30, IsQuoted. | - -### topodata.KeyspaceIdType - - KeyspaceIdType describes the type of the sharding key for a range-based sharded keyspace. - -| Name |Value |Description | -| :-------- | :-------- | :-------- -| UNSET | 0 | UNSET is the default value, when range-based sharding is not used. | -| UINT64 | 1 | UINT64 is when uint64 value is used. This is represented as `UNSIGNED BIGINT` in MySQL | -| BYTES | 2 | BYTES is when an array of bytes is used. This is represented as `VARBINARY` in MySQL | - -### topodata.TabletType - - TabletType represents the type of a given tablet. - -| Name |Value |Description | -| :-------- | :-------- | :-------- -| UNKNOWN | 0 | UNKNOWN is not a valid value. | -| MASTER | 1 | MASTER is the master server for the shard. Only MASTER allows DMLs. | -| REPLICA | 2 | REPLICA is a slave type. It is used to serve live traffic. A REPLICA can be promoted to MASTER. A demoted MASTER will go to REPLICA. | -| RDONLY | 3 | RDONLY (old name) / BATCH (new name) is used to serve traffic for long-running jobs. It is a separate type from REPLICA so long-running queries don't affect web-like traffic. | -| BATCH | 3 | | -| SPARE | 4 | SPARE is a type of servers that cannot serve queries, but is available in case an extra server is needed. | -| EXPERIMENTAL | 5 | EXPERIMENTAL is like SPARE, except it can serve queries. This type can be used for usages not planned by Vitess, like online export to another storage engine. | -| BACKUP | 6 | BACKUP is the type a server goes to when taking a backup. No queries can be served in BACKUP mode. | -| RESTORE | 7 | RESTORE is the type a server uses when restoring a backup, at startup time. No queries can be served in RESTORE mode. | -| DRAINED | 8 | DRAINED is the type a server goes into when used by Vitess tools to perform an offline action. It is a serving type (as the tools processes may need to run queries), but it's not used to route queries from Vitess users. In this state, this tablet is dedicated to the process that uses it. | - -### vtrpc.ErrorCode - - ErrorCode is the enum values for Errors. Internally, errors should be created with one of these codes. These will then be translated over the wire by various RPC frameworks. - -| Name |Value |Description | -| :-------- | :-------- | :-------- -| SUCCESS | 0 | SUCCESS is returned from a successful call. | -| CANCELLED | 1 | CANCELLED means that the context was cancelled (and noticed in the app layer, as opposed to the RPC layer). | -| UNKNOWN_ERROR | 2 | UNKNOWN_ERROR includes: 1. MySQL error codes that we don't explicitly handle. 2. MySQL response that wasn't as expected. For example, we might expect a MySQL timestamp to be returned in a particular way, but it wasn't. 3. Anything else that doesn't fall into a different bucket. | -| BAD_INPUT | 3 | BAD_INPUT is returned when an end-user either sends SQL that couldn't be parsed correctly, or tries a query that isn't supported by Vitess. | -| DEADLINE_EXCEEDED | 4 | DEADLINE_EXCEEDED is returned when an action is taking longer than a given timeout. | -| INTEGRITY_ERROR | 5 | INTEGRITY_ERROR is returned on integrity error from MySQL, usually due to duplicate primary keys. | -| PERMISSION_DENIED | 6 | PERMISSION_DENIED errors are returned when a user requests access to something that they don't have permissions for. | -| RESOURCE_EXHAUSTED | 7 | RESOURCE_EXHAUSTED is returned when a query exceeds its quota in some dimension and can't be completed due to that. Queries that return RESOURCE_EXHAUSTED should not be retried, as it could be detrimental to the server's health. Examples of errors that will cause the RESOURCE_EXHAUSTED code: 1. TxPoolFull: this is retried server-side, and is only returned as an error if the server-side retries failed. 2. Query is killed due to it taking too long. | -| QUERY_NOT_SERVED | 8 | QUERY_NOT_SERVED means that a query could not be served right now. Client can interpret it as: "the tablet that you sent this query to cannot serve the query right now, try a different tablet or try again later." This could be due to various reasons: QueryService is not serving, should not be serving, wrong shard, wrong tablet type, blacklisted table, etc. Clients that receive this error should usually retry the query, but after taking the appropriate steps to make sure that the query will get sent to the correct tablet. | -| NOT_IN_TX | 9 | NOT_IN_TX means that we're not currently in a transaction, but we should be. | -| INTERNAL_ERROR | 10 | INTERNAL_ERRORs are problems that only the server can fix, not the client. These errors are not due to a query itself, but rather due to the state of the system. Generally, we don't expect the errors to go away by themselves, but they may go away after human intervention. Examples of scenarios where INTERNAL_ERROR is returned: 1. Something is not configured correctly internally. 2. A necessary resource is not available, and we don't expect it to become available by itself. 3. A sanity check fails. 4. Some other internal error occurs. Clients should not retry immediately, as there is little chance of success. However, it's acceptable for retries to happen internally, for example to multiple backends, in case only a subset of backend are not functional. | -| TRANSIENT_ERROR | 11 | TRANSIENT_ERROR is used for when there is some error that we expect we can recover from automatically - often due to a resource limit temporarily being reached. Retrying this error, with an exponential backoff, should succeed. Clients should be able to successfully retry the query on the same backends. Examples of things that can trigger this error: 1. Query has been throttled 2. VtGate could have request backlog | -| UNAUTHENTICATED | 12 | UNAUTHENTICATED errors are returned when a user requests access to something, and we're unable to verify the user's authentication. | - -## Messages - -### BoundKeyspaceIdQuery - -BoundKeyspaceIdQuery represents a single query request for the specified list of keyspace ids. This is used in a list for ExecuteBatchKeyspaceIdsRequest. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| keyspace
string| keyspace to target the query to. | -| keyspace_ids
list <bytes>| keyspace_ids contains the list of keyspace_ids affected by this query. Will be used to find the shards to send the query to. | - -### BoundShardQuery - -BoundShardQuery represents a single query request for the specified list of shards. This is used in a list for ExecuteBatchShardsRequest. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| query
[query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | -| keyspace
string| keyspace to target the query to. | -| shards
list <string>| shards to target the query to. A DML can only target one shard. | - -### Session - -Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| in_transaction
bool| | -| shard_sessions
list <[ShardSession](#session.shardsession)>| | -| single_db
bool| single_db specifies if the transaction should be restricted to a single database. | - -#### Messages - -##### Session.ShardSession - -Properties - -| Name |Description | -| :-------- | :-------- -| target
[query.Target](#query.target)| Target describes what the client expects the tablet is. If the tablet does not match, an error is returned. | -| transaction_id
int64| | - -### query.BindVariable - -BindVariable represents a single bind variable in a Query. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| type
[Type](#query.type)| | -| value
bytes| | -| values
list <[Value](#query.value)>| Value represents a typed value. | - -### query.BoundQuery - -BoundQuery is a query with its bind variables - -#### Properties - -| Name |Description | -| :-------- | :-------- -| sql
string| sql is the SQL query to execute | -| bind_variables
map <string, [BindVariable](#query.bindvariable)>| bind_variables is a map of all bind variables to expand in the query | - -### query.EventToken - -EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| timestamp
int64| timestamp is the MySQL timestamp of the statements. Seconds since Epoch. | -| shard
string| The shard name that applied the statements. Note this is not set when streaming from a vttablet. It is only used on the client -> vtgate link. | -| position
string| The position on the replication stream after this statement was applied. It is not the transaction ID / GTID, but the position / GTIDSet. | - -### query.ExecuteOptions - -ExecuteOptions is passed around for all Execute calls. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| include_event_token
bool| This used to be exclude_field_names, which was replaced by IncludedFields enum below If set, we will try to include an EventToken with the responses. | -| compare_event_token
[EventToken](#query.eventtoken)| EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. | -| included_fields
[IncludedFields](#executeoptions.includedfields)| Controls what fields are returned in Field message responses from MySQL, i.e. field name, table name, etc. This is an optimization for high-QPS queries where the client knows what it's getting | - -#### Enums - -##### ExecuteOptions.IncludedFields - -| Name |Value |Description | -| :-------- | :-------- | :-------- -| TYPE_AND_NAME | 0 | | -| TYPE_ONLY | 1 | | -| ALL | 2 | | - -### query.Field - -Field describes a single column returned by a query - -#### Properties - -| Name |Description | -| :-------- | :-------- -| name
string| name of the field as returned by mysql C API | -| type
[Type](#query.type)| vitess-defined type. Conversion function is in sqltypes package. | -| table
string| Remaining fields from mysql C API. These fields are only populated when ExecuteOptions.included_fields is set to IncludedFields.ALL. | -| org_table
string| | -| database
string| | -| org_name
string| | -| column_length
uint32| column_length is really a uint32. All 32 bits can be used. | -| charset
uint32| charset is actually a uint16. Only the lower 16 bits are used. | -| decimals
uint32| decimals is actualy a uint8. Only the lower 8 bits are used. | -| flags
uint32| flags is actually a uint16. Only the lower 16 bits are used. | - -### query.QueryResult - -QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). - -#### Properties - -| Name |Description | -| :-------- | :-------- -| fields
list <[Field](#query.field)>| Field describes a single column returned by a query | -| rows_affected
uint64| | -| insert_id
uint64| | -| rows
list <[Row](#query.row)>| Row is a database row. | -| extras
[ResultExtras](#query.resultextras)| ResultExtras contains optional out-of-band information. Usually the extras are requested by adding ExecuteOptions flags. | - -### query.ResultExtras - -ResultExtras contains optional out-of-band information. Usually the extras are requested by adding ExecuteOptions flags. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| event_token
[EventToken](#query.eventtoken)| EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. | -| fresher
bool| If set, it means the data returned with this result is fresher than the compare_token passed in the ExecuteOptions. | - -### query.ResultWithError - -ResultWithError represents a query response in the form of result or error but not both. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| error
[vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | -| result
[query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | - -### query.Row - -Row is a database row. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| lengths
list <sint64>| lengths contains the length of each value in values. A length of -1 means that the field is NULL. While reading values, you have to accummulate the length to know the offset where the next value begins in values. | -| values
bytes| values contains a concatenation of all values in the row. | - -### query.StreamEvent - -StreamEvent describes a set of transformations that happened as a single transactional unit on a server. It is streamed back by the Update Stream calls. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| statements
list <[Statement](#streamevent.statement)>| The statements in this transaction. | -| event_token
[EventToken](#query.eventtoken)| EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. | - -#### Messages - -##### StreamEvent.Statement - -One individual Statement in a transaction. - -Properties - -| Name |Description | -| :-------- | :-------- -| category
[Category](#streamevent.statement.category)| | -| table_name
string| table_name, primary_key_fields and primary_key_values are set for DML. | -| primary_key_fields
list <[Field](#query.field)>| Field describes a single column returned by a query | -| primary_key_values
list <[Row](#query.row)>| Row is a database row. | -| sql
bytes| sql is set for all queries. FIXME(alainjobart) we may not need it for DMLs. | - -#### Enums - -##### StreamEvent.Statement.Category - - One individual Statement in a transaction. The category of one statement. - -| Name |Value |Description | -| :-------- | :-------- | :-------- -| Error | 0 | | -| DML | 1 | | -| DDL | 2 | | - -### query.Target - -Target describes what the client expects the tablet is. If the tablet does not match, an error is returned. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| keyspace
string| | -| shard
string| | -| tablet_type
[topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | - -### query.Value - -Value represents a typed value. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| type
[Type](#query.type)| | -| value
bytes| | - -### topodata.KeyRange - -KeyRange describes a range of sharding keys, when range-based sharding is used. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| start
bytes| | -| end
bytes| | - -### topodata.ShardReference - -ShardReference is used as a pointer from a SrvKeyspace to a Shard - -#### Properties - -| Name |Description | -| :-------- | :-------- -| name
string| Copied from Shard. | -| key_range
[KeyRange](#topodata.keyrange)| KeyRange describes a range of sharding keys, when range-based sharding is used. | - -### topodata.SrvKeyspace - -SrvKeyspace is a rollup node for the keyspace itself. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| partitions
list <[KeyspacePartition](#srvkeyspace.keyspacepartition)>| The partitions this keyspace is serving, per tablet type. | -| sharding_column_name
string| copied from Keyspace | -| sharding_column_type
[KeyspaceIdType](#topodata.keyspaceidtype)| | -| served_from
list <[ServedFrom](#srvkeyspace.servedfrom)>| | - -#### Messages - -##### SrvKeyspace.KeyspacePartition - -Properties - -| Name |Description | -| :-------- | :-------- -| served_type
[TabletType](#topodata.tablettype)| The type this partition applies to. | -| shard_references
list <[ShardReference](#topodata.shardreference)>| ShardReference is used as a pointer from a SrvKeyspace to a Shard | - -##### SrvKeyspace.ServedFrom - -ServedFrom indicates a relationship between a TabletType and the keyspace name that's serving it. - -Properties - -| Name |Description | -| :-------- | :-------- -| tablet_type
[TabletType](#topodata.tablettype)| ServedFrom indicates a relationship between a TabletType and the keyspace name that's serving it. the tablet type | -| keyspace
string| the keyspace name that's serving it | - -### vtrpc.CallerID - -CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| principal
string| principal is the effective user identifier. It is usually filled in with whoever made the request to the appserver, if the request came from an automated job or another system component. If the request comes directly from the Internet, or if the Vitess client takes action on its own accord, it is okay for this field to be absent. | -| component
string| component describes the running process of the effective caller. It can for instance be the hostname:port of the servlet initiating the database call, or the container engine ID used by the servlet. | -| subcomponent
string| subcomponent describes a component inisde the immediate caller which is responsible for generating is request. Suggested values are a servlet name or an API endpoint name. | - -### vtrpc.RPCError - -RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. - -#### Properties - -| Name |Description | -| :-------- | :-------- -| code
[ErrorCode](#vtrpc.errorcode)| | -| message
string| | diff --git a/content/en/docs/reference/vtctl.md b/content/en/docs/reference/vtctl.md deleted file mode 100644 index 4a3956366..000000000 --- a/content/en/docs/reference/vtctl.md +++ /dev/null @@ -1,2644 +0,0 @@ ---- -title: vtctl Reference -noToc: true -weight: 9 ---- - -This reference guide explains the commands that the vtctl tool supports. **vtctl** is a command-line tool used to administer a Vitess cluster, and it allows a human or application to easily interact with a Vitess implementation. - -Commands are listed in the following groups: - -* [Cells](#cells) -* [Generic](#generic) -* [Keyspaces](#keyspaces) -* [Queries](#queries) -* [Replication Graph](#replication-graph) -* [Resharding Throttler](#resharding-throttler) -* [Schema, Version, Permissions](#schema-version-permissions) -* [Serving Graph](#serving-graph) -* [Shards](#shards) -* [Tablets](#tablets) -* [Topo](#topo) -* [Workflows](#workflows) - - -## Cells - -* [AddCellInfo](#addcellinfo) -* [DeleteCellInfo](#deletecellinfo) -* [GetCellInfo](#getcellinfo) -* [GetCellInfoNames](#getcellinfonames) -* [UpdateCellInfo](#updatecellinfo) -* [AddCellsAlias](#addcellsalias) -* [DeleteCellsAlias](#deletecellsalias) -* [UpdateCellsAlias](#updatecellsalias) -* [GetCellsAliases](#getcellsaliases) - -### AddCellInfo - -Registers a local topology service in a new cell by creating the CellInfo with the provided parameters. The address will be used to connect to the topology service, and we'll put Vitess data starting at the provided root. - -#### Example - -
AddCellInfo [-server_address <addr>] [-root <root>] <cell>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| root | string | The root path the topology service is using for that cell. | -| server_address | string | The address the topology service is using for that cell. | - - -#### Arguments - -* <addr> – Required. -* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. - -#### Errors - -* the <cell> argument is required for the <AddCellInfo> command This error occurs if the command is not called with exactly one argument. - - -### DeleteCellInfo - -Deletes the CellInfo for the provided cell. The cell cannot be referenced by any Shard record. - -#### Example - -
DeleteCellInfo <cell>
- -#### Errors - -* the <cell> argument is required for the <DeleteCellInfo> command This error occurs if the command is not called with exactly one argument. - - -### GetCellInfo - -Prints a JSON representation of the CellInfo for a cell. - -#### Example - -
GetCellInfo <cell>
- -#### Errors - -* the <cell> argument is required for the <GetCellInfo> command This error occurs if the command is not called with exactly one argument. - - -### GetCellInfoNames - -Lists all the cells for which we have a CellInfo object, meaning we have a local topology service registered. - -#### Example - -
GetCellInfoNames
- -#### Errors - -* <GetCellInfoNames> command takes no parameter This error occurs if the command is not called with exactly 0 arguments. - - -### UpdateCellInfo - -Updates the content of a CellInfo with the provided parameters. If a value is empty, it is not updated. The CellInfo will be created if it doesn't exist. - -#### Example - -
UpdateCellInfo [-server_address <addr>] [-root <root>] <cell>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| root | string | The root path the topology service is using for that cell. | -| server_address | string | The address the topology service is using for that cell. | - - -#### Arguments - -* <addr> – Required. -* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. - -#### Errors - -* the <cell> argument is required for the <UpdateCellInfo> command This error occurs if the command is not called with exactly one argument. - -### AddCellsAlias - -Defines a group of cells within which replica/rdonly traffic can be routed across cells. By default, Vitess does not allow traffic between replicas that are part of different cells. Between cells that are not in the same group (alias), only master traffic can be routed. - - -#### Example - -
AddCellsAlias [-cells <cell1,cell2,cell3>] <alias>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string | The list of cell names that are members of this alias. | - - -#### Arguments - -* <alias> – Required. Alias name for this grouping. - -#### Errors - -* the <alias> argument is required for the <AddCellsAlias> command This error occurs if the command is not called with exactly one argument. - -### DeleteCellsAlias - -Deletes the CellsAlias for the provided alias. After deleting an alias, cells that were part of the group are not going to be able to route replica/rdonly traffic to the rest of the cells that were part of the grouping. - -#### Example - -
DeleteCellsAlias <alias>
- -#### Errors - -* the <alias> argument is required for the <DeleteCellsAlias> command This error occurs if the command is not called with exactly one argument. - -### UpdateCellsAlias - -Updates the content of a CellAlias with the provided parameters. Empty values and intersections with other aliases are not supported. - -#### Example - -
UpdateCellsAliases [-cells <cell1,cell2,cell3>] <alias>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string |The list of cell names that are members of this alias. | - - -#### Arguments - -* <alias> – Required. Alias name group to update. - -#### Errors - -* the <alias> argument is required for the <UpdateCellsAlias> command This error occurs if the command is not called with exactly one argument. - -### GetCellsAliases - -Fetches in json format all the existent cells alias groups. - -#### Example - -
GetCellsAliases
- -## Generic - -* [ListAllTablets](#listalltablets) -* [ListTablets](#listtablets) -* [Validate](#validate) - -### ListAllTablets - -Lists all tablets in an awk-friendly way. - -#### Example - -
ListAllTablets <cell name>
- -#### Arguments - -* <cell name> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. - -#### Errors - -* the <cell name> argument is required for the <ListAllTablets> command This error occurs if the command is not called with exactly one argument. - - -### ListTablets - -Lists specified tablets in an awk-friendly way. - -#### Example - -
ListTablets <tablet alias> ...
- -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space. - -#### Errors - -* the <tablet alias> argument is required for the <ListTablets> command This error occurs if the command is not called with at least one argument. - - -### Validate - -Validates that all nodes reachable from the global replication graph and that all tablets in all discoverable cells are consistent. - -#### Example - -
Validate [-ping-tablets]
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process | - - - - -## Keyspaces - -* [CreateKeyspace](#createkeyspace) -* [DeleteKeyspace](#deletekeyspace) -* [FindAllShardsInKeyspace](#findallshardsinkeyspace) -* [GetKeyspace](#getkeyspace) -* [GetKeyspaces](#getkeyspaces) -* [MigrateServedFrom](#migrateservedfrom) -* [MigrateServedTypes](#migrateservedtypes) -* [CancelResharding](#cancelresharding) -* [ShowResharding](#showresharding) -* [RebuildKeyspaceGraph](#rebuildkeyspacegraph) -* [RemoveKeyspaceCell](#removekeyspacecell) -* [SetKeyspaceServedFrom](#setkeyspaceservedfrom) -* [SetKeyspaceShardingInfo](#setkeyspaceshardinginfo) -* [ValidateKeyspace](#validatekeyspace) -* [WaitForDrain](#waitfordrain) - -### CreateKeyspace - -Creates the specified keyspace. - -#### Example - -
CreateKeyspace [-sharding_column_name=name] [-sharding_column_type=type] [-served_from=tablettype1:ks1,tablettype2,ks2,...] [-force] <keyspace name>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| force | Boolean | Proceeds even if the keyspace already exists | -| served_from | string | Specifies a comma-separated list of dbtype:keyspace pairs used to serve traffic | -| sharding_column_name | string | Specifies the column to use for sharding operations | -| sharding_column_type | string | Specifies the type of the column to use for sharding operations | - - -#### 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 <CreateKeyspace> command This error occurs if the command is not called with exactly one argument. - - -### DeleteKeyspace - -Deletes the specified keyspace. In recursive mode, it also recursively deletes all shards in the keyspace. Otherwise, there must be no shards left in the keyspace. - -#### Example - -
DeleteKeyspace [-recursive] <keyspace>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| recursive | Boolean | Also recursively delete all shards in the 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 - -* must specify the <keyspace> argument for <DeleteKeyspace> This error occurs if the command is not called with exactly one argument. - - -### FindAllShardsInKeyspace - -Displays all of the shards in the specified keyspace. - -#### Example - -
FindAllShardsInKeyspace <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 <FindAllShardsInKeyspace> command This error occurs if the command is not called with exactly one argument. - - -### GetKeyspace - -Outputs a JSON structure that contains information about the Keyspace. - -#### Example - -
GetKeyspace <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 <GetKeyspace> command This error occurs if the command is not called with exactly one argument. - - -### GetKeyspaces - -Outputs a sorted list of all keyspaces. - - -### MigrateServedFrom - -Makes the <destination keyspace/shard> serve the given type. This command also rebuilds the serving graph. - -#### Example - -
MigrateServedFrom [-cells=c1,c2,...] [-reverse] <destination keyspace/shard> <served tablet type>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string | Specifies a comma-separated list of cells to update | -| filtered_replication_wait_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations | -| reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble | - - -#### Arguments - -* <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>. -* <served tablet type> – Required. The vttablet's role. Valid values are: - - * backup – A slaved copy of data that is offline to queries other than for backup purposes - * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) - * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. - * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. - * master – A primary copy of data - * rdonly – A slaved copy of data for OLAP load patterns - * replica – A slaved copy of data ready to be promoted to master - * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. - * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. - * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. - - - - -#### Errors - -* the <destination keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedFrom> command This error occurs if the command is not called with exactly 2 arguments. - - -### MigrateServedTypes - -Migrates a serving type from the source shard to the shards that it replicates to. This command also rebuilds the serving graph. The <keyspace/shard> argument can specify any of the shards involved in the migration. - -#### Example - -
MigrateServedTypes [-cells=c1,c2,...] [-reverse] [-skip-refresh-state] <keyspace/shard> <served tablet type>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string | Specifies a comma-separated list of cells to update | -| filtered\_replication\_wait\_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations | -| reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble | -| skip-refresh-state | Boolean | Skips refreshing the state of the source tablets after the migration, meaning that the refresh will need to be done manually, replica and rdonly only) | -| reverse\_replication | Boolean | For master migration, enabling this flag reverses replication which allows you to rollback | - - -#### 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>. -* <served tablet type> – Required. The vttablet's role. Valid values are: - - * backup – A slaved copy of data that is offline to queries other than for backup purposes - * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) - * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. - * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. - * master – A primary copy of data - * rdonly – A slaved copy of data for OLAP load patterns - * replica – A slaved copy of data ready to be promoted to master - * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. - * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. - * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. - - - - -#### Errors - -* the <source keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedTypes> command This error occurs if the command is not called with exactly 2 arguments. -* the <skip-refresh-state> flag can only be specified for non-master migrations - - -### CancelResharding - -Permanently cancels a resharding in progress. All resharding related metadata will be deleted. - -#### 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>. - - -### ShowResharding - -"Displays all metadata about a resharding in progress. - -#### 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>. - - -### RebuildKeyspaceGraph - -Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients. - -#### Example - -
RebuildKeyspaceGraph [-cells=c1,c2,...] <keyspace> ...
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string | Specifies a comma-separated list of cells to update | - - -#### 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. To specify multiple values for this argument, separate individual values with a space. - -#### Errors - -* the <keyspace> argument must be used to specify at least one keyspace when calling the <RebuildKeyspaceGraph> command This error occurs if the command is not called with at least one argument. - - -### RemoveKeyspaceCell - -Removes the cell from the Cells list for all shards in the keyspace, and the SrvKeyspace for that keyspace in that cell. - -#### Example - -
RemoveKeyspaceCell [-force] [-recursive] <keyspace> <cell>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| force | Boolean | Proceeds even if the cell's topology service cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. | -| recursive | Boolean | Also delete all tablets in that cell belonging to the specified 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. -* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. - -#### Errors - -* the <keyspace> and <cell> arguments are required for the <RemoveKeyspaceCell> command This error occurs if the command is not called with exactly 2 arguments. - - -### SetKeyspaceServedFrom - -Changes the ServedFromMap manually. This command is intended for emergency fixes. This field is automatically set when you call the *MigrateServedFrom* command. This command does not rebuild the serving graph. - -#### Example - -
SetKeyspaceServedFrom [-source=<source keyspace name>] [-remove] [-cells=c1,c2,...] <keyspace name> <tablet type>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string | Specifies a comma-separated list of cells to affect | -| remove | Boolean | Indicates whether to add (default) or remove the served from record | -| source | string | Specifies the source 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. -* <tablet type> – Required. The vttablet's role. Valid values are: - - * backup – A slaved copy of data that is offline to queries other than for backup purposes - * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) - * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. - * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. - * master – A primary copy of data - * rdonly – A slaved copy of data for OLAP load patterns - * replica – A slaved copy of data ready to be promoted to master - * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. - * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. - * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. - - - - -#### Errors - -* the <keyspace name> and <tablet type> arguments are required for the <SetKeyspaceServedFrom> command This error occurs if the command is not called with exactly 2 arguments. - - -### SetKeyspaceShardingInfo - -Updates the sharding information for a keyspace. - -#### Example - -
SetKeyspaceShardingInfo [-force] <keyspace name> [<column name>] [<column type>]
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| force | Boolean | Updates fields even if they are already set. Use caution before calling this command. | - - -#### 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. -* <column name> – Optional. -* <column type> – Optional. - -#### Errors - -* the <keyspace name> argument is required for the <SetKeyspaceShardingInfo> command. The <column name> and <column type> arguments are both optional This error occurs if the command is not called with between 1 and 3 arguments. -* both <column name> and <column type> must be set, or both must be unset - - -### ValidateKeyspace - -Validates that all nodes reachable from the specified keyspace are consistent. - -#### Example - -
ValidateKeyspace [-ping-tablets] <keyspace name>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| ping-tablets | Boolean | Specifies whether all tablets will be pinged during the validation process | - - -#### 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 <ValidateKeyspace> command This error occurs if the command is not called with exactly one argument. - - -### WaitForDrain - -Blocks until no new queries were observed on all tablets with the given tablet type in the specified keyspace. This can be used as sanity check to ensure that the tablets were drained after running vtctl MigrateServedTypes and vtgate is no longer using them. If -timeout is set, it fails when the timeout is reached. - -#### Example - -
WaitForDrain [-timeout <duration>] [-retry_delay <duration>] [-initial_wait <duration>] <keyspace/shard> <served tablet type>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string | Specifies a comma-separated list of cells to look for tablets | -| initial_wait | Duration | Time to wait for all tablets to check in | -| retry_delay | Duration | Time to wait between two checks | -| timeout | Duration | Timeout after which the command fails | - - -#### 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>. -* <served tablet type> – Required. The vttablet's role. Valid values are: - - * backup – A slaved copy of data that is offline to queries other than for backup purposes - * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) - * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. - * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. - * master – A primary copy of data - * rdonly – A slaved copy of data for OLAP load patterns - * replica – A slaved copy of data ready to be promoted to master - * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. - * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. - * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. - - - - -#### Errors - -* the <keyspace/shard> and <tablet type> arguments are both required for the <WaitForDrain> command This error occurs if the command is not called with exactly 2 arguments. - - -## Queries - -* [VtGateExecute](#vtgateexecute) -* [VtGateExecuteKeyspaceIds](#vtgateexecutekeyspaceids) -* [VtGateExecuteShards](#vtgateexecuteshards) -* [VtGateSplitQuery](#vtgatesplitquery) -* [VtTabletBegin](#vttabletbegin) -* [VtTabletCommit](#vttabletcommit) -* [VtTabletExecute](#vttabletexecute) -* [VtTabletRollback](#vttabletrollback) -* [VtTabletStreamHealth](#vttabletstreamhealth) -* [VtTabletUpdateStream](#vttabletupdatestream) - -### VtGateExecute - -Executes the given SQL query with the provided bound variables against the vtgate server. - -#### Example - -
VtGateExecute -server <vtgate> [-bind_variables <JSON map>] [-keyspace <default keyspace>] [-tablet_type <tablet type>] [-options <proto text options>] [-json] <sql>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| json | Boolean | Output JSON instead of human-readable table | -| options | string | execute options values as a text encoded proto of the ExecuteOptions structure | -| server | string | VtGate server to connect to | -| target | string | keyspace:shard@tablet_type | - - -#### Arguments - -* <vtgate> – Required. -* <sql> – Required. - -#### Errors - -* the <sql> argument is required for the <VtGateExecute> command This error occurs if the command is not called with exactly one argument. -* query commands are disabled (set the -enable_queries flag to enable) -* error connecting to vtgate '%v': %v -* Execute failed: %v - - -### VtGateExecuteKeyspaceIds - -Executes the given SQL query with the provided bound variables against the vtgate server. It is routed to the shards that contain the provided keyspace ids. - -#### Example - -
VtGateExecuteKeyspaceIds -server <vtgate> -keyspace <keyspace> -keyspace_ids <ks1 in hex>,<k2 in hex>,... [-bind_variables <JSON map>] [-tablet_type <tablet type>] [-options <proto text options>] [-json] <sql>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| json | Boolean | Output JSON instead of human-readable table | -| keyspace | string | keyspace to send query to | -| keyspace_ids | string | comma-separated list of keyspace ids (in hex) that will map into shards to send query to | -| options | string | execute options values as a text encoded proto of the ExecuteOptions structure | -| server | string | VtGate server to connect to | -| tablet_type | string | tablet type to query | - - -#### Arguments - -* <vtgate> – Required. -* <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. -* <ks1 in hex> – Required. To specify multiple values for this argument, separate individual values with a comma. -* <sql> – Required. - -#### Errors - -* the <sql> argument is required for the <VtGateExecuteKeyspaceIds> command This error occurs if the command is not called with exactly one argument. -* query commands are disabled (set the -enable_queries flag to enable) -* cannot hex-decode value %v '%v': %v -* error connecting to vtgate '%v': %v -* Execute failed: %v - - -### VtGateExecuteShards - -Executes the given SQL query with the provided bound variables against the vtgate server. It is routed to the provided shards. - -#### Example - -
VtGateExecuteShards -server <vtgate> -keyspace <keyspace> -shards <shard0>,<shard1>,... [-bind_variables <JSON map>] [-tablet_type <tablet type>] [-options <proto text options>] [-json] <sql>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| json | Boolean | Output JSON instead of human-readable table | -| keyspace | string | keyspace to send query to | -| options | string | execute options values as a text encoded proto of the ExecuteOptions structure | -| server | string | VtGate server to connect to | -| shards | string | comma-separated list of shards to send query to | -| tablet_type | string | tablet type to query | - - -#### Arguments - -* <vtgate> – Required. -* <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. -* <shard> – Required. The name of a shard. The argument value is typically in the format <range start>-<range end>. To specify multiple values for this argument, separate individual values with a comma. -* <sql> – Required. - -#### Errors - -* the <sql> argument is required for the <VtGateExecuteShards> command This error occurs if the command is not called with exactly one argument. -* query commands are disabled (set the -enable_queries flag to enable) -* error connecting to vtgate '%v': %v -* Execute failed: %v - - -### VtGateSplitQuery - -Executes the SplitQuery computation for the given SQL query with the provided bound variables against the vtgate server (this is the base query for Map-Reduce workloads, and is provided here for debug / test purposes). - -#### Example - -
VtGateSplitQuery -server <vtgate> -keyspace <keyspace> [-split_column <split_column>] -split_count <split_count> [-bind_variables <JSON map>] <sql>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| algorithm | string | The algorithm to | -| keyspace | string | keyspace to send query to | -| server | string | VtGate server to connect to | -| split_count | Int64 | number of splits to generate. | - - -#### Arguments - -* <vtgate> – Required. -* <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. -* <split_count> – Required. -* <sql> – Required. - -#### Errors - -* the <sql> argument is required for the <VtGateSplitQuery> command This error occurs if the command is not called with exactly one argument. -* query commands are disabled (set the -enable_queries flag to enable) -* Exactly one of <split_count> or num_rows_per_query_part -* Unknown split-query <algorithm>: %v -* error connecting to vtgate '%v': %v -* Execute failed: %v -* SplitQuery failed: %v - - -### VtTabletBegin - -Starts a transaction on the provided server. - -#### Example - -
VtTabletBegin [-username <TableACL user>] <tablet alias>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | - - -#### Arguments - -* <TableACL user> – Required. -* <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 <VtTabletBegin> command This error occurs if the command is not called with exactly one argument. -* query commands are disabled (set the -enable_queries flag to enable) -* cannot connect to tablet %v: %v -* Begin failed: %v - - -### VtTabletCommit - -Commits the given transaction on the provided server. - -#### Example - -
VtTabletCommit [-username <TableACL user>] <transaction_id>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | - - -#### Arguments - -* <TableACL user> – Required. -* <transaction_id> – Required. - -#### Errors - -* the <tablet_alias> and <transaction_id> arguments are required for the <VtTabletCommit> command This error occurs if the command is not called with exactly 2 arguments. -* query commands are disabled (set the -enable_queries flag to enable) -* cannot connect to tablet %v: %v - - -### VtTabletExecute - -Executes the given query on the given tablet. -transaction_id is optional. Use VtTabletBegin to start a transaction. - -#### Example - -
VtTabletExecute [-username <TableACL user>] [-transaction_id <transaction_id>] [-options <proto text options>] [-json] <tablet alias> <sql>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| json | Boolean | Output JSON instead of human-readable table | -| options | string | execute options values as a text encoded proto of the ExecuteOptions structure | -| transaction_id | Int | transaction id to use, if inside a transaction. | -| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | - - -#### Arguments - -* <TableACL user> – Required. -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. -* <sql> – Required. - -#### Errors - -* the <tablet_alias> and <sql> arguments are required for the <VtTabletExecute> command This error occurs if the command is not called with exactly 2 arguments. -* query commands are disabled (set the -enable_queries flag to enable) -* cannot connect to tablet %v: %v -* Execute failed: %v - - -### VtTabletRollback - -Rollbacks the given transaction on the provided server. - -#### Example - -
VtTabletRollback [-username <TableACL user>] <tablet alias> <transaction_id>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | - - -#### Arguments - -* <TableACL user> – Required. -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. -* <transaction_id> – Required. - -#### Errors - -* the <tablet_alias> and <transaction_id> arguments are required for the <VtTabletRollback> command This error occurs if the command is not called with exactly 2 arguments. -* query commands are disabled (set the -enable_queries flag to enable) -* cannot connect to tablet %v: %v - - -### VtTabletStreamHealth - -Executes the StreamHealth streaming query to a vttablet process. Will stop after getting <count> answers. - -#### Example - -
VtTabletStreamHealth [-count <count, default 1>] <tablet alias>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| count | Int | number of responses to wait for | - - -#### Arguments - -* <count default 1> – Required. -* <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 <VtTabletStreamHealth> command This error occurs if the command is not called with exactly one argument. -* query commands are disabled (set the -enable_queries flag to enable) -* cannot connect to tablet %v: %v - - -### VtTabletUpdateStream - -Executes the UpdateStream streaming query to a vttablet process. Will stop after getting <count> answers. - -#### Example - -
VtTabletUpdateStream [-count <count, default 1>] [-position <position>] [-timestamp <timestamp>] <tablet alias>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| count | Int | number of responses to wait for | -| position | string | position to start the stream from | -| timestamp | Int | timestamp to start the stream from | - - -#### Arguments - -* <count default 1> – Required. -* <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 <VtTabletUpdateStream> command This error occurs if the command is not called with exactly one argument. -* query commands are disabled (set the -enable_queries flag to enable) -* cannot connect to tablet %v: %v - - -## Replication Graph - -* [GetShardReplication](#getshardreplication) - -### GetShardReplication - -Outputs a JSON structure that contains information about the ShardReplication. - -#### Example - -
GetShardReplication <cell> <keyspace/shard>
- -#### Arguments - -* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. -* <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 <cell> and <keyspace/shard> arguments are required for the <GetShardReplication> command This error occurs if the command is not called with exactly 2 arguments. - - -## Resharding Throttler - -* [GetThrottlerConfiguration](#getthrottlerconfiguration) -* [ResetThrottlerConfiguration](#resetthrottlerconfiguration) -* [ThrottlerMaxRates](#throttlermaxrates) -* [ThrottlerSetMaxRate](#throttlersetmaxrate) -* [UpdateThrottlerConfiguration](#updatethrottlerconfiguration) - -### GetThrottlerConfiguration - -Returns the current configuration of the MaxReplicationLag module. If no throttler name is specified, the configuration of all throttlers will be returned. - -#### Example - -
GetThrottlerConfiguration -server <vtworker or vttablet> [<throttler name>]
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| server | string | vtworker or vttablet to connect to | - - -#### Arguments - -* <vtworker or vttablet> – Required. -* <throttler name> – Optional. - -#### Errors - -* the <GetThrottlerConfiguration> command accepts only <throttler name> as optional positional parameter This error occurs if the command is not called with more than 1 arguments. -* error creating a throttler client for <server> '%v': %v -* failed to get the throttler configuration from <server> '%v': %v - - -### ResetThrottlerConfiguration - -Resets the current configuration of the MaxReplicationLag module. If no throttler name is specified, the configuration of all throttlers will be reset. - -#### Example - -
ResetThrottlerConfiguration -server <vtworker or vttablet> [<throttler name>]
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| server | string | vtworker or vttablet to connect to | - - -#### Arguments - -* <vtworker or vttablet> – Required. -* <throttler name> – Optional. - -#### Errors - -* the <ResetThrottlerConfiguration> command accepts only <throttler name> as optional positional parameter This error occurs if the command is not called with more than 1 arguments. -* error creating a throttler client for <server> '%v': %v -* failed to get the throttler configuration from <server> '%v': %v - - -### ThrottlerMaxRates - -Returns the current max rate of all active resharding throttlers on the server. - -#### Example - -
ThrottlerMaxRates -server <vtworker or vttablet>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| server | string | vtworker or vttablet to connect to | - - -#### Arguments - -* <vtworker or vttablet> – Required. - -#### Errors - -* the ThrottlerSetMaxRate command does not accept any positional parameters This error occurs if the command is not called with exactly 0 arguments. -* error creating a throttler client for <server> '%v': %v -* failed to get the throttler rate from <server> '%v': %v - - -### ThrottlerSetMaxRate - -Sets the max rate for all active resharding throttlers on the server. - -#### Example - -
ThrottlerSetMaxRate -server <vtworker or vttablet> <rate>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| server | string | vtworker or vttablet to connect to | - - -#### Arguments - -* <vtworker or vttablet> – Required. -* <rate> – Required. - -#### Errors - -* the <rate> argument is required for the <ThrottlerSetMaxRate> command This error occurs if the command is not called with exactly one argument. -* failed to parse rate '%v' as integer value: %v -* error creating a throttler client for <server> '%v': %v -* failed to set the throttler rate on <server> '%v': %v - - -### UpdateThrottlerConfiguration - -Updates the configuration of the MaxReplicationLag module. The configuration must be specified as protobuf text. If a field is omitted or has a zero value, it will be ignored unless -copy_zero_values is specified. If no throttler name is specified, all throttlers will be updated. - -#### Example - -
UpdateThrottlerConfiguration `-server <vtworker or vttablet> [-copy_zero_values] "<configuration protobuf text>" [<throttler name>]`
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| copy_zero_values | Boolean | If true, fields with zero values will be copied as well | -| server | string | vtworker or vttablet to connect to | - - -#### Arguments - -* <vtworker or vttablet> – Required. -* <throttler name> – Optional. - -#### Errors - -* Failed to unmarshal the configuration protobuf text (%v) into a protobuf instance: %v -* error creating a throttler client for <server> '%v': %v -* failed to update the throttler configuration on <server> '%v': %v - - -## Schema, Version, Permissions - -* [ApplySchema](#applyschema) -* [ApplyVSchema](#applyvschema) -* [CopySchemaShard](#copyschemashard) -* [GetPermissions](#getpermissions) -* [GetSchema](#getschema) -* [GetVSchema](#getvschema) -* [RebuildVSchemaGraph](#rebuildvschemagraph) -* [ReloadSchema](#reloadschema) -* [ReloadSchemaKeyspace](#reloadschemakeyspace) -* [ReloadSchemaShard](#reloadschemashard) -* [ValidatePermissionsKeyspace](#validatepermissionskeyspace) -* [ValidatePermissionsShard](#validatepermissionsshard) -* [ValidateSchemaKeyspace](#validateschemakeyspace) -* [ValidateSchemaShard](#validateschemashard) -* [ValidateVersionKeyspace](#validateversionkeyspace) -* [ValidateVersionShard](#validateversionshard) - -### ApplySchema - -Applies the schema change to the specified keyspace on every master, running in parallel on all shards. The changes are then propagated to slaves 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. - -#### Example - -
ApplySchema [-allow_long_unavailability] [-wait_slave_timeout=10s] {-sql=<sql> || -sql-file=<filename>} <keyspace>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| allow_long_unavailability | Boolean | Allow large schema changes which incur a longer unavailability of the database. | -| sql | string | A list of semicolon-delimited SQL commands | -| sql-file | string | Identifies the file that contains the SQL commands | -| wait_slave_timeout | Duration | The amount of time to wait for slaves to receive the schema change via replication. | - - -#### 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. - - -### ApplyVSchema - -Applies the VTGate routing schema to the provided keyspace. Shows the result after application. - -#### Example - -
ApplyVSchema {-vschema=<vschema> || -vschema_file=<vschema file>} [-cells=c1,c2,...] [-skip_rebuild] <keyspace>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string | If specified, limits the rebuild to the cells, after upload. Ignored if skipRebuild is set. | -| skip_rebuild | Boolean | If set, do no rebuild the SrvSchema objects. | -| vschema | string | Identifies the VTGate routing schema | -| vschema_file | string | Identifies 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 - - -### CopySchemaShard - -Copies the schema from a source shard's master (or a specific tablet) to a destination shard. The schema is applied directly on the master 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_slave_timeout=10s] {<source keyspace/shard> || <source tablet alias>} <destination keyspace/shard>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | -| include-views | Boolean | Includes views in the output | -| tables | string | Specifies a comma-separated list of tables to copy. Each is either an exact match, or a regular expression of the form /regexp/ | -| wait_slave_timeout | Duration | The amount of time to wait for slaves to receive the schema change via replication. | - - -#### Arguments - -* <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. - - -### 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. - - -### 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 - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | -| include-views | Boolean | Includes views in the output | -| table_names_only | Boolean | Only displays table names that match | -| tables | string | Specifies 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. - - -### 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. - - -### 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 - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string | Specifies 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. - - -### 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. - - -### ReloadSchemaKeyspace - -Reloads the schema on all the tablets in a keyspace. - -#### Example - -
ReloadSchemaKeyspace [-concurrency=10] [-include_master=false] <keyspace>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| concurrency | Int | How many tablets to reload in parallel | -| include_master | Boolean | Include the master 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. - - -### ReloadSchemaShard - -Reloads the schema on all the tablets in a shard. - -#### Example - -
ReloadSchemaShard [-concurrency=10] [-include_master=false] <keyspace/shard>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| concurrency | Int | How many tablets to reload in parallel | -| include_master | Boolean | Include the master 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. - - -### ValidatePermissionsKeyspace - -Validates that the master permissions from 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. - - -### ValidatePermissionsShard - -Validates that the master permissions match all the slaves. - -#### 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. - - -### ValidateSchemaKeyspace - -Validates that the master schema from shard 0 matches the schema on all of the other tablets in the keyspace. - -#### Example - -
ValidateSchemaKeyspace [-exclude_tables=''] [-include-views] <keyspace name>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | -| include-views | Boolean | Includes 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. - - -### ValidateSchemaShard - -Validates that the master schema matches all of the slaves. - -#### Example - -
ValidateSchemaShard [-exclude_tables=''] [-include-views] <keyspace/shard>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | -| include-views | Boolean | Includes 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. - - -### ValidateVersionKeyspace - -Validates that the master version from 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. - - -### ValidateVersionShard - -Validates that the master version matches all of the slaves. - -#### 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. - - -## Serving Graph - -* [GetSrvKeyspace](#getsrvkeyspace) -* [GetSrvKeyspaceNames](#getsrvkeyspacenames) -* [GetSrvVSchema](#getsrvvschema) - -### GetSrvKeyspace - -Outputs a JSON structure that contains information about the SrvKeyspace. - -#### Example - -
GetSrvKeyspace <cell> <keyspace>
- -#### Arguments - -* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. -* <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 <cell> and <keyspace> arguments are required for the <GetSrvKeyspace> command This error occurs if the command is not called with exactly 2 arguments. - - -### GetSrvKeyspaceNames - -Outputs a list of keyspace names. - -#### Example - -
GetSrvKeyspaceNames <cell>
- -#### Arguments - -* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. - -#### Errors - -* the <cell> argument is required for the <GetSrvKeyspaceNames> command This error occurs if the command is not called with exactly one argument. - - -### GetSrvVSchema - -Outputs a JSON structure that contains information about the SrvVSchema. - -#### Example - -
GetSrvVSchema <cell>
- -#### Arguments - -* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. - -#### Errors - -* the <cell> argument is required for the <GetSrvVSchema> command This error occurs if the command is not called with exactly one argument. - - -## Shards - -* [CreateShard](#createshard) -* [DeleteShard](#deleteshard) -* [EmergencyReparentShard](#emergencyreparentshard) -* [GetShard](#getshard) -* [InitShardMaster](#initshardmaster) -* [ListBackups](#listbackups) -* [ListShardTablets](#listshardtablets) -* [PlannedReparentShard](#plannedreparentshard) -* [RemoveBackup](#removebackup) -* [RemoveShardCell](#removeshardcell) -* [SetShardServedTypes](#setshardservedtypes) -* [SetShardTabletControl](#setshardtabletcontrol) -* [ShardReplicationFix](#shardreplicationfix) -* [ShardReplicationPositions](#shardreplicationpositions) -* [SourceShardAdd](#sourceshardadd) -* [SourceShardDelete](#sourcesharddelete) -* [TabletExternallyReparented](#tabletexternallyreparented) -* [ValidateShard](#validateshard) -* [WaitForFilteredReplication](#waitforfilteredreplication) - -### CreateShard - -Creates the specified shard. - -#### Example - -
CreateShard [-force] [-parent] <keyspace/shard>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| force | Boolean | Proceeds with the command even if the keyspace already exists | -| parent | Boolean | Creates the parent keyspace if it doesn't already exist | - - -#### 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 <CreateShard> command This error occurs if the command is not called with exactly one argument. - - -### DeleteShard - -Deletes the specified shard(s). In recursive mode, it also deletes all tablets belonging to the shard. Otherwise, there must be no tablets left in the shard. - -#### Example - -
DeleteShard [-recursive] [-even_if_serving] <keyspace/shard> ...
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| even_if_serving | Boolean | Remove the shard even if it is serving. Use with caution. | -| recursive | Boolean | Also delete all tablets belonging to the 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>. To specify multiple values for this argument, separate individual values with a space. - -#### Errors - -* the <keyspace/shard> argument must be used to identify at least one keyspace and shard when calling the <DeleteShard> command This error occurs if the command is not called with at least one argument. - - -### EmergencyReparentShard - -Reparents the shard to the new master. Assumes the old master is dead and not responding. - -#### Example - -
EmergencyReparentShard -keyspace_shard=<keyspace/shard> -new_master=<tablet alias>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented | -| new_master | string | alias of a tablet that should be the new master | -| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting | - - -#### Errors - -* action <EmergencyReparentShard> requires -keyspace_shard=<keyspace/shard> -new_master=<tablet alias> This error occurs if the command is not called with exactly 0 arguments. -* active reparent commands disabled (unset the -disable_active_reparents flag to enable) -* cannot use legacy syntax and flag -<new_master> for action <EmergencyReparentShard> at the same time - - -### GetShard - -Outputs a JSON structure that contains information about the Shard. - -#### Example - -
GetShard <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 <GetShard> command This error occurs if the command is not called with exactly one argument. - - -### InitShardMaster - -Sets the initial master for a shard. Will make all other tablets in the shard slaves of the provided master. WARNING: this could cause data loss on an already replicating shard. PlannedReparentShard or EmergencyReparentShard should be used instead. - -#### Example - -
InitShardMaster [-force] [-wait_slave_timeout=<duration>] <keyspace/shard> <tablet alias>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| force | Boolean | will force the reparent even if the provided tablet is not a master or the shard master | -| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting | - - -#### 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>. -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. - -#### Errors - -* action <InitShardMaster> requires <keyspace/shard> <tablet alias> This error occurs if the command is not called with exactly 2 arguments. -* active reparent commands disabled (unset the -disable_active_reparents flag to enable) - - -### ListBackups - -Lists all the backups for a shard. - -#### Example - -
ListBackups <keyspace/shard>
- -#### Errors - -* action <ListBackups> requires <keyspace/shard> This error occurs if the command is not called with exactly one argument. - - -### ListShardTablets - -Lists all tablets in the specified shard. - -#### Example - -
ListShardTablets <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 <ListShardTablets> command This error occurs if the command is not called with exactly one argument. - - -### PlannedReparentShard - -Reparents the shard to the new master, or away from old master. Both old and new master need to be up and running. - -#### Example - -
PlannedReparentShard -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>]
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| avoid_master | string | alias of a tablet that should not be the master, i.e. reparent to any other tablet if this one is the master | -| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented | -| new_master | string | alias of a tablet that should be the new master | -| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting | - - -#### Errors - -* action <PlannedReparentShard> requires -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>] This error occurs if the command is not called with exactly 0 arguments. -* active reparent commands disabled (unset the -disable_active_reparents flag to enable) -* cannot use legacy syntax and flags -<keyspace_shard> and -<new_master> for action <PlannedReparentShard> at the same time - - -### RemoveBackup - -Removes a backup for the BackupStorage. - -#### Example - -
RemoveBackup <keyspace/shard> <backup name>
- -#### Arguments - -* <backup name> – Required. - -#### Errors - -* action <RemoveBackup> requires <keyspace/shard> <backup name> This error occurs if the command is not called with exactly 2 arguments. - - -### RemoveShardCell - -Removes the cell from the shard's Cells list. - -#### Example - -
RemoveShardCell [-force] [-recursive] <keyspace/shard> <cell>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| force | Boolean | Proceeds even if the cell's topology service cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. | -| recursive | Boolean | Also delete all tablets in that cell belonging to the specified 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>. -* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. - -#### Errors - -* the <keyspace/shard> and <cell> arguments are required for the <RemoveShardCell> command This error occurs if the command is not called with exactly 2 arguments. - - -### SetShardServedTypes - -Add or remove served type to/from a shard. This is meant as an emergency function. It does not rebuild any serving graph i.e. does not run 'RebuildKeyspaceGraph'. - -#### Example - -
SetShardServedTypes [--cells=c1,c2,...] [--remove] <keyspace/shard> <served tablet type>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string | Specifies a comma-separated list of cells to update | -| remove | Boolean | Removes the served tablet type | - - -#### 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>. -* <served tablet type> – Required. The vttablet's role. Valid values are: - - * backup – A slaved copy of data that is offline to queries other than for backup purposes - * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) - * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. - * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. - * master – A primary copy of data - * rdonly – A slaved copy of data for OLAP load patterns - * replica – A slaved copy of data ready to be promoted to master - * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. - * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. - * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. - - - - -#### Errors - -* the <keyspace/shard> and <served tablet type> arguments are both required for the <SetShardServedTypes> command This error occurs if the command is not called with exactly 2 arguments. - - -### SetShardTabletControl - -Sets the TabletControl record for a shard and type. Only use this for an emergency fix or after a finished vertical split. The *MigrateServedFrom* and *MigrateServedType* commands set this field appropriately already. Always specify the blacklisted_tables flag for vertical splits, but never for horizontal splits.

To set the DisableQueryServiceFlag, keep 'blacklisted_tables' empty, and set 'disable_query_service' to true or false. Useful to fix horizontal splits gone wrong.

To change the blacklisted tables list, specify the 'blacklisted_tables' parameter with the new list. Useful to fix tables that are being blocked after a vertical split.

To just remove the ShardTabletControl entirely, use the 'remove' flag, useful after a vertical split is finished to remove serving restrictions. - -#### Example - -
SetShardTabletControl [--cells=c1,c2,...] [--blacklisted_tables=t1,t2,...] [--remove] [--disable_query_service] <keyspace/shard> <tablet type>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| blacklisted_tables | string | Specifies a comma-separated list of tables to blacklist (used for vertical split). Each is either an exact match, or a regular expression of the form '/regexp/'. | -| cells | string | Specifies a comma-separated list of cells to update | -| disable_query_service | Boolean | Disables query service on the provided nodes. This flag requires 'blacklisted_tables' and 'remove' to be unset, otherwise it's ignored. | -| remove | Boolean | Removes cells for vertical splits. | - - -#### 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>. -* <tablet type> – Required. The vttablet's role. Valid values are: - - * backup – A slaved copy of data that is offline to queries other than for backup purposes - * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) - * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. - * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. - * master – A primary copy of data - * rdonly – A slaved copy of data for OLAP load patterns - * replica – A slaved copy of data ready to be promoted to master - * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. - * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. - * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. - - - - -#### Errors - -* the <keyspace/shard> and <tablet type> arguments are both required for the <SetShardTabletControl> command This error occurs if the command is not called with exactly 2 arguments. - - -### ShardReplicationFix - -Walks through a ShardReplication object and fixes the first error that it encounters. - -#### Example - -
ShardReplicationFix <cell> <keyspace/shard>
- -#### Arguments - -* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. -* <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 <cell> and <keyspace/shard> arguments are required for the ShardReplicationRemove command This error occurs if the command is not called with exactly 2 arguments. - - -### ShardReplicationPositions - -Shows the replication status of each slave machine in the shard graph. In this case, the status refers to the replication lag between the master vttablet and the slave vttablet. In Vitess, data is always written to the master vttablet first and then replicated to all slave vttablets. Output is sorted by tablet type, then replication position. Use ctrl-C to interrupt command and see partial result if needed. - -#### Example - -
ShardReplicationPositions <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 <ShardReplicationPositions> command This error occurs if the command is not called with exactly one argument. - - -### SourceShardAdd - -Adds the SourceShard record with the provided index. This is meant as an emergency function. It does not call RefreshState for the shard master. - -#### Example - -
SourceShardAdd [--key_range=<keyrange>] [--tables=<table1,table2,...>] <keyspace/shard> <uid> <source keyspace/shard>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| key_range | string | Identifies the key range to use for the SourceShard | -| tables | string | Specifies a comma-separated list of tables to replicate (used for vertical split). Each is either an exact match, or a regular expression of the form /regexp/ | - - -#### 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>. -* <uid> – Required. -* <source 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>, <uid>, and <source keyspace/shard> arguments are all required for the <SourceShardAdd> command This error occurs if the command is not called with exactly 3 arguments. - - -### SourceShardDelete - -Deletes the SourceShard record with the provided index. This is meant as an emergency cleanup function. It does not call RefreshState for the shard master. - -#### Example - -
SourceShardDelete <keyspace/shard> <uid>
- -#### 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>. -* <uid> – Required. - -#### Errors - -* the <keyspace/shard> and <uid> arguments are both required for the <SourceShardDelete> command This error occurs if the command is not called with at least 2 arguments. - - -### TabletExternallyReparented - -Changes metadata in the topology service to acknowledge a shard master change performed by an external tool. See [Reparenting](../../user-guides/reparenting/#external-reparenting) for more information. - -#### Example - -
TabletExternallyReparented <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 <TabletExternallyReparented> command This error occurs if the command is not called with exactly one argument. - - -### ValidateShard - -Validates that all nodes that are reachable from this shard are consistent. - -#### Example - -
ValidateShard [-ping-tablets] <keyspace/shard>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process | - - -#### 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 <ValidateShard> command This error occurs if the command is not called with exactly one argument. - - -### WaitForFilteredReplication - -Blocks until the specified shard has caught up with the filtered replication of its source shard. - -#### Example - -
WaitForFilteredReplication [-max_delay <max_delay, default 30s>] <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 <WaitForFilteredReplication> command This error occurs if the command is not called with exactly one argument. - - -## Tablets - -* [Backup](#backup) -* [ChangeSlaveType](#changeslavetype) -* [DeleteTablet](#deletetablet) -* [ExecuteFetchAsDba](#executefetchasdba) -* [ExecuteHook](#executehook) -* [GetTablet](#gettablet) -* [IgnoreHealthError](#ignorehealtherror) -* [InitTablet](#inittablet) -* [Ping](#ping) -* [RefreshState](#refreshstate) -* [RefreshStateByShard](#refreshstatebyshard) -* [ReparentTablet](#reparenttablet) -* [RestoreFromBackup](#restorefrombackup) -* [RunHealthCheck](#runhealthcheck) -* [SetReadOnly](#setreadonly) -* [SetReadWrite](#setreadwrite) -* [Sleep](#sleep) -* [StartSlave](#startslave) -* [StopSlave](#stopslave) -* [UpdateTabletAddrs](#updatetabletaddrs) - -### Backup - -Stops mysqld and uses the BackupStorage service to store a new backup. This function also remembers if the tablet was replicating so that it can restore the same state after the backup completes. - -#### Example - -
Backup [-concurrency=4] <tablet alias>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| concurrency | Int | Specifies the number of compression/checksum jobs to run simultaneously | - - -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. - -#### Errors - -* the <Backup> command requires the <tablet alias> argument This error occurs if the command is not called with exactly one argument. - - -### ChangeSlaveType - -Changes the db type for the specified tablet, if possible. This command is used primarily to arrange replicas, and it will not convert a master.

NOTE: This command automatically updates the serving graph.

- -#### Example - -
ChangeSlaveType [-dry-run] <tablet alias> <tablet type>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| dry-run | Boolean | Lists the proposed change without actually executing it | - - -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. -* <tablet type> – Required. The vttablet's role. Valid values are: - - * backup – A slaved copy of data that is offline to queries other than for backup purposes - * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) - * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. - * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. - * master – A primary copy of data - * rdonly – A slaved copy of data for OLAP load patterns - * replica – A slaved copy of data ready to be promoted to master - * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. - * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. - * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. - - - - -#### Errors - -* the <tablet alias> and <db type> arguments are required for the <ChangeSlaveType> command This error occurs if the command is not called with exactly 2 arguments. -* failed reading tablet %v: %v -* invalid type transition %v: %v -> %v - - -### DeleteTablet - -Deletes tablet(s) from the topology. - -#### Example - -
DeleteTablet [-allow_master] <tablet alias> ...
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| allow_master | Boolean | Allows for the master tablet of a shard to be deleted. Use with caution. | - - -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space. - -#### Errors - -* the <tablet alias> argument must be used to specify at least one tablet when calling the <DeleteTablet> command This error occurs if the command is not called with at least one argument. - - -### ExecuteFetchAsDba - -Runs the given SQL command as a DBA on the remote tablet. - -#### Example - -
ExecuteFetchAsDba [-max_rows=10000] [-disable_binlogs] [-json] <tablet alias> <sql command>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| disable_binlogs | Boolean | Disables writing to binlogs during the query | -| json | Boolean | Output JSON instead of human-readable table | -| max_rows | Int | Specifies the maximum number of rows to allow in reset | -| reload_schema | Boolean | Indicates whether the tablet schema will be reloaded after executing the SQL command. The default value is false, which indicates that the tablet schema will not be reloaded. | - - -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. -* <sql command> – Required. - -#### Errors - -* the <tablet alias> and <sql command> arguments are required for the <ExecuteFetchAsDba> command This error occurs if the command is not called with exactly 2 arguments. - - -### ExecuteHook - -Runs the specified hook on the given tablet. A hook is a script that resides in the $VTROOT/vthook directory. You can put any script into that directory and use this command to run that script.

For this command, the param=value arguments are parameters that the command passes to the specified hook. - -#### Example - -
ExecuteHook <tablet alias> <hook name> [<param1=value1> <param2=value2> ...]
- -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. -* <hook name> – Required. -* <param1=value1> <param2=value2> . – Optional. - -#### Errors - -* the <tablet alias> and <hook name> arguments are required for the <ExecuteHook> command This error occurs if the command is not called with at least 2 arguments. - - -### GetTablet - -Outputs a JSON structure that contains information about the Tablet. - -#### Example - -
GetTablet <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 <GetTablet> command This error occurs if the command is not called with exactly one argument. - - -### IgnoreHealthError - -Sets the regexp for health check errors to ignore on the specified tablet. The pattern has implicit ^$ anchors. Set to empty string or restart vttablet to stop ignoring anything. - -#### Example - -
IgnoreHealthError <tablet alias> <ignore regexp>
- -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. -* <ignore regexp> – Required. - -#### Errors - -* the <tablet alias> and <ignore regexp> arguments are required for the <IgnoreHealthError> command This error occurs if the command is not called with exactly 2 arguments. - - -### InitTablet - -Initializes a tablet in the topology.

- -#### Example - -
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>] -keyspace=<keyspace> -shard=<shard> <tablet alias> <tablet type>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| allow_master_override | Boolean | Use this flag to force initialization if a tablet is created as master, and a master for the keyspace/shard already exists. Use with caution. | -| allow_update | Boolean | Use this flag to force initialization if a tablet with the same name already exists. Use with caution. | -| db_name_override | string | Overrides the name of the database that the vttablet uses | -| grpc_port | Int | The gRPC port for the vttablet process | -| hostname | string | The server on which the tablet is running | -| keyspace | string | The keyspace to which this tablet belongs | -| mysql_host | string | The mysql host for the mysql server | -| mysql_port | Int | The mysql port for the mysql server | -| parent | Boolean | Creates the parent shard and keyspace if they don't yet exist | -| port | Int | The main port for the vttablet process | -| shard | string | The shard to which this tablet belongs | -| tags | string | A comma-separated list of key:value pairs that are used to tag the tablet | - - -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. -* <tablet type> – Required. The vttablet's role. Valid values are: - - * backup – A slaved copy of data that is offline to queries other than for backup purposes - * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) - * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. - * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. - * master – A primary copy of data - * rdonly – A slaved copy of data for OLAP load patterns - * replica – A slaved copy of data ready to be promoted to master - * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. - * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. - * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
vtctl Snapshot -server-mode ...
Use this command to exit this mode: 
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. - - - - -#### Errors - -* the <tablet alias> and <tablet type> arguments are both required for the <InitTablet> command This error occurs if the command is not called with exactly 2 arguments. - - -### Ping - -Checks that the specified tablet is awake and responding to RPCs. This command can be blocked by other in-flight operations. - -#### Example - -
Ping <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 <Ping> command This error occurs if the command is not called with exactly one argument. - - -### RefreshState - -Reloads the tablet record on the specified tablet. - -#### Example - -
RefreshState <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 <RefreshState> command This error occurs if the command is not called with exactly one argument. - - -### RefreshStateByShard - -Runs 'RefreshState' on all tablets in the given shard. - -#### Example - -
RefreshStateByShard [-cells=c1,c2,...] <keyspace/shard>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cells | string | Specifies a comma-separated list of cells whose tablets are included. If empty, all cells are considered. | - - -#### 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 <RefreshStateByShard> command This error occurs if the command is not called with exactly one argument. - - -### ReparentTablet - -Reparent a tablet to the current master in the shard. This only works if the current slave position matches the last known reparent action. - -#### Example - -
ReparentTablet <tablet alias>
- -#### Errors - -* action <ReparentTablet> requires <tablet alias> This error occurs if the command is not called with exactly one argument. -* active reparent commands disabled (unset the -disable_active_reparents flag to enable) - - -### RestoreFromBackup - -Stops mysqld and restores the data from the latest backup. - -#### Example - -
RestoreFromBackup <tablet alias>
- -#### Errors - -* the <RestoreFromBackup> command requires the <tablet alias> argument This error occurs if the command is not called with exactly one argument. - - -### RunHealthCheck - -Runs a health check on a remote tablet. - -#### Example - -
RunHealthCheck <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 <RunHealthCheck> command This error occurs if the command is not called with exactly one argument. - - -### SetReadOnly - -Sets the tablet as read-only. - -#### Example - -
SetReadOnly <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 <SetReadOnly> command This error occurs if the command is not called with exactly one argument. -* failed reading tablet %v: %v - - -### SetReadWrite - -Sets the tablet as read-write. - -#### Example - -
SetReadWrite <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 <SetReadWrite> command This error occurs if the command is not called with exactly one argument. -* failed reading tablet %v: %v - - -### Sleep - -Blocks the action queue on the specified tablet for the specified amount of time. This is typically used for testing. - -#### Example - -
Sleep <tablet alias> <duration>
- -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. -* <duration> – Required. The amount of time that the action queue should be blocked. The value is a string that contains a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms" or "1h45m". See the definition of the Go language's ParseDuration function for more details. Note that, in practice, the value should be a positively signed value. - -#### Errors - -* the <tablet alias> and <duration> arguments are required for the <Sleep> command This error occurs if the command is not called with exactly 2 arguments. - - -### StartSlave - -Starts replication on the specified slave. - -#### Example - -
StartSlave <tablet alias>
- -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. - -#### Errors - -* action <StartSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument. -* failed reading tablet %v: %v - - -### StopSlave - -Stops replication on the specified slave. - -#### Example - -
StopSlave <tablet alias>
- -#### Arguments - -* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. - -#### Errors - -* action <StopSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument. -* failed reading tablet %v: %v - - -### UpdateTabletAddrs - -Updates the IP address and port numbers of a tablet. - -#### Example - -
UpdateTabletAddrs [-hostname <hostname>] [-ip-addr <ip addr>] [-mysql-port <mysql port>] [-vt-port <vt port>] [-grpc-port <grpc port>] <tablet alias>
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| grpc-port | Int | The gRPC port for the vttablet process | -| hostname | string | The fully qualified host name of the server on which the tablet is running. | -| mysql-port | Int | The mysql port for the mysql daemon | -| mysql_host | string | The mysql host for the mysql server | -| vt-port | Int | The main port for the vttablet process | - - -#### 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 <UpdateTabletAddrs> command This error occurs if the command is not called with exactly one argument. - - -## Topo - -* [TopoCat](#topocat) - -### TopoCat - -Retrieves the file(s) at <path> from the topo service, and displays it. It can resolve wildcards, and decode the proto-encoded data. - -#### Example - -
TopoCat [-cell <cell>] [-decode_proto] [-long] <path> [<path>...]
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| cell | string | topology cell to cat the file from. Defaults to global cell. | -| decode_proto | Boolean | decode proto files and display them as text | -| long | Boolean | long listing. | - - -#### Arguments - -* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. -* <path> – Required. -* <path>. – Optional. - -#### Errors - -* <TopoCat>: no path specified This error occurs if the command is not called with at least one argument. -* <TopoCat>: invalid wildcards: %v -* <TopoCat>: some paths had errors - - -## Workflows - -* [WorkflowAction](#workflowaction) -* [WorkflowCreate](#workflowcreate) -* [WorkflowDelete](#workflowdelete) -* [WorkflowStart](#workflowstart) -* [WorkflowStop](#workflowstop) -* [WorkflowTree](#workflowtree) -* [WorkflowWait](#workflowwait) - -### WorkflowAction - -Sends the provided action name on the specified path. - -#### Example - -
WorkflowAction <path> <name>
- -#### Arguments - -* <name> – Required. - -#### Errors - -* the <path> and <name> arguments are required for the <WorkflowAction> command This error occurs if the command is not called with exactly 2 arguments. -* no workflow.Manager registered - - -### WorkflowCreate - -Creates the workflow with the provided parameters. The workflow is also started, unless -skip_start is specified. - -#### Example - -
WorkflowCreate [-skip_start] <factoryName> [parameters...]
- -#### Flags - -| Name | Type | Definition | -| :-------- | :--------- | :--------- | -| skip_start | Boolean | If set, the workflow will not be started. | - - -#### Arguments - -* <factoryName> – Required. - -#### Errors - -* the <factoryName> argument is required for the <WorkflowCreate> command This error occurs if the command is not called with at least one argument. -* no workflow.Manager registered - - -### WorkflowDelete - -Deletes the finished or not started workflow. - -#### Example - -
WorkflowDelete <uuid>
- -#### Errors - -* the <uuid> argument is required for the <WorkflowDelete> command This error occurs if the command is not called with exactly one argument. -* no workflow.Manager registered - - -### WorkflowStart - -Starts the workflow. - -#### Example - -
WorkflowStart <uuid>
- -#### Errors - -* the <uuid> argument is required for the <WorkflowStart> command This error occurs if the command is not called with exactly one argument. -* no workflow.Manager registered - - -### WorkflowStop - -Stops the workflow. - -#### Example - -
WorkflowStop <uuid>
- -#### Errors - -* the <uuid> argument is required for the <WorkflowStop> command This error occurs if the command is not called with exactly one argument. -* no workflow.Manager registered - - -### WorkflowTree - -Displays a JSON representation of the workflow tree. - -#### Example - -
WorkflowTree
- -#### Errors - -* the <WorkflowTree> command takes no parameter This error occurs if the command is not called with exactly 0 arguments. -* no workflow.Manager registered - - -### WorkflowWait - -Waits for the workflow to finish. - -#### Example - -
WorkflowWait <uuid>
- -#### Errors - -* the <uuid> argument is required for the <WorkflowWait> command This error occurs if the command is not called with exactly one argument. -* no workflow.Manager registered diff --git a/content/en/docs/reference/vtexplain.md b/content/en/docs/reference/vtexplain.md deleted file mode 100644 index 825fc9d3a..000000000 --- a/content/en/docs/reference/vtexplain.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: VTExplain command line tool ---- - -# Overview - -This document provides information about the options and syntax of the `VTExplain` tool. - -To learn more about the way Vitess executes a particular SQL statement using the `VTexplain` tool, see the doument [Explaining how Vitess executes a SQL statement](../../user-guides/vtexplain). - -## About VTExplain - -The `VTExplain` tool provides information about how Vitess will execute a particular SQL statement. `VTExplain` is analagous to the MySQL [`EXPLAIN`](https://dev.mysql.com/doc/refman/8.0/en/explain.html) tool. - -## Syntax - -``` -> vtexplain {-vschema|vschema-file} {-schema|-schema-file} -sql -``` - -## Options - -The `vtexplain` command takes the following options: - --dbname string -: Optional database target to override normal routing (default "") - --output-mode string -: Output in human-friendly text or json (default "text") - --normalize -: Whether to enable vtgate normalization (default false) - --shards int -: Number of shards to simulate per keyspace (default 2).`vtexplain` will always allocate an evenly divided key range to each. - --replication-mode string -: The replication mode to simulate: either ROW or STATEMENT (default "ROW"). - --schema string -: The SQL table schema (default ""). Either `schema` or `schema-file` is required. - --schema-file string -: Identifies the file that contains the SQL table schema (default ""). Either `schema` or `schema-file` is required. - --sql string -: A list of semicolon-delimited SQL commands to analyze (default ""). Required. - --sql-file string -: Identifies the file that contains the SQL commands to analyze (default "") - --vschema string -: Identifies the VTGate routing schema (default ""). Either `-vschema` or `-vschema-file` is required. - --vschema-file string -: Identifies the VTGate routing schema file (default "") - --queryserver-config-passthrough-dmls -: query server pass through all dml statements without rewriting (default false) - -To view a list of these options, execute the following command: - -``` -vtexplain --help -``` - -## Examples - -``` -vtexplain -vschema-file vschema.json -schema-file schema.sql -sql "SELECT * FROM users" -``` - -The example above explains how Vitess would execute the query `SELECT * FROM users` using the VSchema contained in `vschema.json` and the database schema contained in `schema.sql`. - -``` -vtexplain -shards 128 -vschema-file /tmp/vschema.json -schema-file /tmp/schema.sql -replication-mode "ROW" -output-mode text -sql "INSERT INTO users (user_id, name) VALUES(1, 'john')" -``` - -The example above explains how Vitess would execute the query `INSERT INTO users (user_id, name) VALUES(1, 'john')`, simulating 128 shards and row-based replication, and specifying text-based output. - -## Limitations - -### The VSchema must use a keyspace name. - -VTExplain requires a keyspace name for each keyspace in an input VSChema: - -``` -"keyspace_name": { - "_comment": "Keyspace definition goes here." -} -``` - -If no keyspace name is present, VTExplain will return the following error: - -``` -ERROR: initVtgateExecutor: json: cannot unmarshal bool into Go value of type map[string]json.RawMessage -``` - -## See also - -+ [Explaining how Vitess executes a SQL statement](../../user-guides/vtexplain) - diff --git a/content/en/docs/reference/vttablet-modes.md b/content/en/docs/reference/vttablet-modes.md deleted file mode 100644 index 087f30995..000000000 --- a/content/en/docs/reference/vttablet-modes.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: VTTablet Modes -aliases: ['/docs/user-guides/vttablet-modes/'] ---- - -VTTablet can be configured to control MySQL at many levels. At the level with the most control, VTTablet can perform backups and restores, respond to reparenting commands coming through vtctld, automatically fix replication, and enforce semi-sync settings. - -At the level with the least control, vttablet just sends the application’s queries to MySQL. The level of desired control is achieved through various command line arguments, explained below. - -## Managed MySQL - -In the mode with the highest control, VTTablet can take backups. It can also automatically restore from an existing backup to prime a new replica. For this mode, vttablet needs to run on the same host as MySQL, and must be given access to MySQL's `my.cnf` file. Additionally, the flags must not contain any connectivity flags like -db_host or -db_socket; VTTablet will fetch the socket information from `my.cnf` and use that to connect to the local MySQL. - -It will also load other information from the `my.cnf`, like the location of data files, etc. When it receives a request to take a backup, it will shut down MySQL, copy the MySQL data files to the backup store, and restart MySQL. - -The `my.cnf` file can be specified in the following ways: - -* Implicit: If MySQL was initialized by the `mysqlctl` tool, then vttablet can find it based on just the `-tablet-path`. The default location for this file is `$VTDATAROOT/vt_/my.cnf`. -* `-mycnf-file`: This option can be used if the file is not present in the default location. -* `-mycnf_server_id` and other flags: You can specify all values of the `my.cnf` file from the command line, and vttablet will behave as it read this information from a physical file. - -Specifying a `-db_host` or a `-db_socket` flag will cause vttablet to skip the loading of the `my.cnf` file, and will disable its ability to perform backups or restores. - -## -restore_from_backup - -The default value for this flag is false (i.e. the flag is not present). If set to true (i.e. the flag is present), and the `my.cnf` file was successfully loaded, then vttablet can perform automatic restores as follows: - -* If started against a MySQL instance that has no data files, it will search the list of backups for the latest one, and initiate a restore. -* After this, it will point the MySQL to the current master and wait for replication to catch up. Once replication is caught up to the specified tolerance limit, it will advertise itself as serving. -* This will cause the vtgates to add it to the list of healthy tablets to serve queries from. - -If this flag is present, but `my.cnf` was not loaded, then vttablet will fatally exit with an error message. - -You can additionally control the level of concurrency for a restore with the `-restore_concurrency` flag (default is set to 4). This is typically useful in cloud environments to prevent the restore process from becoming a 'noisy' neighbor by consuming all available disk IOPS. - -## Unmanaged or remote MySQL - -You can start a vttablet against a remote MySQL instance by simply specifying the connection flags `-db_host` and `-db_port` on the command line. In this mode, backup and restore operations will be disabled. If you start vttablet against a local MySQL, you can specify a `-db_socket` instead, which will still make vttablet treat the MySQL instance as if it was remote. - -Specifically, the absence of a `my.cnf` file indicates to vttablet that it's connecting to a remote MySQL instance. - -## Partially managed MySQL - -Even if a MySQL is remote, you can still make vttablet perform some management functions. They are as follows: - -* `-disable_active_reparents`: If this flag is set, then any reparent or slave commands will not be allowed. These are InitShardMaster, PlannedReparent, EmergencyReparent, and ReparentTablet. In this mode, you should use the TabletExternallyReparented command to inform Vitess of the current master. -* `-master_connect_retry`: This value is given to MySQL when it connects a slave to the master as the retry duration parameter. -* `-enable_replication_reporter`: If this flag is set, then vttablet will transmit replica lag related information to the vtgates, which will allow it to balance load better. Additionally, enabling this will also cause vttablet to restart replication if it was stopped. However, it will do this only if `-disable_active_reparents` was not turned on. -* `-enable_semi_sync`: This option will automatically enable semi-sync replication on new replicas as well as on any tablet that transitions to a replica type. This includes the demotion of a master to a replica. -* `-heartbeat_enable` and `-heartbeat_interval_duration`: cause vttablet to write heartbeats to the sidecar database. This information is also used by the replication reporter to assess replica lag. - -## Typical vttablet command line flags - -### Minimal vttablet flags to enable query serving: - -``` -$TOPOLOGY_FLAGS --tablet-path $alias --init_keyspace $keyspace --init_shard $shard --init_tablet_type $tablet_type --port $port --grpc_port $grpc_port --service_map 'grpc-queryservice,grpc-tabletmanager,grpc-updatestream' -``` - -`$alias` needs to be of the form: `-id`, and the cell should match one of the local cells that was created in the topology. The id can be left padded with zeroes: `cell-100` and `cell-000000100` are synonymous. - -Example `TOPOLOGY_FLAGS` for a Topology Service like zookeeper: - -`-topo_implementation zk2 -topo_global_server_address localhost:21811,localhost:21812,localhost:21813 -topo_global_root /vitess/global` - -### Additional flags to enable cluster management - -``` --enable_semi_sync --enable_replication_reporter --backup_storage_implementation file --file_backup_storage_root $BACKUP_MOUNT --restore_from_backup --vtctld_addr http://$hostname:$vtctld_web_port/ -``` - -### Additional flags for running in prod - -``` --queryserver-config-pool-size 24 --queryserver-config-stream-pool-size 24 --queryserver-config-transaction-cap 300 -``` - -More tuning flags are available, but the above overrides are definitely needed for serving reasonable production traffic. - -### Connecting vttablet to a running MySQL instance - -``` --db_host $MYSQL_HOST --db_port $MYSQL_PORT --db_app_user $USER --db_app_password $PASSWORD -``` - -### Additional user credentials that need to be supplied for performing various operations - -``` --db_allprivs_user --db_allprivs_password --db_appdebug_user --db_appdebug_password --db_dba_user --db_dba_password --db_filtered_user --db_filtered_password -``` -Other flags exist for finer control. diff --git a/layouts/partials/docs/pages-in-section.html b/layouts/partials/docs/pages-in-section.html index e9f9b00a1..b0e927055 100644 --- a/layouts/partials/docs/pages-in-section.html +++ b/layouts/partials/docs/pages-in-section.html @@ -3,7 +3,7 @@