diff --git a/content/en/docs/15.0/get-started/local-brew.md b/content/en/docs/15.0/get-started/local-brew.md index f9d9a56c8..c60bec6e8 100644 --- a/content/en/docs/15.0/get-started/local-brew.md +++ b/content/en/docs/15.0/get-started/local-brew.md @@ -1,7 +1,7 @@ --- title: Local Install via Homebrew description: Instructions for using Vitess on your macOS machine for testing purposes -weight: 2 +weight: 3 featured: true aliases: ['/docs/tutorials/local-brew/'] --- diff --git a/content/en/docs/15.0/get-started/local-docker.md b/content/en/docs/15.0/get-started/local-docker.md index f9b56336b..0f6c36bfb 100644 --- a/content/en/docs/15.0/get-started/local-docker.md +++ b/content/en/docs/15.0/get-started/local-docker.md @@ -1,11 +1,15 @@ --- title: Local Install via Docker description: Instructions for using Vitess on your machine for testing purposes -weight: 1 -featured: true +weight: 5 +featured: false aliases: ['/docs/tutorials/local-docker/'] --- +{{< warning >}} +This guide will only work on x86_64/amd64 based machines. +{{}} + This guide illustrates how to run a local testing Vitess setup via Docker. The Vitess environment is identical to the [local setup](../local/), but without having to install software on one's host other than Docker. ## Check out the vitessio/vitess repository diff --git a/content/en/docs/15.0/get-started/local.md b/content/en/docs/15.0/get-started/local.md index 93dc51e51..d9e0e8188 100644 --- a/content/en/docs/15.0/get-started/local.md +++ b/content/en/docs/15.0/get-started/local.md @@ -85,11 +85,11 @@ Download the [latest binary release](https://github.com/vitessio/vitess/releases **Notes:** * Release 15.0 has a bug because of which the local example fails when try to run vtadmin web. [Issue#11679](https://github.com/vitessio/vitess/issues/11679) -* Please use release [15.0.3](https://github.com/vitessio/vitess/releases/tag/v15.0.3) instead. +* Please use release [15.0.3](https://github.com/vitessio/vitess/releases/tag/v15.0.3) or later. ```sh -version=15.0.3 -file=vitess-${version}-652b0da.tar.gz +version=15.0.4 +file=vitess-${version}-72d943e.tar.gz wget https://github.com/vitessio/vitess/releases/download/v${version}/${file} tar -xzf ${file} cd ${file/.tar.gz/} diff --git a/content/en/docs/15.0/get-started/operator.md b/content/en/docs/15.0/get-started/operator.md index 16adcfa87..621b3bdb1 100644 --- a/content/en/docs/15.0/get-started/operator.md +++ b/content/en/docs/15.0/get-started/operator.md @@ -1,6 +1,6 @@ --- title: Vitess Operator for Kubernetes -weight: 3 +weight: 1 featured: true aliases: ['/docs/tutorials/kubernetes/','/user-guide/sharding-kubernetes.html', '/docs/get-started/scaleway/','/docs/get-started/kubernetes/'] --- diff --git a/content/en/docs/15.0/get-started/vttestserver-docker-image.md b/content/en/docs/15.0/get-started/vttestserver-docker-image.md index b4a7aab80..e5f452a5f 100644 --- a/content/en/docs/15.0/get-started/vttestserver-docker-image.md +++ b/content/en/docs/15.0/get-started/vttestserver-docker-image.md @@ -1,6 +1,6 @@ --- title: Vttestserver Docker Image -weight: 4 +weight: 10 featured: true aliases: ['/docs/tutorials/vttestserver/'] --- diff --git a/content/en/docs/15.0/reference/features/messaging.md b/content/en/docs/15.0/reference/features/messaging.md index d0dc86136..8724ae323 100644 --- a/content/en/docs/15.0/reference/features/messaging.md +++ b/content/en/docs/15.0/reference/features/messaging.md @@ -122,12 +122,22 @@ Messages can also be created to be sent in the future: ## Receiving messages -Processes can subscribe to receive messages by sending a `MessageStream` +Processes can subscribe to receive messages by sending a [`MessageStream`](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate#Executor.MessageStream) gRPC request to a `VTGate` or using the `stream * from ` SQL statement (if using the interactive mysql command-line client you must also pass the -`-q`/`--quick` option). If there are multiple subscribers, the messages will be -delivered in a round-robin fashion. Note that *this is not a broadcast*; each -message will be sent to at most one subscriber. +`-q`/`--quick` option): + +```mysql +$ mysql --quick +mysql> SET WORKLOAD=OLAP; +mysql> STREAM * FROM
; +``` + +
+ +If there are multiple subscribers, the messages will be delivered in a round-robin +fashion. Note that *this is not a broadcast*; each message will be sent to at most +one subscriber. The format for messages is the same as a standard Vitess `Result` received from a `VTGate`. This means that standard database tools that understand query results diff --git a/content/en/docs/16.0/get-started/local-brew.md b/content/en/docs/16.0/get-started/local-brew.md index 73c833660..95723c40a 100644 --- a/content/en/docs/16.0/get-started/local-brew.md +++ b/content/en/docs/16.0/get-started/local-brew.md @@ -1,7 +1,7 @@ --- title: Local Install via Homebrew description: Instructions for using Vitess on your macOS machine for testing purposes -weight: 2 +weight: 3 featured: true aliases: ['/docs/tutorials/local-brew/'] --- diff --git a/content/en/docs/16.0/get-started/local-docker.md b/content/en/docs/16.0/get-started/local-docker.md index 8eaecff3f..d4bf43fd5 100644 --- a/content/en/docs/16.0/get-started/local-docker.md +++ b/content/en/docs/16.0/get-started/local-docker.md @@ -1,11 +1,15 @@ --- title: Local Install via Docker description: Instructions for using Vitess on your machine for testing purposes -weight: 1 -featured: true +weight: 5 +featured: false aliases: ['/docs/tutorials/local-docker/'] --- +{{< warning >}} +This guide will only work on x86_64/amd64 based machines. +{{}} + This guide illustrates how to run a local testing Vitess setup via Docker. The Vitess environment is identical to the [local setup](../local/), but without having to install software on one's host other than Docker. ## Check out the vitessio/vitess repository diff --git a/content/en/docs/16.0/get-started/local.md b/content/en/docs/16.0/get-started/local.md index e8b62b803..c1e427715 100644 --- a/content/en/docs/16.0/get-started/local.md +++ b/content/en/docs/16.0/get-started/local.md @@ -85,12 +85,12 @@ Download the [latest binary release](https://github.com/vitessio/vitess/releases **Notes:** * Release 16.0.0 has an issue where the VTAdmin `web` directory is missing from the release artifacts. -* Please use release [16.0.2](https://github.com/vitessio/vitess/releases/tag/v16.0.2) instead. +* Please use release [16.0.2](https://github.com/vitessio/vitess/releases/tag/v16.0.2) or later. * Ubuntu is the only fully supported OS, for another OS please [build Vitess by yourself](/docs/contributing) or use the Docker images. ```sh -version=16.0.2 -file=vitess-${version}-6076fed.tar.gz +version=16.0.3 +file=vitess-${version}-a93cb55.tar.gz wget https://github.com/vitessio/vitess/releases/download/v${version}/${file} tar -xzf ${file} cd ${file/.tar.gz/} diff --git a/content/en/docs/16.0/get-started/operator.md b/content/en/docs/16.0/get-started/operator.md index 8e17c183f..55112f490 100644 --- a/content/en/docs/16.0/get-started/operator.md +++ b/content/en/docs/16.0/get-started/operator.md @@ -1,6 +1,6 @@ --- title: Vitess Operator for Kubernetes -weight: 3 +weight: 1 featured: true aliases: ['/docs/tutorials/kubernetes/','/user-guide/sharding-kubernetes.html', '/docs/get-started/scaleway/','/docs/get-started/kubernetes/'] --- diff --git a/content/en/docs/16.0/get-started/vttestserver-docker-image.md b/content/en/docs/16.0/get-started/vttestserver-docker-image.md index 5d6949b53..fac47efe5 100644 --- a/content/en/docs/16.0/get-started/vttestserver-docker-image.md +++ b/content/en/docs/16.0/get-started/vttestserver-docker-image.md @@ -1,6 +1,6 @@ --- title: Vttestserver Docker Image -weight: 4 +weight: 10 featured: true aliases: ['/docs/tutorials/vttestserver/'] --- diff --git a/content/en/docs/16.0/reference/features/messaging.md b/content/en/docs/16.0/reference/features/messaging.md index d0dc86136..8724ae323 100644 --- a/content/en/docs/16.0/reference/features/messaging.md +++ b/content/en/docs/16.0/reference/features/messaging.md @@ -122,12 +122,22 @@ Messages can also be created to be sent in the future: ## Receiving messages -Processes can subscribe to receive messages by sending a `MessageStream` +Processes can subscribe to receive messages by sending a [`MessageStream`](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate#Executor.MessageStream) gRPC request to a `VTGate` or using the `stream * from
` SQL statement (if using the interactive mysql command-line client you must also pass the -`-q`/`--quick` option). If there are multiple subscribers, the messages will be -delivered in a round-robin fashion. Note that *this is not a broadcast*; each -message will be sent to at most one subscriber. +`-q`/`--quick` option): + +```mysql +$ mysql --quick +mysql> SET WORKLOAD=OLAP; +mysql> STREAM * FROM
; +``` + +
+ +If there are multiple subscribers, the messages will be delivered in a round-robin +fashion. Note that *this is not a broadcast*; each message will be sent to at most +one subscriber. The format for messages is the same as a standard Vitess `Result` received from a `VTGate`. This means that standard database tools that understand query results diff --git a/content/en/docs/17.0/get-started/local-brew.md b/content/en/docs/17.0/get-started/local-brew.md index a895481af..3d752fa8d 100644 --- a/content/en/docs/17.0/get-started/local-brew.md +++ b/content/en/docs/17.0/get-started/local-brew.md @@ -1,7 +1,7 @@ --- title: Local Install via Homebrew description: Instructions for using Vitess on your macOS machine for testing purposes -weight: 2 +weight: 3 featured: true aliases: ['/docs/tutorials/local-brew/'] --- @@ -37,12 +37,12 @@ Already downloaded: /Users/askdba/Library/Caches/Homebrew/downloads/45991b27589a ``` At this point Vitess binaries installed under default Homebrew install location at /usr/local/share/vitess. -### Install Node 16.13.0+ (required to run VTAdmin) +### Install Node 18.16.0+ (required to run VTAdmin) ```bash $ brew install nvm -$ nvm install --lts 16.13.0 -$ nvm use 16.13.0 +$ nvm install --lts 18.16.0 +$ nvm use 18.16.0 ``` See the [vtadmin README](https://github.com/vitessio/vitess/blob/main/web/vtadmin/README.md) for more details. @@ -60,41 +60,42 @@ Created cell: zone1 etcd start done... Starting vtctld... vtctld is running! +Successfully created keyspace commerce. Result: +{ + "name": "commerce", + "keyspace": { + "served_froms": [], + "keyspace_type": 0, + "base_keyspace": "", + "snapshot_time": null, + "durability_policy": "semi_sync", + "throttler_config": null, + "sidecar_db_name": "_vt" + } +} Starting MySQL for tablet zone1-0000000100... Starting vttablet for zone1-0000000100... HTTP/1.1 200 OK -Date: Thu, 01 Sep 2022 12:49:50 GMT +Date: Mon, 26 Jun 2023 19:21:51 GMT Content-Type: text/html; charset=utf-8 Starting MySQL for tablet zone1-0000000101... Starting vttablet for zone1-0000000101... HTTP/1.1 200 OK -Date: Thu, 01 Sep 2022 12:49:55 GMT +Date: Mon, 26 Jun 2023 19:21:54 GMT Content-Type: text/html; charset=utf-8 Starting MySQL for tablet zone1-0000000102... Starting vttablet for zone1-0000000102... HTTP/1.1 200 OK -Date: Thu, 01 Sep 2022 12:50:00 GMT +Date: Mon, 26 Jun 2023 19:21:56 GMT Content-Type: text/html; charset=utf-8 -{ - "keyspace": { - "served_froms": [], - "keyspace_type": 0, - "base_keyspace": "", - "snapshot_time": null, - "durability_policy": "semi_sync", - "throttler_config": null, - "sidecar_db_name": "_vt" - } -} vtorc is running! - UI: http://localhost:16000 - - Logs: /Users/manangupta/vitess/vtdataroot/tmp/vtorc.out - - PID: 74088 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtorc.out + - PID: 49556 -zone1-0000000100 commerce 0 primary localhost:15100 localhost:17100 [] 2022-09-23T05:48:52Z New VSchema object: { @@ -107,7 +108,8 @@ New VSchema object: "auto_increment": null, "columns": [], "pinned": "", - "column_list_authoritative": false + "column_list_authoritative": false, + "source": "" }, "customer": { "type": "", @@ -115,7 +117,8 @@ New VSchema object: "auto_increment": null, "columns": [], "pinned": "", - "column_list_authoritative": false + "column_list_authoritative": false, + "source": "" }, "product": { "type": "", @@ -123,7 +126,8 @@ New VSchema object: "auto_increment": null, "columns": [], "pinned": "", - "column_list_authoritative": false + "column_list_authoritative": false, + "source": "" } }, "require_explicit_routing": false @@ -131,51 +135,16 @@ New VSchema object: If this is not what you expected, check the input data (as JSON parsing will skip unexpected fields). Waiting for vtgate to be up... vtgate is up! -Access vtgate at http://Manans-MacBook-Pro.local:15001/debug/status +Access vtgate at http://Florents-MacBook-Pro-2.local:15001/debug/status vtadmin-api is running! - - API: http://localhost:14200 - - Logs: /Users/manangupta/vitess/vtdataroot/tmp/vtadmin-api.out - - PID: 74039 - -> vtadmin@0.1.0 build -> vite build - -vite v4.2.1 building for production... -transforming (1218) src/icons/alertFail.svgUse of eval in "node_modules/@protobufjs/inquire/index.js" is strongly discouraged as it poses security risks and may cause issues with minification. -✓ 1231 modules transformed. -build/assets/chevronUp-3d6782a5.svg 0.18 kB -build/assets/chevronDown-02f94e73.svg 0.19 kB -build/assets/download-8ef290b4.svg 0.21 kB -build/assets/delete-a9184ef9.svg 0.23 kB -build/assets/info-2617ee9d.svg 0.34 kB -build/assets/circleAdd-cfd7e5db.svg 0.35 kB -build/assets/alertFail-8056b6e4.svg 0.35 kB -build/assets/checkSuccess-f8fd1dbb.svg 0.36 kB -build/assets/search-3261bac7.svg 0.41 kB -build/assets/question-a67b2492.svg 0.46 kB -build/assets/runQuery-edfab4ed.svg 0.49 kB -build/assets/open-405dd348.svg 0.49 kB -build/index.html 0.90 kB -build/assets/bug-5b6edb54.svg 0.99 kB -build/assets/topology-0032b65e.svg 1.62 kB -build/assets/NotoMono-Regular-41fd7ccc.ttf 107.85 kB -build/assets/NotoSans-Regular-c8cff31f.ttf 313.14 kB -build/assets/NotoSans-SemiBold-43207822.ttf 313.72 kB -build/assets/NotoSans-Bold-c6a598dd.ttf 313.79 kB -build/assets/index-ef40fbc9.css 87.78 kB │ gzip: 15.02 kB -build/assets/index-4ddb52ed.js 2,811.88 kB │ gzip: 492.59 kB - -(!) Some chunks are larger than 500 kBs after minification. Consider: -- Using dynamic import() to code-split the application -- Use build.rollupOptions.output.manualChunks to improve chunking: https://rollupjs.org/configuration-options/#output-manualchunks -- Adjust chunk size limit for this warning via build.chunkSizeWarningLimit. -✓ built in 10.85s + - API: http://Florents-MacBook-Pro-2.local:14200 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtadmin-api.out + - PID: 49695 vtadmin-web is running! - - Browser: http://localhost:14201 - - Logs: /Users/manangupta/vitess/vtdataroot/tmp/vtadmin-web.out - - PID: 74070 - + - Browser: http://Florents-MacBook-Pro-2.local:14201 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtadmin-web.out + - PID: 49698 ``` Verify your initial cluster: ```sql diff --git a/content/en/docs/17.0/get-started/local-docker.md b/content/en/docs/17.0/get-started/local-docker.md index 8eaecff3f..d4bf43fd5 100644 --- a/content/en/docs/17.0/get-started/local-docker.md +++ b/content/en/docs/17.0/get-started/local-docker.md @@ -1,11 +1,15 @@ --- title: Local Install via Docker description: Instructions for using Vitess on your machine for testing purposes -weight: 1 -featured: true +weight: 5 +featured: false aliases: ['/docs/tutorials/local-docker/'] --- +{{< warning >}} +This guide will only work on x86_64/amd64 based machines. +{{}} + This guide illustrates how to run a local testing Vitess setup via Docker. The Vitess environment is identical to the [local setup](../local/), but without having to install software on one's host other than Docker. ## Check out the vitessio/vitess repository diff --git a/content/en/docs/17.0/get-started/local.md b/content/en/docs/17.0/get-started/local.md index 2593b7144..717c09ff7 100644 --- a/content/en/docs/17.0/get-started/local.md +++ b/content/en/docs/17.0/get-started/local.md @@ -65,8 +65,8 @@ Download the [latest binary release](https://github.com/vitessio/vitess/releases * Ubuntu is the only fully supported OS, for another OS please [build Vitess by yourself](/docs/contributing) or use the Docker images. ```sh -version=17.0.0 -file=vitess-${version}-70a9466.tar.gz +version=17.0.1 +file=vitess-${version}-a4e751f.tar.gz wget https://github.com/vitessio/vitess/releases/download/v${version}/${file} tar -xzf ${file} cd ${file/.tar.gz/} diff --git a/content/en/docs/17.0/get-started/operator.md b/content/en/docs/17.0/get-started/operator.md index 8e17c183f..55112f490 100644 --- a/content/en/docs/17.0/get-started/operator.md +++ b/content/en/docs/17.0/get-started/operator.md @@ -1,6 +1,6 @@ --- title: Vitess Operator for Kubernetes -weight: 3 +weight: 1 featured: true aliases: ['/docs/tutorials/kubernetes/','/user-guide/sharding-kubernetes.html', '/docs/get-started/scaleway/','/docs/get-started/kubernetes/'] --- diff --git a/content/en/docs/17.0/get-started/vttestserver-docker-image.md b/content/en/docs/17.0/get-started/vttestserver-docker-image.md index 46924ef98..b7193536c 100644 --- a/content/en/docs/17.0/get-started/vttestserver-docker-image.md +++ b/content/en/docs/17.0/get-started/vttestserver-docker-image.md @@ -1,6 +1,6 @@ --- title: Vttestserver Docker Image -weight: 4 +weight: 10 featured: true aliases: ['/docs/tutorials/vttestserver/'] --- diff --git a/content/en/docs/17.0/reference/features/messaging.md b/content/en/docs/17.0/reference/features/messaging.md index d0dc86136..8724ae323 100644 --- a/content/en/docs/17.0/reference/features/messaging.md +++ b/content/en/docs/17.0/reference/features/messaging.md @@ -122,12 +122,22 @@ Messages can also be created to be sent in the future: ## Receiving messages -Processes can subscribe to receive messages by sending a `MessageStream` +Processes can subscribe to receive messages by sending a [`MessageStream`](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate#Executor.MessageStream) gRPC request to a `VTGate` or using the `stream * from
` SQL statement (if using the interactive mysql command-line client you must also pass the -`-q`/`--quick` option). If there are multiple subscribers, the messages will be -delivered in a round-robin fashion. Note that *this is not a broadcast*; each -message will be sent to at most one subscriber. +`-q`/`--quick` option): + +```mysql +$ mysql --quick +mysql> SET WORKLOAD=OLAP; +mysql> STREAM * FROM
; +``` + +
+ +If there are multiple subscribers, the messages will be delivered in a round-robin +fashion. Note that *this is not a broadcast*; each message will be sent to at most +one subscriber. The format for messages is the same as a standard Vitess `Result` received from a `VTGate`. This means that standard database tools that understand query results diff --git a/content/en/docs/17.0/reference/features/recovery.md b/content/en/docs/17.0/reference/features/recovery.md index 7d9786d50..0be939330 100644 --- a/content/en/docs/17.0/reference/features/recovery.md +++ b/content/en/docs/17.0/reference/features/recovery.md @@ -6,6 +6,23 @@ aliases: ['/docs/recovery/pitr','/docs/reference/pitr/'] ## Point in Time Recovery +Vitess supports incremental backup and recoveries, AKA point in time recoveries. `v17` offers restore-to-position functionality, and `v18` is slated to support restore-to-timestamp functionality in addition. + +Point in time recoveries are based on full and incremental backups. It is possible to recover a database to a position that is _covered_ by some backup. + +See [Backup Types](../../../user-guides/operating-vitess/backup-and-restore/overview/#backup-types) and [Restore Types](../../../user-guides/operating-vitess/backup-and-restore/overview/#restore-types) for an overview of incremental backups and restores. + +See the user guides for how to [Create an Incremental Backup](../../../user-guides/operating-vitess/backup-and-restore/creating-a-backup/#create-an-incremental-backup-with-vtctl) and how to [Restore to a position](../../../user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore/#restore-to-a-point-in-time). + +### Supported Databases +- MySQL 5.7, 8.0 + +### Notes + +This functionality replaces a legacy functionality, based on binlog servers and transient binary logs. + +## Point in Time Recovery: legacy functionality based on binlog server + ### Supported Databases - MySQL 8.0 diff --git a/content/en/docs/17.0/reference/features/tablet-throttler.md b/content/en/docs/17.0/reference/features/tablet-throttler.md index 21b7d6595..0de167dc7 100644 --- a/content/en/docs/17.0/reference/features/tablet-throttler.md +++ b/content/en/docs/17.0/reference/features/tablet-throttler.md @@ -102,6 +102,12 @@ It is possible to _restrict_ the throttler's response to one or more apps. For e It is _not possible_ to give an app more way than the throttler's standard behavior. That is, if the throttler is set to throttler at `5s` replication lag, it is _not possible_ to respond wih `HTTP 200` to a specific app with replication lag at `7s`. +Vitess has a granular breakdown for its own throttler apps. Generally, the user should not change throttling configuration for internal apps. However, some of the apps are user-facing or user-initiated, and it makes sense for the user to restrict them. These apps include: + +- `online-ddl`: affecting all schema migrations of all strategies. +- `vreplication`: all VReplication operations, for example: MoveTables, Reshard, Online DDL via `vitess/online` strategy. +- `vplayer`: the VPlayer component of VReplication, which tails, processes and applies events from the bianry logs. +- `vcopier`: the VCopier component of VReplication, which copies over the mass of table rows from source to target tables. ## Configuration {{< warning >}} diff --git a/content/en/docs/17.0/reference/programs/vttablet.md b/content/en/docs/17.0/reference/programs/vttablet.md index b23b3997b..d34196110 100644 --- a/content/en/docs/17.0/reference/programs/vttablet.md +++ b/content/en/docs/17.0/reference/programs/vttablet.md @@ -296,7 +296,7 @@ The following global options apply to `vttablet`: | --queryserver-config-txpool-timeout | float | 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 | -| --queryserver-enable-settings-pool | boolean | Enable pooling of connections with modified system settings | +| --queryserver-enable-settings-pool | boolean | Enable pooling of connections with modified system settings (default true) | | --queryserver-enable-views | boolean | Enable views support in vttablet. | | --queryserver_enable_online_ddl | boolean | Enable online DDL. (default true) | | --redact-debug-ui-queries | boolean | redact full queries and bind variables from debug UI | @@ -403,6 +403,7 @@ The following global options apply to `vttablet`: | --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 | Synonym to -tx_throttler_config (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-default-priority int | int | Default query priority used by the transaction throttler if it is not specified in a query comment directive. It must be a number between 0 (highest priority) and 100 (lowest priority) (default: 100) | | --tx-throttler-healthcheck-cells | strings | Synonym to -tx_throttler_healthcheck_cells | | --tx-throttler-tablet-types | strings | A comma-separated list of tablet types. Only tablets of this type are monitored for replication lag by the transaction throttler. Supported types are replica and/or rdonly. (default replica) | | --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") | diff --git a/content/en/docs/17.0/reference/query-serving/reserved-conn.md b/content/en/docs/17.0/reference/query-serving/reserved-conn.md index 40b449351..bf5644a8e 100644 --- a/content/en/docs/17.0/reference/query-serving/reserved-conn.md +++ b/content/en/docs/17.0/reference/query-serving/reserved-conn.md @@ -39,7 +39,7 @@ What we want to highlight at the beginning is that there is a known issue when a To solve this problem, the connection pool implementation used by vttablet has been enhanced to keep the connections with settings in the pool and not to pin the connection to the client session. With this enhancement, we reduce the likelihood of MySQL running out of connections due to reserved connections, because the scenarios where we still need reserved connections are sharply reduced. -Since this is a new feature, it is currently disabled by default. It can be enabled by setting the flag `--queryserver-enable-settings-pool` on vttablet. +This is enabled by default from v17 onwards. It can be disabled by setting the flag `--queryserver-enable-settings-pool` on vttablet. This change takes effect only for the cases when system variable changes need a reserved connection. There are still cases like [temporary tables](#temporary-tables-and-reserved-connections) and [advisory locks](#get_lock-and-reserved-connections) where reserved connections will continue to be used. diff --git a/content/en/docs/17.0/user-guides/configuration-advanced/comment-directives.md b/content/en/docs/17.0/user-guides/configuration-advanced/comment-directives.md index daad76c7a..faadca599 100644 --- a/content/en/docs/17.0/user-guides/configuration-advanced/comment-directives.md +++ b/content/en/docs/17.0/user-guides/configuration-advanced/comment-directives.md @@ -119,3 +119,15 @@ As shown above, the metrics being instrumented this way are `vttablet_query_coun If the query lacks the `WORKLOAD_NAME` directive, the corresponding label in the metric will have the value of an empty string. If `vttablet` is not started with `--enable-per-workload-table-metrics`, metrics are emitted without the workload label (e.g. `vttablet_query_counts{plan="Select",table="customer"}`. + +### Priority (`PRIORITY`) + +Specifies the priority associated with the execution of this query, as a number between 0 (highest priority) and 100 +(lowest priority). The priority is used by the transaction throttler (see `--tx-throttler-...` and `-enable-tx-throttler` +flags in the `vttablet` [documentation](../../reference/programs/vttablet.md))) to determine whether a particular query +should be throttled. If the transaction throttler determines that a query may need to be throttled, it will throttle it +with a probability equal to the provided query priority. This allows avoiding high business impact queries from being +throttled (by setting their priority to `0`) while letting less business critical ones continue to be throttled (by +setting their priority to more than `0`). + +Notice that this directive has no effect if the transaction throttler is not enabled. diff --git a/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md b/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md index 5ab721ed7..6ab431628 100644 --- a/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md +++ b/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md @@ -4,7 +4,8 @@ weight: 3 aliases: ['/docs/user-guides/backup-and-restore/'] --- -## Restoring a backup +Restores can be done automatically by way of seeding/bootstrapping new tablets, or they can be invoked manually on a tablet to restore a full backup or do a point-in-time recovery. +## Auto restoring a backup on startup When a tablet starts, Vitess checks the value of the `--restore_from_backup` command-line flag to determine whether to restore a backup to that tablet. Restores will always be done with whichever engine was used to create the backup. @@ -32,3 +33,41 @@ Bootstrapping a new tablet is almost identical to restoring an existing tablet. ``` The bootstrapped tablet will restore the data from the backup and then apply changes, which occurred after the backup, by restarting replication. + +## Manual restore + +A manual restore is done on a specific tablet. The tablet's MySQL server is shut down and its data is wiped out. + +### Restore a full backup + +To restore the tablet from the most recent full backup, run: + +```shell +vtctldclient --server=: RestoreFromBackup +``` + +Example: + +```shell +vtctldclient --server localhost:15999 --alsologtostderr RestoreFromBackup zone1-0000000101 +``` + +If successful, the tablet's MySQL server rejoins the shard's replication stream, to eventually captch up and be able to serve traffic. + +### Restore to a point-in-time + +`v17` supports incremental restore, or restoring to a specific _position_: + +```shell +vtctlclient -- RestoreFromBackup --restore_to_pos +``` + +Example: + +```shell +vtctlclient -- RestoreFromBackup --restore_to_pos "MySQL56/0d7aaca6-1666-11ee-aeaf-0a43f95f28a3:1-60" zone1-0000000102 +``` + +This restore method assumes backups have been taken that cover the specified position. The restore process will first determine a restore path: a sequence of backups, starting with a full backup followed by zero or more incremental backups, that when combined, include the specified position. See more on [Restore Types](../overview/#restore-types) and on [Taking Incremental Backup](../creating-a-backup/#create-an-incremental-backup-with-vtctl). + +`v18` will supports restore to a given timestamp. diff --git a/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md b/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md index 665fba502..ff4ffaaba 100644 --- a/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md +++ b/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md @@ -4,6 +4,12 @@ weight: 2 aliases: ['/docs/user-guides/backup-and-restore/'] --- +## Choosing the backup type + +As described in [Backup types](../overview/#backup-types), you choose to run a full Backup (the default) or an incremental Backup. + +Full backups will use the backup engine chosen in the tablet's [configuration](#configuration). Incremental backups will always copy MySQL's binary logs, irrespective of the configured backup engine. + ## Using xtrabackup The default backup implementation is `builtin`, however we strongly recommend using the `xtrabackup` engine as it is more robust and allows for non-blocking backups. Restores will always be done with whichever engine was used to create the backup. @@ -75,11 +81,11 @@ I0310 12:49:32.279773 215835 backup.go:163] I0310 20:49:32.279485 xtrabackupeng To continue with risk: Set `--xtrabackup_backup_flags=--no-server-version-check`. Note this occurs when your MySQL server version is technically unsupported by `xtrabackup`. -## Create backups with vtctl +## Create a full backup with vtctl __Run the following vtctl command to create a backup:__ -``` sh +```sh vtctldclient --server=: Backup ``` @@ -89,10 +95,31 @@ If the engine is `xtrabackup`, the tablet can continue to serve traffic while th __Run the following vtctl command to backup a specific shard:__ -``` sh +```sh vtctldclient --server=: BackupShard [--allow_primary=false] ``` +## Create an incremental backup with vtctl + +An incremental backup requires additional information: the point from which to start the backup. An incremental backup is taken by supplying `--incremental_from_pos` to the `Backup` command. The argument may either indicate a valid position, or the value `auto`. Examples: + +```sh +vtctlclient -- Backup --incremental_from_pos="MySQL56/0d7aaca6-1666-11ee-aeaf-0a43f95f28a3:1-53" zone1-0000000102 + +vtctlclient -- Backup --incremental_from_pos="auto" zone1-0000000102 +``` + +When `--incremental_from_pos="auto"`, Vitess chooses the position of the last successful backup as the starting point for the incremental backup. This is a convenient way to ensure a sequence of contiguous incremental backups. + +An incremental backup backs up one or more MySQL binary log files. These binary log files may begin with the requested position, or with an earlier position. They will necessarily include the requested position. When the incremental backup begins, Vitess rotates the MySQL binary logs on the tablet, so that it does not back up an active log file. + +An incremental backup fails in these scenarios: + +- It is unable to find binary log files that covers the requested position. This can happen if the binary logs are purged earlier than the incremental backup was taken. It essentially means there's a gap in the changelog events. **Note** that while on one tablet the binary logs may be missing, another tablet may still have binary logs that cover the requested position. +- There is no change to the database since the requested position, i.e. the GTID position has not changed since. + +`v17` only supports `--incremental_from_pos` in the `Backup` command, not in `BackupShard`. Also, only `vtctlclient` supports the flag, where `vtctldclient` does not. `v18` is expected to support incremental backups for `BackupShard` and for `vtctldclient`. + ## Backing up Topology Server The Topology Server stores metadata (and not tablet data). It is recommended to create a backup using the method described by the underlying plugin: diff --git a/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/overview.md b/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/overview.md index 1f7e98996..d7ac333d1 100644 --- a/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/overview.md +++ b/content/en/docs/17.0/user-guides/operating-vitess/backup-and-restore/overview.md @@ -26,6 +26,36 @@ The engine is the techology used for generating the backup. Currently Vitess has * Builtin: Shutdown an instance and copy all the database files (default) * XtraBackup: An online backup using Percona's [XtraBackup](https://www.percona.com/software/mysql-database/percona-xtrabackup) +### Backup types + +Vitess supports full backups as well as incremental backups, and their respective counterparts full restores and point-in-time restores. + +* A full backup contains the entire data in the database. The backup represents a consistent state of the data, i.e. it is a snapshot of the data at some point in time. +* An incremental backup contains a changelog, or a transition of data from one state to another. Vitess implements incremental backups by making a copy of MySQL binary logs. + +Generally speaking and on most workloads, the cost of a full backup is higher, and the cost of incremental backups is lower. The time it takes to create a full backup is significant, and it is therefore impractical to take full backups in very small intervals. Moreover, a full backup consumes the disk space needed for the entire dataset. Incremental backups, on the other hand, are quick to run, and have very little impact, if any, to the running servers. They only contain the changes in between two points in time, and on most workloads are more compact. + +Full and incremental backups are expected to be interleaved. For example: one would create a full backup once per day, and incremental backups once per hour. + +Full backups are simply states of the database. Incremental backups, however, need to start with some point and end with some point. The common practice is for an incremental backup to continue from the point of the last good backup, which can be a full or incremental backup. An inremental backup in Vitess ends at the point in time of execution. + +The identity of the tablet on which a full backup or an incremental backup is taken is immaterial. It is possible to take a full backup on one tablet and incremental backups on another. It is possible to take full backups on two different tablets. It is also possible to take incremental backups, independently, on two different tablets, even though the contents of those incremental backups overlaps. Vitess uses MySQL GTID sets to determine positioning and prune duplicates. + +### Restores + +Restores are the counterparts of backups. A restore uses the engine utilized to create a backup. One may run a restore from a full backup, or a point-in-time restore (PITR) based on additional incremental backups. + +A Vitess restore operates on a tablet. The restore process completely wipes out the data in the tablet's MySQL server and repopulates the server with the backup(s) data. The MySQL server is shutdown during the process. As a safety mechanism, Vitess by default prevents a restore onto a `PRIMARY` tablet. Any non-`PRIMARY` tablet is otherwise eligible to restore. + +### Restore Types + +Vitess supports full restores and incremental (AKA point-in-time) restores. The two serve different purposes. + +* A full restore loads the dataset from a full backup onto a non-`PRIMARY` tablet. Once the data is loaded, the restore process starts the MySQL service and makes it join the replication stream. It is expected that a freshly restored server will lag behind the shard's `PRIMARY` for a period of time. + The full restore flow is useful for seeding new replica tablets. It may also be used to fix replicas that have been corrupted. +* An incremental, or a point-in-time restore, restores a tablet/MySQL up to a specific position or time. This is done by first loading a full backup dataset, followed by applying the changelog captured in zero or more incremental backups. Once that is complete, the tablet type is set to `DRAINED` and the tablet does _not_ join the replication stream. + The common purpose of point-in-time restore is to recover data from an accidental write/deletion. If the database administrator knows at about what time the accidental write took place, they can restore a replica tablet to a point in time shortly before the accidental write. Since the server does not join the replication stream, its data then remains static, and the administrator may review or copy the data as they please. Finally, it is then possible to change the tablet type back to `REPLICA` and have it join the shard's replication. + ## Vtbackup, VTTablet and Vtctld Vtbackup, VTTablet, and Vtctld may all participate in backups and restores. diff --git a/content/en/docs/17.0/user-guides/vschema-guide/advanced-vschema.md b/content/en/docs/17.0/user-guides/vschema-guide/advanced-vschema.md index 440d1bb82..1429063a3 100644 --- a/content/en/docs/17.0/user-guides/vschema-guide/advanced-vschema.md +++ b/content/en/docs/17.0/user-guides/vschema-guide/advanced-vschema.md @@ -46,7 +46,7 @@ A reference table should not have any vindex, and is defined in the VSchema as a #### Source Tables -Vitess will optimize reference tables routing when joined to a table within the same keyspace. Additional routing optimizations can be enabled by specifying the `source` of a reference table. When a reference table specifies a `source` table: +Vitess will optimize reference table routing when joined to a table within the same keyspace. Additional routing optimizations can be enabled by specifying the `source` of a reference table. When a reference table specifies a `source` table: * A `SELECT ... JOIN` (or equivalent `SELECT ... WHERE`) will try to route the query to the keyspace of the table to which the reference (or source) table @@ -70,7 +70,6 @@ For example: There are some constraints on `source`: - * It must be a keyspace-qualified table name, e.g. `unsharded_ks.zip_detail`. * It must refer to an existing table in an existing keyspace. * It must refer to a table in a different keyspace. * It must refer to a table in an unsharded keyspace. diff --git a/content/en/docs/18.0/get-started/local-brew.md b/content/en/docs/18.0/get-started/local-brew.md index 7b55955fd..3d752fa8d 100644 --- a/content/en/docs/18.0/get-started/local-brew.md +++ b/content/en/docs/18.0/get-started/local-brew.md @@ -1,7 +1,7 @@ --- title: Local Install via Homebrew description: Instructions for using Vitess on your macOS machine for testing purposes -weight: 2 +weight: 3 featured: true aliases: ['/docs/tutorials/local-brew/'] --- diff --git a/content/en/docs/18.0/get-started/local-docker.md b/content/en/docs/18.0/get-started/local-docker.md index 8eaecff3f..d4bf43fd5 100644 --- a/content/en/docs/18.0/get-started/local-docker.md +++ b/content/en/docs/18.0/get-started/local-docker.md @@ -1,11 +1,15 @@ --- title: Local Install via Docker description: Instructions for using Vitess on your machine for testing purposes -weight: 1 -featured: true +weight: 5 +featured: false aliases: ['/docs/tutorials/local-docker/'] --- +{{< warning >}} +This guide will only work on x86_64/amd64 based machines. +{{}} + This guide illustrates how to run a local testing Vitess setup via Docker. The Vitess environment is identical to the [local setup](../local/), but without having to install software on one's host other than Docker. ## Check out the vitessio/vitess repository diff --git a/content/en/docs/18.0/get-started/operator.md b/content/en/docs/18.0/get-started/operator.md index 8e17c183f..55112f490 100644 --- a/content/en/docs/18.0/get-started/operator.md +++ b/content/en/docs/18.0/get-started/operator.md @@ -1,6 +1,6 @@ --- title: Vitess Operator for Kubernetes -weight: 3 +weight: 1 featured: true aliases: ['/docs/tutorials/kubernetes/','/user-guide/sharding-kubernetes.html', '/docs/get-started/scaleway/','/docs/get-started/kubernetes/'] --- diff --git a/content/en/docs/18.0/get-started/vttestserver-docker-image.md b/content/en/docs/18.0/get-started/vttestserver-docker-image.md index 46924ef98..e64739f6a 100644 --- a/content/en/docs/18.0/get-started/vttestserver-docker-image.md +++ b/content/en/docs/18.0/get-started/vttestserver-docker-image.md @@ -1,6 +1,6 @@ --- title: Vttestserver Docker Image -weight: 4 +weight: 10 featured: true aliases: ['/docs/tutorials/vttestserver/'] --- @@ -51,20 +51,20 @@ At this point, you should have a docker image named `vitess/vttestserver:mysql57 The docker image expects some of the environment variables to be set to function properly. The following table lists all the environment variables available along with their usages. -| Environment variable | Required | Use | -| -- | -- | -- | -| *KEYSPACES* | yes | Specifies the names of the keyspaces to be created as a comma separated value. | -| *NUM_SHARDS* | yes | Specifies the number of shards in each keyspace. It is a comma separated value as well, read in conjunction with the KEYSPACES. | -| *PORT* | yes | The starting of the port addresses that vitess will use to register its components like vtgate, etc. | -| *MYSQL_MAX_CONNECTIONS* | no | Maximum number of connections that the MySQL instance will support. If unspecified, it defaults to 1000. | -| *MYSQL_BIND_HOST* | no | Which host to bind the MySQL listener to. If unspecified, it defaults to `127.0.0.1`. | -| *MYSQL_SERVER_VERSION* | no | MySQL server version to advertise. If unspecified, it defaults to `8.0.31-vitess` or `5.7.9-vitess` according to the version of vttestserver run. | -| *CHARSET* | no | Default charset to use. If unspecified, it defaults to `utf8mb4`. | -| *FOREIGN_KEY_MODE* | no | This is to provide how to handle foreign key constraint in create/alter table. Valid values are: allow (default), disallow. | -| *ENABLE_ONLINE_DDL* | no | Allow users to submit, review and control Online DDL. Valid values are: true (default), false. | -| *ENABLE_DIRECT_DDL* | no | Allow users to submit direct DDL statements. Valid values are: true (default), false. | -| *PLANNER_VERSION* | no | Sets the default planner to use when the session has not changed it. Valid values are: Gen4 (default), v3, Gen4Greedy and Gen4Fallback. Gen4Fallback tries the new gen4 planner and falls back to the V3 planner if the gen4 fails. | -| *TABLET_REFRESH_INTERVAL* | no | Interval at which vtgate refreshes tablet information from topology server. | +| Environment variable | Required | Use | +|---------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| *KEYSPACES* | yes | Specifies the names of the keyspaces to be created as a comma separated value. | +| *NUM_SHARDS* | yes | Specifies the number of shards in each keyspace. It is a comma separated value as well, read in conjunction with the KEYSPACES. | +| *PORT* | yes | The starting of the port addresses that vitess will use to register its components like vtgate, etc. | +| *MYSQL_MAX_CONNECTIONS* | no | Maximum number of connections that the MySQL instance will support. If unspecified, it defaults to 1000. | +| *MYSQL_BIND_HOST* | no | Which host to bind the MySQL listener to. If unspecified, it defaults to `127.0.0.1`. | +| *MYSQL_SERVER_VERSION* | no | MySQL server version to advertise. If unspecified, it defaults to `8.0.31-vitess` or `5.7.9-vitess` according to the version of vttestserver run. | +| *CHARSET* | no | Default charset to use. If unspecified, it defaults to `utf8mb4`. | +| *FOREIGN_KEY_MODE* | no | This is to provide how to handle foreign key constraint in create/alter table. Valid values are: allow (default), disallow. | +| *ENABLE_ONLINE_DDL* | no | Allow users to submit, review and control Online DDL. Valid values are: true (default), false. | +| *ENABLE_DIRECT_DDL* | no | Allow users to submit direct DDL statements. Valid values are: true (default), false. | +| *PLANNER_VERSION* | no | Sets the default planner to use when the session has not changed it. Valid values are: Gen4, Gen4Greedy, Gen4Left2Right. | +| *TABLET_REFRESH_INTERVAL* | no | Interval at which vtgate refreshes tablet information from topology server. | Environment variables in docker can be specified using the `-e` aka `--env` flag. diff --git a/content/en/docs/18.0/reference/backup-and-restore/metrics.md b/content/en/docs/18.0/reference/backup-and-restore/metrics.md index 1645642f7..ac83023ed 100644 --- a/content/en/docs/18.0/reference/backup-and-restore/metrics.md +++ b/content/en/docs/18.0/reference/backup-and-restore/metrics.md @@ -50,11 +50,11 @@ _restore_duration_seconds_ times the duration of a restore. This metric is depre Vtbackup exports some metrics which are not available elsewhere. -#### DurationByPhaseSeconds +#### Phase Vtbackup fetches the last backup, restores it to an empty mysql installation, replicates recent changes into that installation, and then takes a backup of that installation. -_DurationByPhaseSeconds_ exports timings for these individual phases. +_Phase_ a binary-valued gauge that reports the currently active phase.
@@ -91,11 +91,11 @@ _DurationByPhaseSeconds_ exports timings for these individual phases. "BackupEngine.Builtin.Destination:Close": 17144630, "BackupStorage.File.File:Write": 10743169 }, - "DurationByPhaseSeconds": { - "InitMySQLd": 2, - "RestoreLastBackup": 6, - "CatchUpReplication": 1, - "TakeNewBackup": 4 + "Phase": { + "InitialBackup": 0, + "RestoreLastBackup": 0, + "CatchUpReplication": 0, + "TakeNewBackup": 0 }, "RestoreBytes": { "BackupEngine.Builtin.Source:Read": 1095, @@ -131,6 +131,6 @@ _DurationByPhaseSeconds_ exports timings for these individual phases. Some notes to help understand these metrics: * `BackupBytes["BackupStorage.File.File:Write"]` measures how many bytes were read from disk by the `file` Backup Storage implementation during the backup phase. - * `DurationByPhaseSeconds["CatchUpReplication"]` measures how long it took to catch-up replication after the restore phase. - * `DurationByPhaseSeconds["RestoreLastBackup"]` measures to the duration of the restore phase. + * `Phase["CatchUpReplication"]` reports whether the catch-up replication phase is active (1) or not (0). + * `Phase["RestoreLastBackup"]` reports whether the restore last backup phase is active (1) or not (0). * `RestoreDurationNanoseconds["-.-.Restore"]` also measures to the duration of the restore phase. diff --git a/content/en/docs/18.0/reference/compatibility/gen4-and-v3-compatibility.md b/content/en/docs/18.0/reference/compatibility/gen4-and-v3-compatibility.md deleted file mode 100644 index fb61ab653..000000000 --- a/content/en/docs/18.0/reference/compatibility/gen4-and-v3-compatibility.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Gen4 and V3 Compatibility -weight: 2 -aliases: ['/docs/reference/gen4-against-v3/', '/docs/reference/gen4-and-v3-compatibility/'] ---- - -The latest version of the Vitess query planner, `Gen4`, changes most of the planner's internals. -To ensure `Gen4` produces plans that, once executed, give us the same results as what `V3` would do, we have developed -a small test tool that runs queries using both `Gen4` and `V3` planners and compare their results. If the results we got are different -from the two planners, the query will fail and the difference will be printed in VTGate's logs as a warning. - -This tool is enabled by the use of a new planner: `Gen4CompareV3`, to use it, we must start VTGate with the `--planner-version` -flag set to `Gen4CompareV3`. Once set, new queries will be tested against both `Gen4` and `V3`. diff --git a/content/en/docs/18.0/reference/compatibility/mysql-compatibility.md b/content/en/docs/18.0/reference/compatibility/mysql-compatibility.md index c9bdff72b..04d19f50c 100644 --- a/content/en/docs/18.0/reference/compatibility/mysql-compatibility.md +++ b/content/en/docs/18.0/reference/compatibility/mysql-compatibility.md @@ -125,16 +125,26 @@ Vitess does not yet support Window Functions or Common Table Expressions. ### Killing running queries -Vitess does not yet support killing running queries via the `KILL` command through VTGate. -Currently, there exists a comment directive [QUERY_TIMEOUT_MS](../../../user-guides/configuration-advanced/comment-directives/#query-timeouts-query_timeout_ms) that can be set to reduce the query timeout which will ensure that the query either return result or abort within that time. +In v18, Vitess introduced the ability to terminate running queries using the [`KILL` command](https://dev.mysql.com/doc/refman/8.0/en/kill.html) through VTGate. +To execute a "kill connection" or "kill query" statement, the client needs to establish a new connection. +This behavior is similar to when a user on the MySQL shell client terminates a command by pressing ctrl+c. -Vitess does have strict query timeouts for OLTP workloads (see below). If you need to kill a query, you can connect to the underlying MySQL shard instance and run `KILL` from there. +The [RFC](https://github.com/vitessio/vitess/issues/13438) highlights the current limitation of the `Kill statement` support. + +Alternatively, +- [query_timeout_ms](../../../user-guides/configuration-advanced/comment-directives/#query-timeouts-query_timeout_ms) query comment directive can be set to define a query timeout. This ensures that the query either returns a result or aborts within the specified time. +- [mysql_server_query_timeout](../../programs/vtgate/) command-line flag can be set on VTGate to establish a default timeout. + +Vitess does have strict query timeouts for OLTP workloads (see below). ### Workload -By default, Vitess sets some intentional restrictions on the execution time and number of rows that a query can return. This default workload mode is called `OLTP`. This can be disabled by setting the workload to `OLAP`: +By default, Vitess applies specific limitations on the execution time and the number of rows a query can return. +These limitations can be modified by adjusting the parameters like `queryserver-config-query-timeout`, `queryserver-config-transaction-timeout` and more in [vttablet](../../programs/vttablet/). +This default workload mode is referred as `OLTP`. This can be disabled by switching to `OLAP` mode by executing the following SQL statement: + ```sql -SET workload='olap' +set workload = olap; ``` ### SELECT ... INTO Statement diff --git a/content/en/docs/18.0/reference/features/messaging.md b/content/en/docs/18.0/reference/features/messaging.md index d0dc86136..8724ae323 100644 --- a/content/en/docs/18.0/reference/features/messaging.md +++ b/content/en/docs/18.0/reference/features/messaging.md @@ -122,12 +122,22 @@ Messages can also be created to be sent in the future: ## Receiving messages -Processes can subscribe to receive messages by sending a `MessageStream` +Processes can subscribe to receive messages by sending a [`MessageStream`](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate#Executor.MessageStream) gRPC request to a `VTGate` or using the `stream * from
` SQL statement (if using the interactive mysql command-line client you must also pass the -`-q`/`--quick` option). If there are multiple subscribers, the messages will be -delivered in a round-robin fashion. Note that *this is not a broadcast*; each -message will be sent to at most one subscriber. +`-q`/`--quick` option): + +```mysql +$ mysql --quick +mysql> SET WORKLOAD=OLAP; +mysql> STREAM * FROM
; +``` + +
+ +If there are multiple subscribers, the messages will be delivered in a round-robin +fashion. Note that *this is not a broadcast*; each message will be sent to at most +one subscriber. The format for messages is the same as a standard Vitess `Result` received from a `VTGate`. This means that standard database tools that understand query results diff --git a/content/en/docs/18.0/reference/features/recovery.md b/content/en/docs/18.0/reference/features/recovery.md index 7d9786d50..0be939330 100644 --- a/content/en/docs/18.0/reference/features/recovery.md +++ b/content/en/docs/18.0/reference/features/recovery.md @@ -6,6 +6,23 @@ aliases: ['/docs/recovery/pitr','/docs/reference/pitr/'] ## Point in Time Recovery +Vitess supports incremental backup and recoveries, AKA point in time recoveries. `v17` offers restore-to-position functionality, and `v18` is slated to support restore-to-timestamp functionality in addition. + +Point in time recoveries are based on full and incremental backups. It is possible to recover a database to a position that is _covered_ by some backup. + +See [Backup Types](../../../user-guides/operating-vitess/backup-and-restore/overview/#backup-types) and [Restore Types](../../../user-guides/operating-vitess/backup-and-restore/overview/#restore-types) for an overview of incremental backups and restores. + +See the user guides for how to [Create an Incremental Backup](../../../user-guides/operating-vitess/backup-and-restore/creating-a-backup/#create-an-incremental-backup-with-vtctl) and how to [Restore to a position](../../../user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore/#restore-to-a-point-in-time). + +### Supported Databases +- MySQL 5.7, 8.0 + +### Notes + +This functionality replaces a legacy functionality, based on binlog servers and transient binary logs. + +## Point in Time Recovery: legacy functionality based on binlog server + ### Supported Databases - MySQL 8.0 diff --git a/content/en/docs/18.0/reference/features/tablet-throttler.md b/content/en/docs/18.0/reference/features/tablet-throttler.md index 21b7d6595..67c73399d 100644 --- a/content/en/docs/18.0/reference/features/tablet-throttler.md +++ b/content/en/docs/18.0/reference/features/tablet-throttler.md @@ -45,7 +45,7 @@ In addition, the primary tablet is responsible for the overall health of the clu - The throttler confirms it is still the primary tablet for its shard. - Every `10sec`, the throttler uses the topology server to refresh the shard's tablets list. -- The throttler probes all `REPLICA` tablets for their replication lag. This is done by querying the `_vt.heartbeat` table. +- The throttler probes all `REPLICA` tablets (or other types of tablets, see [Configuration](#configuration)) for their own throttler metrics. This is done via gRPC. - The throttler begins in dormant probe mode. As long as no application or client is actually looking for metrics, it probes the servers at multi-second intervals. - When applications check for throttle advice, the throttler begins probing servers in subsecond intervals. It reverts to dormant probe mode if no requests are made in the duration of `1min`. - The throttler aggregates the last probed values from all relevant tablets. This is _the cluster's metric_. @@ -100,68 +100,42 @@ It is possible for the throttler to respond differently -- to some extent -- to It is possible to _restrict_ the throttler's response to one or more apps. For example, it's possible to completely throttle "vreplication" while still responding `HTTP 200` to other apps. This is typically used to give way or precedence to one or two apps, or otherwise to further reduce the incoming load from a specific app. -It is _not possible_ to give an app more way than the throttler's standard behavior. That is, if the throttler is set to throttler at `5s` replication lag, it is _not possible_ to respond wih `HTTP 200` to a specific app with replication lag at `7s`. +Starting `v18`, it is also possible to _exempt_ an app from throttling, even if the throttler is otherwise rejecting requests with metrics beyond the threshold. This is an advanced feature that users should treat with great care, and only in situations where they absolutely must give a specific workflow/migration the highest priority above all else. See discussion in examples, below. ## Configuration {{< warning >}} -Configuration in v16 differs from v15 and earlier. Please note the different configuration options for your version.{{< /warning >}} +Per-tablet throttler configuration, as used in `v15` and supported in `v16`, is no longer supported in `v18`.{{< /warning >}} -`v16` is backwards compliant with `v15` and still default to the `v15` configuration. We illustrate both configurations so that you understand how to transition from one to the other. +Throttler configuration is found in the [local topology server](../../../concepts/topology-service/). There is one configuration per keyspace. All shards and all tablets in all cells have the same throttler configuration: they are all enabled or disabled, and all share the same threshold or custom query. Since configuration is stored outside the tablet, it survives tablet restarts. -### v17 and forward +`v16` introduced a new opt-in `vttablet` flag, `--throttler-config-via-topo`, and the flag defaulted `false`. In `v17` the flag now defaulted to `true`. In `v18`, the flag is not used anymore, and the tablet looks for configuration in the topology server, and will watch and apply any changes made there. -In `v17`, throttler configuration is found in the [local topology server](../../../concepts/topology-service/). There is one configuration per keyspace. All shards and all tablets in all cells have the same throttler configuration: they are all enabled or disabled, and all share the same threshold or custom query. Since configuration is stored outside the tablet, it survives tablet restarts. +The following flags are deprecated (and will be removed in `v19`): -`v16` introduced a new opt-in `vttablet` flag, `--throttler-config-via-topo`. In `v16` this flag defaulted `false`. In `v17` this flag now defaults `true`. With `--throttler-config-via-topo` set, the tablet will look for configuration in the topology server, and will watch and apply any changes made there. - -When the flag `--throttler-config-via-topo` is set (and it is set by default), the following flags are ignored even if specified. These flags are scheduled to be removed in `v18`and `v19`: - -- `--enable_lag_throttler` - `--throttle_threshold` - `--throttle_metrics_query` - `--throttle_metrics_threshold` - `--throttle_check_as_check_self` +- `--throttler-config-via-topo` +The following flag was removed: + +- `--enable_lag_throttler` Updating the throttler config is done via `vtctlclient` or `vtctldclient`. For example: ```sh $ vtctlclient -- UpdateThrottlerConfig --enable --threshold 3.0 commerce $ vtctldclient UpdateThrottlerConfig --disable commerce +$ vtctldclient UpdateThrottlerConfig --throttle-app="vreplication" --throttle-app-ratio 0.5 --throttle-app-duration "30m" commerce ``` See [vtctl UpdateThrottlerConfig](../../programs/vtctl/throttler#updatethrottlerconfig). -If you are still using the `v15` flags, we recommend that you transition to the new throttler configuration scheme: first populate topo with a new throttler configuration via `UpdateThrottlerConfig`. At the very least, set a `--threshold`. You likely also want to `--enable`. Then, reconfigure `vttablet`s with `--throttler-config-via-topo`, and restart them. - - -### v16 and before - -In earlier versions, the throttler is configured per tablet. Each tablet can have throttler enabled/disabled independently, or have different thresholds. - -`v17` still supports the per-tablet configuration if you specify `--throttler-config-via-topo=false`, but this will be removed in `v18`. - -- The throttler is **disabled** by default. Use the `vttablet` option `--enable-lag-throttler` to enable the throttler. - When the throttler is disabled, it still serves `/throttler/check` and `/throttler/check-self` API endpoints, and responds with `HTTP 200 OK` to all requests. - When the throttler is enabled, it implicitly also runs heartbeat injections. -- Use the `vttablet` flag `--throttle_threshold` to set a lag threshold value. The default threshold is `1sec` and is set upon tablet startup. For example, to set a half-second lag threshold, use the flag `--throttle_threshold=0.5s`. -- To set the tablet types that the throttler queries for lag, use the `vttablet` flag `--throttle_tablet_types="replica,rdonly"`. The default tablet type is `replica`; this type is always implicitly included in the tablet types list. You may add any other tablet type. Any type not specified is ignored by the throttler. -- To override the default lag evaluation, and measure a different metric, use `--throttle_metrics_query`. The query must be either of these forms: - - `SHOW GLOBAL STATUS LIKE ''` - - `SHOW GLOBAL VARIABLES LIKE ''` - - `SELECT FROM ...`, expecting single column, single row result -- To override the throttle threshold, use `--throttle_metrics_threshold`. Floating point values are accepted. -- Use `--throttle_check_as_check_self` to implicitly reroute any `/throttler/check` call into `/throttler/check-self`. This makes sense when the user supplies a custom query, and where the user wishes to throttle writes to the cluster based on the primary tablet's health, rather than the overall health of the cluster. +If you are still using the `v15` flags, you will have to transition to the new throttler configuration scheme: first populate topo with a new throttler configuration via `UpdateThrottlerConfig`. At the very least, set a `--threshold`. You likely also want to `--enable`. Then, reconfigure `vttablet`s with `--throttler-config-via-topo`, and restart them. -An example for custom query & threshold setup, using the MySQL metrics `Threads_running` (number of threads actively executing a query at a given time) on the primary, might look like: - -```shell -$ vttablet - --throttle_metrics_query "show global status like 'threads_running'" - --throttle_metrics_threshold 150 - --throttle_check_as_check_self -``` +The list of tablet types included in the throttler's logic is dictated by `vttablet --throttle_tablet_types`. The value is a comma delimited list of tablet types. The default value is `"replica"`. You may, for example, set it to be `"replica,rdonly"`. ## Heartbeat configuration @@ -183,7 +157,7 @@ Applications use these API endpoints: #### Examples: -- `gh-ost` uses this throttler endpoint: `/throttler/check?app=gh-ost&p=low` +- `gh-ost` uses this throttler endpoint: `/throttler/check?app=online-ddl:gh-ost:&p=low` - A data backfill application will identify as such, and use _normal_ priority: `/throttler/check?app=my_backfill` (priority not indicated in URL therefore assumed to be _normal_) - An app reading a massive amount of data directly from a replica tablet will use `/throttler/check-self?app=my_data_reader` @@ -195,32 +169,123 @@ A `HEAD` request is sufficient. A `GET` request also provides a `JSON` output. F In the first two above examples we can see that the tablet is configured to throttle at `1sec` -### Instructions +### Control -- `/throttler/throttle-app?app=&duration=[&ratio=][&p=low]`: instructs the throttler to begin throttling requests from given app. - - A mandatory `duration` value auto expires the throttling after indicated time. You may specify these units: `s` (seconds), `m` (minutes), `h` (hours) or combinations. Example values: `90s`, `30m`, `1h`, `1h30m`, etc. - - An optional `ratio` value indicates the throttling intensity, ranging from `0` (no throttling at all) to `1.0` (the default, full throttle). - With a value of `0.3`, for example, `3` out of `10`, on average, checks by the app, are flat out denied, regardless of present metrics and threshold. The remaining `7` out of `10` checks, will get a response that is based on the actual metrics and threshold (thereby, thay may be approved, or they may be rejected). - - Applications may also declare themselves to be _low priority_ via `?p=low` param. Managed online schema migrations (`gh-ost`, `pt-online-schema-change`) do so, as does the table purge process. -- `/throttler/unthrottle-app?app=`: instructs the throttler to stop throttling for the given app. This removes any previous throttling instruction for the app. the throttler still reserves the right to throttle the app based on cluster status. +All controls below apply to a given keyspace (`commerce` in the next examples). All of the keyspace's tablets, in all shards and cells, are affected. -#### Examples: +Enable the throttler: + +```sh +$ vtctldclient UpdateThrottlerConfig --enable commerce +``` + +Disable the throttler + +```sh +$ vtctldclient UpdateThrottlerConfig --disable commerce +``` -- `/throttler/throttle-app?app=vreplication&duration=2h` rejects all requests made by `vreplication` for the next `2` hours, after which the app is unthrottled. -- `/throttler/throttle-app?app=vreplication&duration=2h&ratio=0.25` rejects on average 1 out of 4 requests made by `vreplication` for the next `2` hours, after which the app is unthrottled. +Enable and also set a replication lag threshold: + +```sh +$ vtctldclient UpdateThrottlerConfig --enable --threshold 15.0 commerce +``` -{{< info >}} -If using `curl` from a shell prompt/script, make sure to enclose URL with quotes, like so: +Set a custom query and a matching threshold. Does not affect enabled state: +```sh +$ vtctldclient UpdateThrottlerConfig --custom-query "show global status like 'threads_running'" --threshold 40 --check-as-check-self commerce ``` -$ curl -s 'http://localhost:15000/throttler/throttle-app?app=test&ratio=0.25' + +In the above, we use `--check-as-check-self` because we want the shard's `PRIMARY`'s metric (concurrent threads) to be the throttling factor. + +Return to default throttling metric (replication lag): + +```sh +$ vtctldclient UpdateThrottlerConfig --custom-query "" --threshold 15.0 --check-as-check-shard commerce +``` + +In the above, we use `--check-as-check-self` because we want the shard's replicas metric (lag) to be the throttling factor. + +Throttle a specific app, `vreplication`, so that `80%` of its eligible requests are denied (slowing it down to `20%` potential speed), auto-expiring after `30` minutes: + +```sh +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-ratio=0.8 --throttle-app-duration "30m" commerce +``` + +Unthrottle an app: + +```sh +$ vtctldclient UpdateThrottlerConfig --unthrottle-app "vreplication" commerce +``` + +An altrnative method to unthrottle is to set a throttling rule that expires immediately: + +```sh +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-duration 0 commerce +``` + +Fully throttle all Online DDL (schema changes) for the next hour and a half: + +```sh +$ vtctldclient UpdateThrottlerConfig --throttle-app "online-ddl" --throttle-app-ratio=1.0 --throttle-app-duration "1h30m" commerce +``` + +Exempt `vreplication` from being throttled, even if otherwise the metrics are past the throttler threshold (e.g. replication lag is high): + +```sh +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-duration "30m" --throttle-app-exempt commerce +``` + +Use the above with great care. Exempting one app can cause starvation to all other apps. Consider, for example, the common use case where throttling is based on replication lag. By exempting `vreplication`, it is free to grab all the resources it wants. It is possible and likely that it will drive replication lag higher than the threshold, which means all other throttler clients will be fully throttled and with all requests rejected. + +Exemption times out just as other throttling rules. To remove an exemption, any of the following will do: + +```sh +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-exempt=false commerce +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-duration "0" commerce +$ vtctldclient UpdateThrottlerConfig --unthrottle-app "vreplication" commerce ``` -{{< /info >}} ### Information +Throttler configuration is part of the `Keyspace` entry: + +```sh +$ vtctldclient GetKeyspace commerce +``` + +```json +{ + "name": "commerce", + "keyspace": { + "served_froms": [], + "keyspace_type": 0, + "base_keyspace": "", + "snapshot_time": null, + "durability_policy": "semi_sync", + "throttler_config": { + "enabled": true, + "threshold": 15.0, + "custom_query": "", + "check_as_check_self": false, + "throttled_apps": { + "vreplication": { + "name": "vreplication", + "ratio": 0.5, + "expires_at": { + "seconds": "1687864412", + "nanoseconds": 142717831 + } + } + } + }, + "sidecar_db_name": "_vt" + } +} +``` + - `/throttler/status` endpoint. This is useful for monitoring and management purposes. -- `/throttler/throttled-apps` endpoint, listing all apps for which there's a throttling instruction Vitess also accepts the SQL syntax: @@ -310,22 +375,6 @@ This API call returns the following JSON object: The replica tablet only presents `mysql/self` metric (measurement of its own backend MySQL's lag). It does not serve checks for the shard in general. -#### Example: throttled-apps - -```sh -$ curl -s 'http://127.0.0.1:15100/throttler/throttled-apps' -``` - -```json -[ - { - "AppName": "always-throttled-app", - "ExpireAt": "2032-05-08T11:33:19.683767744Z", - "Ratio": 1 - } -] -``` - ## Resources - [freno](https://github.com/github/freno) project page diff --git a/content/en/docs/18.0/reference/features/topology-service.md b/content/en/docs/18.0/reference/features/topology-service.md index 4c155015a..8ec6e1f8a 100644 --- a/content/en/docs/18.0/reference/features/topology-service.md +++ b/content/en/docs/18.0/reference/features/topology-service.md @@ -95,7 +95,7 @@ tasks cannot concurrently alter the data. ### VSchema data The VSchema data contains sharding and routing information for -the [VTGate V3](https://github.com/vitessio/vitess/blob/main/doc/VTGateV3Features.md) API. +the [VTGate API](https://github.com/vitessio/vitess/blob/main/doc/design-docs/VTGateV3Features.md). ## Local data @@ -360,7 +360,7 @@ others wait for files with older ModRevisions to disappear. Leader elections also use a subdirectory, named after the election Name, and use a similar method as the locks, with ephemeral files. -We store the proto3 binary data for each object (as the v3 API allows us to store +We store the proto3 binary data for each object (as the API allows us to store binary data). Note that this means that if you want to interact with etcd using the `etcdctl` tool, you will have to tell it to use the v3 API, e.g.: diff --git a/content/en/docs/18.0/reference/features/vindexes.md b/content/en/docs/18.0/reference/features/vindexes.md index 04d5fc6e1..fb5ebc87f 100644 --- a/content/en/docs/18.0/reference/features/vindexes.md +++ b/content/en/docs/18.0/reference/features/vindexes.md @@ -149,7 +149,7 @@ Vindexes are defined in the [VSchema](../vschema/) inside the `Vindexes` section In the above case, the name of the vindex is `name_keyspace_idx`. It is of type `lookup`, and it is owned by the `user` table. -Every Vindex has an optional `params` section that contains a map of string key-value pairs. The keys and values differ depending on the vindex type and are explained below. +Every Vindex has an optional `params` section that contains a map of string key-value pairs. The keys and values differ depending on the vindex type and are explained below. There is an optional fourth parameter: `batch_lookup`. To read more about how to use `batch_lookup` see our [Unique Lookup user guide](../../../user-guides/vschema-guide/unique-lookup/). @@ -322,3 +322,27 @@ hex_keyspace_id: d9e62c0ad204fe91658ecc758049e515 1 row in set (0.00 sec) ``` + +### Unknown Vindex parameters + +Most Vindexes will accept unknown parameters without complaint. For example, the following `lookup` Vindex can be applied without error: + +```json + "name_keyspace_idx": { + "type": "lookup", + "params": { + "table": "name_keyspace_idx", + "from": "name", + "to": "keyspace_id", + "rear_lock": "none" + }, + "owner": "user" + } +``` + +In this example, the user intended to use `read_lock` but typed `rear_lock` by mistake. They will be in for an unpleasant surprise during the traffic peak and `rear_lock` does nothing to mitigate lock contention. + +To help users avoid these kinds of unpleasant surprises, Vindexes may expose unknown parameters in the following ways: + + * [As warnings](../../programs/vtctl/schema-version-permissions/#warnings) in the output of `ApplyVSchema`. + * As a [VTGate stat](../../../user-guides/configuration-basic/monitoring/#vindexunknownparameters) named `VindexUnknownParameters`. diff --git a/content/en/docs/18.0/reference/programs/vtbackup.md b/content/en/docs/18.0/reference/programs/vtbackup.md index df2f25388..afed9dc40 100644 --- a/content/en/docs/18.0/reference/programs/vtbackup.md +++ b/content/en/docs/18.0/reference/programs/vtbackup.md @@ -224,6 +224,7 @@ While it is running, `vtbackup` serves debugging info and metrics on port `15500 | --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 | +| --upgrade-safe | boolean | Whether to use innodb_fast_shutdown=0 for the backup so it is safe to use for MySQL upgrades | | --v | Level | log level for V logs | | -v, --version | | print binary version | | --vmodule | moduleSpec | comma-separated list of pattern=N settings for file-filtered logging | diff --git a/content/en/docs/18.0/reference/programs/vtctl/_index.md b/content/en/docs/18.0/reference/programs/vtctl/_index.md index b9809719e..53eca97e7 100644 --- a/content/en/docs/18.0/reference/programs/vtctl/_index.md +++ b/content/en/docs/18.0/reference/programs/vtctl/_index.md @@ -32,7 +32,7 @@ Note that wherever `vtctl` commands produced master or MASTER for tablet type, t | [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_primary=false] ` | +| [Backup](../vtctl/tablets#backup) | `Backup -- [--concurrency=4] [--allow_primary=false] [--upgrade-safe=false] ` | | [RestoreFromBackup](../vtctl/tablets#restorefrombackup) | `RestoreFromBackup ` | | [ReparentTablet](../vtctl/tablets#reparenttablet) | `ReparentTablet ` | @@ -55,7 +55,7 @@ Note that wherever `vtctl` commands produced master or MASTER for tablet type, t | [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_primary=false] ` | +| [BackupShard](../vtctl/shards#backupshard) | `BackupShard -- [--allow_primary=false] [--upgrade-safe=false] ` | | [RemoveBackup](../vtctl/shards#removebackup) | `RemoveBackup ` | | (DEPRECATED) [InitShardPrimary](../vtctl/shards#initshardprimary) | `InitShardPrimary -- [--force] [--wait_replicas_timeout=] ` | | [PlannedReparentShard](../vtctl/shards#plannedreparentshard) | `PlannedReparentShard -- --keyspace_shard= [--new_primary=] [--avoid_tablet=] [--wait_replicas_timeout=]` | @@ -99,7 +99,7 @@ Note that wherever `vtctl` commands produced master or MASTER for tablet type, t | [ReloadSchemaKeyspace](../vtctl/schema-version-permissions#reloadschemakeyspace) | `ReloadSchemaKeyspace -- [--concurrency=10] [--include_primary=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_replicas_timeout=10s] {--sql= \|\| --sql-file=} ` | +| [ApplySchema](../vtctl/schema-version-permissions#applyschema) | `ApplySchema -- [--wait_replicas_timeout=10s] {--sql= \|\| --sql-file=} ` | | [CopySchemaShard](../vtctl/schema-version-permissions#copyschemashard) | `CopySchemaShard -- [--tables=,,...] [--exclude_tables=,,...] [--include-views] [--skip-verify] [--wait_replicas_timeout=10s] { \|\| } ` | | [ValidateVersionShard](../vtctl/schema-version-permissions#validateversionshard) | `ValidateVersionShard ` | | [ValidateVersionKeyspace](../vtctl/schema-version-permissions#validateversionkeyspace) | `ValidateVersionKeyspace ` | @@ -157,7 +157,7 @@ Note that wherever `vtctl` commands produced master or MASTER for tablet type, t | Name | Example Usage | | :-------- | :--------------- | -| [UpdateThrottlerConfig](../vtctl/throttler#updatethrottlerconfig) | `UpdateThrottlerConfig -- [--enable\|--disable] [--threshold=] [--custom-query=] [--check-as-check-self\|--check-as-check-shard] ` +| [UpdateThrottlerConfig](../vtctl/throttler#updatethrottlerconfig) | `UpdateThrottlerConfig -- [--enable\|--disable] [--threshold=] [--custom-query=] [--check-as-check-self\|--check-as-check-shard] [--throttle-app|unthrottle-app=] [--throttle-app-ratio=] [--throttle-app-duration=] ` ## Options diff --git a/content/en/docs/18.0/reference/programs/vtctl/schema-version-permissions.md b/content/en/docs/18.0/reference/programs/vtctl/schema-version-permissions.md index 76744dfcc..c0ae4b558 100644 --- a/content/en/docs/18.0/reference/programs/vtctl/schema-version-permissions.md +++ b/content/en/docs/18.0/reference/programs/vtctl/schema-version-permissions.md @@ -153,13 +153,12 @@ Applies the schema change to the specified keyspace on all shards. The recommend #### Example -
ApplySchema -- [--allow_long_unavailability] [--wait_replicas_timeout=10s] [--ddl_strategy=] [--request_context=] [--skip_preflight] {--sql=<sql> || --sql-file=<filename>} <keyspace>
+
ApplySchema -- [--wait_replicas_timeout=10s] [--ddl_strategy=] [--request_context=] [--skip_preflight] {--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. Flag will be deprecated as the recommended way to run long migrations is via Online DDL. | | caller_id | string | Effective caller ID used for the operation and should map to an ACL name which grants this identity the necessary permissions to perform the operation (this is only necessary when strict table ACLs are used). | | ddl_strategy | string | Online DDL strategy, compatible with @@ddl_strategy session variable (examples: 'gh-ost', 'pt-osc', 'gh-ost --max-load=Threads_running=100' (default "direct"). | | request_context | string | For Only DDL, optionally supply a custom unique string used as context for the migration(s) in this command. By default a unique context is auto-generated by Vitess. | @@ -327,10 +326,14 @@ Applies the VTGate routing schema to the provided keyspace. Shows the result aft #### Errors -* The <keyspace> argument is required for the <ApplyVSchema> command This error occurs if the command is not called with exactly one argument. +* The <keyspace> argument is required for the <ApplyVSchema> command. This error occurs if the command is not called with exactly one argument. * Either the <vschema> or <vschema>File flag must be specified when calling the <ApplyVSchema> command. * If using a file you may need to pass the absolute path. +#### Warnings + +* In some cases, unknown params passed to Vindexes may be accepted but reported as warnings in the command response. + ### GetRoutingRules ``` diff --git a/content/en/docs/18.0/reference/programs/vtctl/shards.md b/content/en/docs/18.0/reference/programs/vtctl/shards.md index 5d6d82a47..39c4833e5 100644 --- a/content/en/docs/18.0/reference/programs/vtctl/shards.md +++ b/content/en/docs/18.0/reference/programs/vtctl/shards.md @@ -325,7 +325,7 @@ Lists all the backups for a shard. ### BackupShard ``` -BackupShard -- [--allow_primary=false] +BackupShard -- [--allow_primary=false] [--upgrade-safe=false] ``` ### RemoveBackup diff --git a/content/en/docs/18.0/reference/programs/vtctl/tablets.md b/content/en/docs/18.0/reference/programs/vtctl/tablets.md index d24a7cede..915415109 100644 --- a/content/en/docs/18.0/reference/programs/vtctl/tablets.md +++ b/content/en/docs/18.0/reference/programs/vtctl/tablets.md @@ -382,14 +382,14 @@ Stops mysqld and uses the [BackupEngine](../../../../user-guides/operating-vites #### Example -
Backup -- [--concurrency=4] <tablet alias>
+
Backup -- [--concurrency=4] [--upgrade-safe=false] <tablet alias>
#### Flags | Name | Type | Definition | | :-------- | :--------- | :--------- | | concurrency | Int | Specifies the number of compression/checksum jobs to run simultaneously | - +| upgrade-safe | Boolean | Whether to use innodb_fast_shutdown=0 for the backup so it is safe to use for MySQL upgrades | #### Arguments diff --git a/content/en/docs/18.0/reference/programs/vtctl/throttler.md b/content/en/docs/18.0/reference/programs/vtctl/throttler.md index f5b7bf767..49cd192d9 100644 --- a/content/en/docs/18.0/reference/programs/vtctl/throttler.md +++ b/content/en/docs/18.0/reference/programs/vtctl/throttler.md @@ -10,11 +10,11 @@ The following `vtctl` commands are available for controlling the tablet throttle ### UpdateThrottlerConfig -Update tablet throttler configuration for all tablets of a given throttler. +Update tablet throttler configuration for all tablets of a given keyspace. #### Usage -
UpdateThrottlerConfig -- [--enable|--disable] [--threshold=<float64>] [--custom-query=<query>] [--check-as-check-self|--check-as-check-shard] <keyspace>
+
UpdateThrottlerConfig -- [--enable|--disable] [--threshold=<float64>] [--custom-query=<query>] [--check-as-check-self|--check-as-check-shard] [--throttle-app|unthrottle-app=<name>] [--throttle-app-ratio=<float, range [0..1]>] [--throttle-app-duration=<duration>] <keyspace>
#### Examples @@ -22,6 +22,10 @@ Update tablet throttler configuration for all tablets of a given throttler. ```UpdateThrottlerConfig -- --disable commerce``` +```UpdateThrottlerConfig -- --throttle-app="vreplication" --throttle-app-ratio=0.5 --throttle-app-duration="30m" commerce``` + +```UpdateThrottlerConfig -- --unthrottle-app="vreplication" commerce``` + #### Flags diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/_index.md b/content/en/docs/18.0/reference/programs/vtctldclient/_index.md index 2f6fe5c9d..1f283e23b 100644 --- a/content/en/docs/18.0/reference/programs/vtctldclient/_index.md +++ b/content/en/docs/18.0/reference/programs/vtctldclient/_index.md @@ -66,6 +66,7 @@ vtctldclient [flags] * [vtctldclient GetVSchema](./vtctldclient_getvschema/) - Prints a JSON representation of a keyspace's topo record. * [vtctldclient GetWorkflows](./vtctldclient_getworkflows/) - Gets all vreplication workflows (Reshard, MoveTables, etc) in the given keyspace. * [vtctldclient LegacyVtctlCommand](./vtctldclient_legacyvtctlcommand/) - Invoke a legacy vtctlclient command. Flag parsing is best effort. +* [vtctldclient MoveTables](./vtctldclient_movetables/) - Perform commands related to moving tables from a source keyspace to a target keyspace. * [vtctldclient PingTablet](./vtctldclient_pingtablet/) - Checks that the specified tablet is awake and responding to RPCs. This command can be blocked by other in-flight operations. * [vtctldclient PlannedReparentShard](./vtctldclient_plannedreparentshard/) - Reparents the shard to a new primary, or away from an old primary. Both the old and new primaries must be up and running. * [vtctldclient RebuildKeyspaceGraph](./vtctldclient_rebuildkeyspacegraph/) - Rebuilds the serving data for the keyspace(s). This command may trigger an update to all connected clients. @@ -102,5 +103,5 @@ vtctldclient [flags] * [vtctldclient ValidateShard](./vtctldclient_validateshard/) - Validates that all nodes reachable from the specified shard are consistent. * [vtctldclient ValidateVersionKeyspace](./vtctldclient_validateversionkeyspace/) - Validates that the version on the primary tablet of shard 0 matches all of the other tablets in the keyspace. * [vtctldclient ValidateVersionShard](./vtctldclient_validateversionshard/) - Validates that the version on the primary matches all of the replicas. -* [vtctldclient workflow](./vtctldclient_workflow/) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace +* [vtctldclient Workflow](./vtctldclient_workflow/) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_ApplySchema.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_ApplySchema.md index 237b4b0ef..52127eb9d 100644 --- a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_ApplySchema.md +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_ApplySchema.md @@ -23,13 +23,12 @@ For --sql, semi-colons and repeated values may be mixed, for example: ApplySchema --sql "CREATE TABLE my_table" --sql "CREATE TABLE my_other_table" ``` -vtctldclient ApplySchema [--allow-long-unavailability] [--ddl-strategy ] [--uuid ...] [--migration-context ] [--wait-replicas-timeout ] [--caller-id ] {--sql-file | --sql } +vtctldclient ApplySchema [--ddl-strategy ] [--uuid ...] [--migration-context ] [--wait-replicas-timeout ] [--caller-id ] {--sql-file | --sql } ``` ### Options ``` - --allow-long-unavailability Allow large schema changes which incur a longer unavailability of the database. --caller-id string Effective caller ID used for the operation and should map to an ACL name which grants this identity the necessary permissions to perform the operation (this is only necessary when strict table ACLs are used). --ddl-strategy string Online DDL strategy, compatible with @@ddl_strategy session variable (examples: 'gh-ost', 'pt-osc', 'gh-ost --max-load=Threads_running=100'. (default "direct") -h, --help help for ApplySchema diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Backup.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Backup.md index 6f3048a73..7220aa66e 100644 --- a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Backup.md +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Backup.md @@ -7,15 +7,17 @@ series: vtctldclient Uses the BackupStorage service on the given tablet to create and store a new backup. ``` -vtctldclient Backup [--concurrency ] [--allow-primary] +vtctldclient Backup [--concurrency ] [--allow-primary] [--incremental-from-pos=|auto] [--upgrade-safe] ``` ### Options ``` - --allow-primary Allow the primary of a shard to be used for the backup. WARNING: If using the builtin backup engine, this will shutdown mysqld on the primary and stop writes for the duration of the backup. - --concurrency uint Specifies the number of compression/checksum jobs to run simultaneously. (default 4) - -h, --help help for Backup + --allow-primary Allow the primary of a shard to be used for the backup. WARNING: If using the builtin backup engine, this will shutdown mysqld on the primary and stop writes for the duration of the backup. + --concurrency uint Specifies the number of compression/checksum jobs to run simultaneously. (default 4) + -h, --help help for Backup + --incremental-from-pos string Position of previous backup. Default: empty. If given, then this backup becomes an incremental backup from given position. If value is 'auto', backup taken from last successful backup position + --upgrade-safe Whether to use innodb_fast_shutdown=0 for the backup so it is safe to use for MySQL upgrades. ``` ### Options inherited from parent commands diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_BackupShard.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_BackupShard.md index 93ae5e7ed..6a637c4b1 100644 --- a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_BackupShard.md +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_BackupShard.md @@ -13,7 +13,7 @@ Finds the most up-to-date REPLICA, RDONLY, or SPARE tablet in the given shard an If no replica-type tablet can be found, the backup can be taken on the primary if --allow-primary is specified. ``` -vtctldclient BackupShard [--concurrency ] [--allow-primary] +vtctldclient BackupShard [--concurrency ] [--allow-primary] [--upgrade-safe] ``` ### Options @@ -22,6 +22,7 @@ vtctldclient BackupShard [--concurrency ] [--allow-primary] -i, --ignore-replicas strings Comma-separated, repeated list of replica tablet aliases to ignore during the emergency reparent. --new-primary string Alias of a tablet that should be the new primary. If not specified, the vtctld will select the best candidate to promote. --prevent-cross-cell-promotion Only promotes a new primary from the same cell as the previous primary. + --wait-for-all-tablets Should ERS wait for all the tablets to respond. Useful when all the tablets are reachable. --wait-replicas-timeout duration Time to wait for replicas to catch up in reparenting. (default 15s) ``` diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/_index.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/_index.md new file mode 100644 index 000000000..73dfa1791 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/_index.md @@ -0,0 +1,42 @@ +--- +title: MoveTables +series: vtctldclient +--- +## vtctldclient MoveTables + +Perform commands related to moving tables from a source keyspace to a target keyspace. + +### Synopsis + +MoveTables commands: Create, Show, Status, SwitchTraffic, ReverseTraffic, Stop, Start, Cancel, and Delete. +See the --help output for each command for more details. + +### Options + +``` + --format string The format of the output; supported formats are: text,json (default "text") + -h, --help help for MoveTables + --target-keyspace string Keyspace where the tables are being moved to and where the workflow exists (required) + -w, --workflow string The workflow you want to perform the command on (required) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. +* [vtctldclient MoveTables cancel](./vtctldclient_movetables_cancel/) - Cancel a MoveTables VReplication workflow. +* [vtctldclient MoveTables complete](./vtctldclient_movetables_complete/) - Complete a MoveTables VReplication workflow. +* [vtctldclient MoveTables create](./vtctldclient_movetables_create/) - Create and optionally run a MoveTables VReplication workflow. +* [vtctldclient MoveTables reversetraffic](./vtctldclient_movetables_reversetraffic/) - Reverse traffic for a MoveTables VReplication workflow. +* [vtctldclient MoveTables show](./vtctldclient_movetables_show/) - Show the details for a MoveTables VReplication workflow. +* [vtctldclient MoveTables start](./vtctldclient_movetables_start/) - Start the MoveTables workflow. +* [vtctldclient MoveTables status](./vtctldclient_movetables_status/) - Show the current status for a MoveTables VReplication workflow. +* [vtctldclient MoveTables stop](./vtctldclient_movetables_stop/) - Stop a MoveTables workflow. +* [vtctldclient MoveTables switchtraffic](./vtctldclient_movetables_switchtraffic/) - Switch traffic for a MoveTables VReplication workflow. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_cancel.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_cancel.md new file mode 100644 index 000000000..92962ae16 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_cancel.md @@ -0,0 +1,38 @@ +--- +title: MoveTables cancel +series: vtctldclient +--- +## vtctldclient MoveTables cancel + +Cancel a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables cancel +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer cancel +``` + +### Options + +``` + -h, --help help for cancel + --keep-data Keep the partially copied table data from the MoveTables workflow in the target keyspace + --keep-routing-rules Keep the routing rules created for the MoveTables workflow +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) + --target-keyspace string Keyspace where the tables are being moved to and where the workflow exists (required) +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_complete.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_complete.md new file mode 100644 index 000000000..cbc708191 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_complete.md @@ -0,0 +1,40 @@ +--- +title: MoveTables complete +series: vtctldclient +--- +## vtctldclient MoveTables complete + +Complete a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables complete +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer complete +``` + +### Options + +``` + --dry-run Print the actions that would be taken and report any known errors that would have occurred + -h, --help help for complete + --keep-data Keep the original source table data that was copied by the MoveTables workflow + --keep-routing-rules Keep the routing rules in place that direct table traffic from the source keyspace to the target keyspace of the MoveTables workflow + --rename-tables Keep the original source table data that was copied by the MoveTables workflow, but rename each table to '__old' +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) + --target-keyspace string Keyspace where the tables are being moved to and where the workflow exists (required) +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md new file mode 100644 index 000000000..4a9aa52a5 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md @@ -0,0 +1,47 @@ +--- +title: MoveTables create +series: vtctldclient +--- +## vtctldclient MoveTables create + +Create and optionally run a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables create +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer create --source-keyspace commerce --cells zone1 --cells zone2 --tablet-types replica +``` + +### Options + +``` + --all-tables Copy all tables from the source + --auto-start Start the MoveTables workflow after creating it (default true) + -c, --cells strings Cells and/or CellAliases to copy table data from + --exclude-tables strings Source tables to exclude from copying + -h, --help help for create + --on-ddl string What to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE (default "IGNORE") + --source-keyspace string Keyspace where the tables are being moved from (required) + --source-shards strings Source shards to copy data from when performing a partial MoveTables (experimental) + --stop-after-copy Stop the MoveTables workflow after it's finished copying the existing rows and before it starts replicating changes + --tables strings Source tables to copy + --tablet-types strings Source tablet types to replicate table data from (e.g. PRIMARY,REPLICA,RDONLY) + --tablet-types-in-preference-order When performing source tablet selection, look for candidates in the type order as they are listed in the tablet-types flag (default true) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) + --target-keyspace string Keyspace where the tables are being moved to and where the workflow exists (required) +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md new file mode 100644 index 000000000..d608be3e1 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md @@ -0,0 +1,42 @@ +--- +title: MoveTables reversetraffic +series: vtctldclient +--- +## vtctldclient MoveTables reversetraffic + +Reverse traffic for a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables reversetraffic +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer reversetraffic +``` + +### Options + +``` + -c, --cells strings Cells and/or CellAliases to switch traffic in + --dry-run Print the actions that would be taken and report any known errors that would have occurred + --enable-reverse-replication Setup replication going back to the original source keyspace to support rolling back the traffic cutover (default true) + -h, --help help for reversetraffic + --max-replication-lag-allowed duration Allow traffic to be switched only if VReplication lag is below this (default 30s) + --tablet-types strings Tablet types to switch traffic for + --timeout duration Specifies the maximum time to wait, in seconds, for VReplication to catch up on primary tablets. The traffic switch will be cancelled on timeout. (default 30s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) + --target-keyspace string Keyspace where the tables are being moved to and where the workflow exists (required) +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_show.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_show.md new file mode 100644 index 000000000..2f6598cbc --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_show.md @@ -0,0 +1,36 @@ +--- +title: MoveTables show +series: vtctldclient +--- +## vtctldclient MoveTables show + +Show the details for a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables show +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer show +``` + +### Options + +``` + -h, --help help for show +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) + --target-keyspace string Keyspace where the tables are being moved to and where the workflow exists (required) +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_start.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_start.md new file mode 100644 index 000000000..139ef73ee --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_start.md @@ -0,0 +1,36 @@ +--- +title: MoveTables start +series: vtctldclient +--- +## vtctldclient MoveTables start + +Start the MoveTables workflow. + +``` +vtctldclient MoveTables start +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer start +``` + +### Options + +``` + -h, --help help for start +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) + --target-keyspace string Keyspace where the tables are being moved to and where the workflow exists (required) +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_status.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_status.md new file mode 100644 index 000000000..e94b350fb --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_status.md @@ -0,0 +1,36 @@ +--- +title: MoveTables status +series: vtctldclient +--- +## vtctldclient MoveTables status + +Show the current status for a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables status +``` + +### Examples + +``` +vtctldclient --server localhost:15999 MoveTables --workflow commerce2customer --target-keyspace customer status +``` + +### Options + +``` + -h, --help help for status +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) + --target-keyspace string Keyspace where the tables are being moved to and where the workflow exists (required) +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_stop.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_stop.md new file mode 100644 index 000000000..9dfff8b29 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_stop.md @@ -0,0 +1,36 @@ +--- +title: MoveTables stop +series: vtctldclient +--- +## vtctldclient MoveTables stop + +Stop a MoveTables workflow. + +``` +vtctldclient MoveTables stop +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer stop +``` + +### Options + +``` + -h, --help help for stop +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) + --target-keyspace string Keyspace where the tables are being moved to and where the workflow exists (required) +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md new file mode 100644 index 000000000..b8bb22ce7 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md @@ -0,0 +1,41 @@ +--- +title: MoveTables switchtraffic +series: vtctldclient +--- +## vtctldclient MoveTables switchtraffic + +Switch traffic for a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables switchtraffic +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer switchtraffic --tablet-types "replica,rdonly" +``` + +### Options + +``` + -c, --cells strings Cells and/or CellAliases to switch traffic in + --dry-run Print the actions that would be taken and report any known errors that would have occurred + -h, --help help for switchtraffic + --max-replication-lag-allowed duration Allow traffic to be switched only if VReplication lag is below this (default 30s) + --tablet-types strings Tablet types to switch traffic for + --timeout duration Specifies the maximum time to wait, in seconds, for VReplication to catch up on primary tablets. The traffic switch will be cancelled on timeout. (default 30s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) + --target-keyspace string Keyspace where the tables are being moved to and where the workflow exists (required) +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_RestoreFromBackup.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_RestoreFromBackup.md index 6e41b8ad6..842bc2879 100644 --- a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_RestoreFromBackup.md +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_RestoreFromBackup.md @@ -7,14 +7,17 @@ series: vtctldclient Stops mysqld on the specified tablet and restores the data from either the latest backup or closest before `backup-timestamp`. ``` -vtctldclient RestoreFromBackup [--backup-timestamp|-t ] +vtctldclient RestoreFromBackup [--backup-timestamp|-t ] [--restore-to-pos ] [--dry-run] ``` ### Options ``` - -t, --backup-timestamp string Use the backup taken at, or closest before, this timestamp. Omit to use the latest backup. Timestamp format is "YYYY-mm-DD.HHMMSS". - -h, --help help for RestoreFromBackup + -t, --backup-timestamp string Use the backup taken at, or closest before, this timestamp. Omit to use the latest backup. Timestamp format is "YYYY-mm-DD.HHMMSS". + --dry-run Only validate restore steps, do not actually restore data + -h, --help help for RestoreFromBackup + --restore-to-pos string Run a point in time recovery that ends with the given position. This will attempt to use one full backup followed by zero or more incremental backups + --restore-to-timestamp 2006-01-02T15:04:05Z07:00 Run a point in time recovery that restores up to, and excluding, given timestamp in RFC3339 format (2006-01-02T15:04:05Z07:00). This will attempt to use one full backup followed by zero or more incremental backups ``` ### Options inherited from parent commands diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_UpdateThrottlerConfig.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_UpdateThrottlerConfig.md index 0314de1b4..1a973387c 100644 --- a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_UpdateThrottlerConfig.md +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_UpdateThrottlerConfig.md @@ -7,19 +7,23 @@ series: vtctldclient Update the tablet throttler configuration for all tablets in the given keyspace (across all cells) ``` -vtctldclient UpdateThrottlerConfig [--enable|--disable] [--threshold=] [--custom-query=] [--check-as-check-self|--check-as-check-shard] +vtctldclient UpdateThrottlerConfig [--enable|--disable] [--threshold=] [--custom-query=] [--check-as-check-self|--check-as-check-shard] [--throttle-app|unthrottle-app=] [--throttle-app-ratio=] [--throttle-app-duration=] ``` ### Options ``` - --check-as-check-self /throttler/check requests behave as is /throttler/check-self was called - --check-as-check-shard use standard behavior for /throttler/check requests - --custom-query string custom throttler check query - --disable Disable the throttler - --enable Enable the throttler - -h, --help help for UpdateThrottlerConfig - --threshold float threshold for the either default check (replication lag seconds) or custom check + --check-as-check-self /throttler/check requests behave as is /throttler/check-self was called + --check-as-check-shard use standard behavior for /throttler/check requests + --custom-query string custom throttler check query + --disable Disable the throttler + --enable Enable the throttler + -h, --help help for UpdateThrottlerConfig + --threshold float threshold for the either default check (replication lag seconds) or custom check + --throttle-app string an app name to throttle + --throttle-app-duration duration duration after which throttled app rule expires (app specififed in --throttled-app) (default 1h0m0s) + --throttle-app-ratio float ratio to throttle app (app specififed in --throttled-app) (default 1) + --unthrottle-app string an app name to unthrottle ``` ### Options inherited from parent commands diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/_index.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/_index.md new file mode 100644 index 000000000..292d2489c --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/_index.md @@ -0,0 +1,41 @@ +--- +title: Workflow +series: vtctldclient +--- +## vtctldclient Workflow + +Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + +### Synopsis + +Workflow commands: List, Show, Start, Stop, Update, and Delete. +See the --help output for each command for more details. + +``` +vtctldclient Workflow --keyspace [command] [command-flags] +``` + +### Options + +``` + -h, --help help for Workflow + -k, --keyspace string Keyspace context for the workflow (required) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. +* [vtctldclient Workflow delete](./vtctldclient_workflow_delete/) - Delete a VReplication workflow. +* [vtctldclient Workflow list](./vtctldclient_workflow_list/) - List the VReplication workflows in the given keyspace. +* [vtctldclient Workflow show](./vtctldclient_workflow_show/) - Show the details for a VReplication workflow. +* [vtctldclient Workflow start](./vtctldclient_workflow_start/) - Start a VReplication workflow. +* [vtctldclient Workflow stop](./vtctldclient_workflow_stop/) - Stop a VReplication workflow. +* [vtctldclient Workflow update](./vtctldclient_workflow_update/) - Update the configuration parameters for a VReplication workflow. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_delete.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_delete.md new file mode 100644 index 000000000..a26f82df3 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_delete.md @@ -0,0 +1,39 @@ +--- +title: Workflow delete +series: vtctldclient +--- +## vtctldclient Workflow delete + +Delete a VReplication workflow. + +``` +vtctldclient Workflow delete +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer delete --workflow commerce2customer +``` + +### Options + +``` + -h, --help help for delete + --keep-data Keep the partially copied table data from the workflow in the target keyspace + --keep-routing-rules Keep the routing rules created for the workflow + -w, --workflow string The workflow you want to delete (required) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_list.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_list.md new file mode 100644 index 000000000..b298632f3 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_list.md @@ -0,0 +1,36 @@ +--- +title: Workflow list +series: vtctldclient +--- +## vtctldclient Workflow list + +List the VReplication workflows in the given keyspace. + +``` +vtctldclient Workflow list +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer list +``` + +### Options + +``` + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_show.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_show.md new file mode 100644 index 000000000..891ef0987 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_show.md @@ -0,0 +1,37 @@ +--- +title: Workflow show +series: vtctldclient +--- +## vtctldclient Workflow show + +Show the details for a VReplication workflow. + +``` +vtctldclient Workflow show +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer show --workflow commerce2customer +``` + +### Options + +``` + -h, --help help for show + -w, --workflow string The workflow you want the details for (required) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_start.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_start.md new file mode 100644 index 000000000..eca3a0002 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_start.md @@ -0,0 +1,37 @@ +--- +title: Workflow start +series: vtctldclient +--- +## vtctldclient Workflow start + +Start a VReplication workflow. + +``` +vtctldclient Workflow start +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer start --workflow commerce2customer +``` + +### Options + +``` + -h, --help help for start + -w, --workflow string The workflow you want to start (required) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_stop.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_stop.md new file mode 100644 index 000000000..f6ff45342 --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_stop.md @@ -0,0 +1,37 @@ +--- +title: Workflow stop +series: vtctldclient +--- +## vtctldclient Workflow stop + +Stop a VReplication workflow. + +``` +vtctldclient Workflow stop +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer stop --workflow commerce2customer +``` + +### Options + +``` + -h, --help help for stop + -w, --workflow string The workflow you want to stop (required) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_update.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_update.md new file mode 100644 index 000000000..7c72a82aa --- /dev/null +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_update.md @@ -0,0 +1,41 @@ +--- +title: Workflow update +series: vtctldclient +--- +## vtctldclient Workflow update + +Update the configuration parameters for a VReplication workflow. + +``` +vtctldclient Workflow update +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer update --workflow commerce2customer --cells zone1 --cells zone2 -c "zone3,zone4" -c zone5 +``` + +### Options + +``` + -c, --cells strings New Cell(s) or CellAlias(es) (comma-separated) to replicate from + -h, --help help for update + --on-ddl string New instruction on what to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE + -t, --tablet-types strings New source tablet types to replicate from (e.g. PRIMARY,REPLICA,RDONLY) + --tablet-types-in-order When performing source tablet selection, look for candidates in the type order as they are listed in the tablet-types flag (default true) + -w, --workflow string The workflow you want to update (required) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_workflow.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_workflow.md deleted file mode 100644 index 32ef15409..000000000 --- a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_workflow.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: workflow -series: vtctldclient ---- -## vtctldclient workflow - -Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace - -``` -vtctldclient workflow -``` - -### Options - -``` - -h, --help help for workflow - -k, --keyspace string Keyspace context for the workflow (required) -``` - -### Options inherited from parent commands - -``` - --action_timeout duration timeout for the total command (default 1h0m0s) - --server string server to use for connection (required) -``` - -### SEE ALSO - -* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. -* [vtctldclient workflow update](./vtctldclient_workflow_update/) - Update the configuration parameters for a VReplication workflow - diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_workflow_update.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_workflow_update.md deleted file mode 100644 index cfb35bc0d..000000000 --- a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_workflow_update.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: workflow_update -series: vtctldclient ---- -## vtctldclient workflow update - -Update the configuration parameters for a VReplication workflow - -``` -vtctldclient workflow update -``` - -### Examples - -``` -vtctldclient --server=localhost:15999 workflow --keyspace=customer update --workflow=commerce2customer --cells "zone1" --cells "zone2" -c "zone3,zone4" -c "zone5" -``` - -### Options - -``` - -c, --cells strings New Cell(s) or CellAlias(es) (comma-separated) to replicate from - -h, --help help for update - --on-ddl string New instruction on what to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE - -t, --tablet-types strings New source tablet types to replicate from (e.g. PRIMARY,REPLICA,RDONLY) - -w, --workflow string The workflow you want to update (required) -``` - -### Options inherited from parent commands - -``` - --action_timeout duration timeout for the total command (default 1h0m0s) - -k, --keyspace string Keyspace context for the workflow (required) - --server string server to use for connection (required) -``` - -### SEE ALSO - -* [vtctldclient workflow](./vtctldclient_workflow/) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace - diff --git a/content/en/docs/18.0/reference/programs/vtexplain.md b/content/en/docs/18.0/reference/programs/vtexplain.md index 4f2d17551..3fc3667de 100644 --- a/content/en/docs/18.0/reference/programs/vtexplain.md +++ b/content/en/docs/18.0/reference/programs/vtexplain.md @@ -28,24 +28,24 @@ vtexplain -- -shards 128 --vschema-file vschema.json --schema-file schema.sql -- The following parameters apply to `mysqlctl`: -| Name | Type | Definition | -|:-----------------------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------| -| --dbname | string | Optional database target to override normal routing | -| --execution-mode | string | The execution mode to simulate -- must be set to multi, legacy-autocommit, or twopc (default "multi") | -| --ks-shard-map | string | JSON map of keyspace name -> shard name -> ShardReference object. The inner map is the same as the output of FindAllShardsInKeyspace | -| --ks-shard-map-file | string | File containing json blob of keyspace name -> shard name -> ShardReference object | -| --mysql_server_version | string | MySQL server version to advertise. (default "8.0.30-Vitess") | -| --normalize | boolean | Whether to enable vtgate normalization | -| --output-mode | string | Output in human-friendly text or json (default "text") | -| --planner-version | string | Sets the query planner version to use when generating the explain output. Valid values are V3 and Gen4. An empty value will use VTGate's default planner | -| --replication-mode | string | The replication mode to simulate -- must be set to either ROW or STATEMENT (default "ROW") | -| --schema | string | The SQL table schema | -| --schema-file | string | Identifies the file that contains the SQL table schema | -| --shards | int | Number of shards per keyspace. Passing --ks-shard-map/--ks-shard-map-file causes this flag to be ignored. (default 2) | -| --sql | string | A list of semicolon-delimited SQL commands to analyze | -| --sql-file | string | Identifies the file that contains the SQL commands to analyze | -| --vschema | string | Identifies the VTGate routing schema | -| --vschema-file | string | Identifies the VTGate routing schema file | +| Name | Type | Definition | +|:-----------------------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------| +| --dbname | string | Optional database target to override normal routing | +| --execution-mode | string | The execution mode to simulate -- must be set to multi, legacy-autocommit, or twopc (default "multi") | +| --ks-shard-map | string | JSON map of keyspace name -> shard name -> ShardReference object. The inner map is the same as the output of FindAllShardsInKeyspace | +| --ks-shard-map-file | string | File containing json blob of keyspace name -> shard name -> ShardReference object | +| --mysql_server_version | string | MySQL server version to advertise. (default "8.0.30-Vitess") | +| --normalize | boolean | Whether to enable vtgate normalization | +| --output-mode | string | Output in human-friendly text or json (default "text") | +| --planner-version | string | Sets the default planner to use. Valid values are: Gen4, Gen4Greedy, Gen4Left2Right | +| --replication-mode | string | The replication mode to simulate -- must be set to either ROW or STATEMENT (default "ROW") | +| --schema | string | The SQL table schema | +| --schema-file | string | Identifies the file that contains the SQL table schema | +| --shards | int | Number of shards per keyspace. Passing --ks-shard-map/--ks-shard-map-file causes this flag to be ignored. (default 2) | +| --sql | string | A list of semicolon-delimited SQL commands to analyze | +| --sql-file | string | Identifies the file that contains the SQL commands to analyze | +| --vschema | string | Identifies the VTGate routing schema | +| --vschema-file | string | Identifies the VTGate routing schema file |
diff --git a/content/en/docs/18.0/reference/programs/vtgate.md b/content/en/docs/18.0/reference/programs/vtgate.md index 566f920a0..b0a5fdda0 100644 --- a/content/en/docs/18.0/reference/programs/vtgate.md +++ b/content/en/docs/18.0/reference/programs/vtgate.md @@ -30,208 +30,210 @@ vtgate \ The following global options apply to `vtgate`: -| Name | Type | Definition | -|:-----------------------------------------------------------------|:----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| --allowed_tablet_types | Strings | Specifies the tablet types this vtgate is allowed to route queries to. Should be provided as a comma-separated set of tablet types. | -| --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 PRIMARY vttablet when draining the buffer. (default 1) | -| --buffer_implementation | String | Allowed values: healthcheck (legacy implementation), keyspace_events (default) (default "keyspace_events") | -| --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 1000) | -| --buffer_window | Duration | Duration for how long a request should be buffered at most. (default 10s) | -| --catch-sigpipe | Boolean | catch and ignore SIGPIPE on stdout and stderr if specified | -| --cell | String | | | cell to use | -| --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. | -| --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 | -| --dbddl_plugin | String | controls how to handle CREATE/DROP DATABASE. use it if you are using your own database provisioning service (default "fail") | -| --ddl_strategy | String | Set default strategy for DDL statements. Override with @@ddl_strategy session variable (default "direct") | -| --default_tablet_type | Topodatapb.TabletType | The default tablet type to set for queries, when one is not explicitly selected. (default PRIMARY) | -| --discovery_high_replication_lag_minimum_serving | Duration | Threshold above which replication lag is considered too high when applying the min_number_serving_vttablets flag. (default 2h0m0s) | -| --discovery_low_replication_lag | Duration | Threshold below which replication lag is considered low enough to be healthy. (default 30s) | -| --emit_stats | Boolean | If set, emit stats to push-based monitoring and stats backends | -| --enable-partial-keyspace-migration | Boolean | (Experimental) Follow shard routing rules: enable only while migrating a keyspace shard by shard. See documentation on Partial MoveTables for more. (default false) | -| --enable-views | Boolean | Enable views support in vtgate. | -| --enable_buffer | Boolean | Enable buffering (stalling) of primary traffic during failovers. | -| --enable_buffer_dry_run | Boolean | Detect and log failover events, but do not actually buffer requests. | -| --enable_direct_ddl | Boolean | Allow users to submit direct DDL statements (default true) | -| --enable_online_ddl | Boolean | Allow users to submit, review and control Online DDL (default true) | -| --enable_set_var | Boolean | This will enable the use of MySQL's SET_VAR query hint for certain system variables instead of using reserved connections (default true) | -| --enable_system_settings | Boolean | This will enable the system settings to be changed per session at the database connection level (default true) | -| --foreign_key_mode | String | This is to provide how to handle foreign key constraint in create/alter table. Valid values are: allow, disallow (default "allow") | -| --gate_query_cache_lfu | Boolean | gate server cache algorithm. when set to true, a new cache algorithm based on a TinyLFU admission policy will be used to improve cache behavior and prevent pollution from sparse queries (default true) | -| --gate_query_cache_memory | Int | gate server query cache size in bytes, maximum amount of memory 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 33554432) | -| --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 cache. This config controls the expected amount of unique entries in the cache. (default 5000) | -| --gateway_initial_tablet_timeout | Duration | At startup, the tabletGateway will wait up to this duration to get at least one tablet per keyspace/shard/tablet type (default 30s) | -| --grpc-use-effective-groups | Boolean | If set, and SSL is not used, will set the immediate caller's security groups from the effective caller id's groups. | -| --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 | server CA to use for gRPC connections, requires TLS, and enforces client certificate check | -| --grpc_cert | String | server certificate to use for gRPC connections, requires grpc_key, enables TLS | -| --grpc_compression | String | Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy | -| --grpc_crl | String | path to a certificate revocation list in PEM format, client certificates will be further verified against this file during TLS handshake | -| --grpc_enable_optional_tls | Boolean | enable optional TLS mode when a server accepts both TLS and plain-text connections on the same port | -| --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 | server private key to use for gRPC connections, 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. If zero, do not listen. | -| --grpc_prometheus | Boolean | Enable gRPC monitoring with Prometheus. | -| --grpc_server_ca | String | path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients | -| --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 10s) | -| --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. | -| --grpc-use-static-authentication-callerid | boolean | If set, will set the immediate caller id to the username authenticated by the static auth plugin. | -| --healthcheck_retry_delay | Duration | health check retry delay (default 2ms) | -| --healthcheck_timeout | Duration | the health check timeout period (default 1m0s) | -| -h, --help | Boolean | display usage and exit | -| --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 | Strings | 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 vttablets for serving. (default true) | -| --lock-timeout | Duration | Maximum time for which a shard/keyspace lock can be acquired for (default 45s) | -| --lock_heartbeat_time | Duration | If there is lock function used. This will keep the lock connection active by using this heartbeat (default 5s) | -| --log_backtrace_at | TraceLocation | when logging hits line file:N, emit a stack trace (default :0) | -| --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-stack-size | Int | configure the maximum stack size in bytes (default 67108864) | -| --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) | -| --max_payload_size | Int | The threshold for query payloads in bytes. A payload greater than this threshold will result in a failure to handle the query. | -| --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 for each replicating tablet_type (e.g. replica, rdonly) that will be continue to be used even with replication lag above discovery_low_replication_lag, but still below discovery_high_replication_lag_minimum_serving. (default 2) | -| --mysql-server-pool-conn-read-buffers | Boolean | If set, the server will pool incoming connection read buffers | -| --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. Options: none, ldap, clientcert, static, vault. (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_auth_vault_addr | String | URL to Vault server | -| --mysql_auth_vault_path | String | Vault path to vtgate credentials JSON blob, e.g.: secret/data/prod/vtgatecreds | -| --mysql_auth_vault_role_mountpoint | String | Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") | -| --mysql_auth_vault_role_secretidfile | String | Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable | -| --mysql_auth_vault_roleid | String | Vault AppRole id; can also be passed using VAULT_ROLEID environment variable | -| --mysql_auth_vault_timeout | Duration | Timeout for vault API operations (default 10s) | -| --mysql_auth_vault_tls_ca | String | Path to CA PEM for validating Vault server certificate | -| --mysql_auth_vault_tokenfile | String | Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable | -| --mysql_auth_vault_ttl | Duration | How long to cache vtgate credentials from the Vault server (default 30m0s) | -| --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 "OLTP") | -| --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 be flushed to the 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_crl | String | Path to ssl CRL for mysql server plugin SSL | -| --mysql_server_ssl_key | String | Path to ssl key for mysql server plugin SSL | -| --mysql_server_ssl_server_ca | String | path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients | -| --mysql_server_tls_min_version | String | Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. | -| --mysql_server_version | String | MySQL server version to advertise. | -| --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") | -| --no_scatter | Boolean | when set to true, the planner will fail instead of producing a plan that includes scatter queries | -| --normalize_queries | Boolean | Rewrite queries with bind vars. Turn this off if the app itself sends normalized queries with bind vars. (default true) | -| --onclose_timeout | Duration | wait no more than this for OnClose handlers before stopping (default 10s) | -| --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. | -| --planner-version | String | Sets the default planner to use when the session has not changed it. Valid values are: V3, Gen4, Gen4Greedy and Gen4Fallback. Gen4Fallback tries the gen4 planner and falls back to the V3 planner if the gen4 fails. | -| --port | Int | port for the server | -| --pprof strings | Boolean | enable profiling | -| --proxy_protocol | Boolean | Enable HAProxy PROXY protocol on MySQL listener socket | -| --purge_logs_interval | Duration | how often try to remove old logs (default 1h0m0s) | -| --query-timeout | Int | Sets the default query timeout (in ms). Can be overridden by session variable (query_timeout) or comment directive (QUERY_TIMEOUT_MS) | -| --querylog-buffer-size | Int | Maximum number of buffered query logs before throttling log output (default 10) | -| --querylog-filter-tag | String | string that must be present in the query for it to be logged; if using a value as the tag, you need to disable query normalization | -| --querylog-format | String | format for query logs ("text" or "json") (default "text") | -| --querylog-row-threshold | Uint | Number of rows a query has to return or affect before being logged; not useful for streaming queries. 0 means all queries will be logged. | -| --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 15s) | -| --retry-count | Int | retry count (default 2) | -| --schema_change_signal | Boolean | Enable the schema tracker; requires queryserver-config-schema-change-signal to be enabled on the underlying vttablets for this to work (default true) | -| --schema_change_signal_user | String | User to be used to send down query to vttablet to retrieve schema changes | -| --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 | Strings | comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice | -| --sql-max-length-errors | Int | truncate queries in error logs to the given length (default unlimited) | -| --sql-max-length-ui | Int | truncate queries in debug UIs to the given length (default 512) (default 512) | -| --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) | -| --srv_topo_timeout | Duration | topo server timeout (default 5s) | -| --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_common_tags | Strings | Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2 | -| --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) | -| --statsd_address | String | Address for statsd client | -| --statsd_sample_rate | Float | Sample rate for statsd metrics (default 1) | -| --stderrthreshold | Severity | 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 | Strings | 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_crl | String | the server crl to use to validate server certificates when connecting | -| --tablet_grpc_key | String | the key to use to connect | -| --tablet_grpc_server_name | String | the server name to use to validate server certificate | -| --tablet_protocol | String | Protocol to use to make queryservice RPCs to vttablets. (default "grpc") | -| --tablet_refresh_interval | Duration | Tablet refresh interval. (default 1m0s) | -| --tablet_refresh_known_tablets | Boolean | Whether to reload the tablet's address/port map from topo in case they change. (default true) | -| --tablet_types_to_wait | Strings | Wait till connected for specified tablet types during Gateway initialization. Should be provided as a comma-separated set of tablet types. | -| --tablet_url_template | String | Format string describing debug tablet url formatting. See getTabletDebugURL() for how to customize this. (default "http://{{.GetTabletHostPort}}") | -| --topo_consul_lock_delay | Duration | LockDelay for consul session. (default 15s) | -| --topo_consul_lock_session_checks | String | List of checks for consul session. (default "serfHealth") | -| --topo_consul_lock_session_ttl | String | TTL for consul session. | -| --topo_consul_watch_poll_duration | Duration | time of the long poll for watch queries. (default 30s) | -| --topo_etcd_lease_ttl | Int | Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) | -| --topo_etcd_tls_ca | String | path to the ca to use to validate the server cert when connecting to the etcd topo server | -| --topo_etcd_tls_cert | String | path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS | -| --topo_etcd_tls_key | String | path to the client key to use to connect to the etcd topo server, enables TLS | -| --topo_global_root | String | the path of the global topology data in the global topology server | -| --topo_global_server_address | String | the address of the global topology server | -| --topo_implementation | String | the topology implementation to use | -| --topo_read_concurrency | Int | Concurrency of 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-enable-logging | Boolean | whether to enable logging in the tracing service | -| --tracing-sampling-rate | Float | sampling rate for the probabilistic jaeger sampler (default 0.1) | -| --tracing-sampling-type | String | sampling strategy to use for jaeger. possible values are 'const', 'probabilistic', 'rateLimiting', or 'remote' (default "const") | -| --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 | Level | log level for V logs | -| -v, --version | Boolean | print binary version | -| --vmodule | ModuleSpec | 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. | -| --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) | -| --warn_payload_size | Int | The warning threshold for query payloads in bytes. A payload greater than this threshold will cause the VtGateWarnings.WarnPayloadSizeExceeded counter to be incremented. | -| --warn_sharded_only | Boolean | If any features that are only available in unsharded mode are used, query execution warnings will be added to the session | +| Name | Type | Definition | +|:-----------------------------------------------------------------|:----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| --allow-kill-statement | Boolean | Allows the execution of kill statement | +| --allowed_tablet_types | Strings | Specifies the tablet types this vtgate is allowed to route queries to. Should be provided as a comma-separated set of tablet types. | +| --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 PRIMARY vttablet when draining the buffer. (default 1) | +| --buffer_implementation | String | Allowed values: healthcheck (legacy implementation), keyspace_events (default) (default "keyspace_events") | +| --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 1000) | +| --buffer_window | Duration | Duration for how long a request should be buffered at most. (default 10s) | +| --catch-sigpipe | Boolean | catch and ignore SIGPIPE on stdout and stderr if specified | +| --cell | String | | | cell to use | +| --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. | +| --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 | +| --dbddl_plugin | String | controls how to handle CREATE/DROP DATABASE. use it if you are using your own database provisioning service (default "fail") | +| --ddl_strategy | String | Set default strategy for DDL statements. Override with @@ddl_strategy session variable (default "direct") | +| --default_tablet_type | Topodatapb.TabletType | The default tablet type to set for queries, when one is not explicitly selected. (default PRIMARY) | +| --discovery_high_replication_lag_minimum_serving | Duration | Threshold above which replication lag is considered too high when applying the min_number_serving_vttablets flag. (default 2h0m0s) | +| --discovery_low_replication_lag | Duration | Threshold below which replication lag is considered low enough to be healthy. (default 30s) | +| --emit_stats | Boolean | If set, emit stats to push-based monitoring and stats backends | +| --enable-partial-keyspace-migration | Boolean | (Experimental) Follow shard routing rules: enable only while migrating a keyspace shard by shard. See documentation on Partial MoveTables for more. (default false) | +| --enable-views | Boolean | Enable views support in vtgate. | +| --enable_buffer | Boolean | Enable buffering (stalling) of primary traffic during failovers. | +| --enable_buffer_dry_run | Boolean | Detect and log failover events, but do not actually buffer requests. | +| --enable_direct_ddl | Boolean | Allow users to submit direct DDL statements (default true) | +| --enable_online_ddl | Boolean | Allow users to submit, review and control Online DDL (default true) | +| --enable_set_var | Boolean | This will enable the use of MySQL's SET_VAR query hint for certain system variables instead of using reserved connections (default true) | +| --enable_system_settings | Boolean | This will enable the system settings to be changed per session at the database connection level (default true) | +| --foreign_key_mode | String | This is to provide how to handle foreign key constraint in create/alter table. Valid values are: allow, disallow (default "allow") | +| --gate_query_cache_lfu | Boolean | gate server cache algorithm. when set to true, a new cache algorithm based on a TinyLFU admission policy will be used to improve cache behavior and prevent pollution from sparse queries (default true) | +| --gate_query_cache_memory | Int | gate server query cache size in bytes, maximum amount of memory 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 33554432) | +| --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 cache. This config controls the expected amount of unique entries in the cache. (default 5000) | +| --gateway_initial_tablet_timeout | Duration | At startup, the tabletGateway will wait up to this duration to get at least one tablet per keyspace/shard/tablet type (default 30s) | +| --grpc-use-effective-groups | Boolean | If set, and SSL is not used, will set the immediate caller's security groups from the effective caller id's groups. | +| --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 | server CA to use for gRPC connections, requires TLS, and enforces client certificate check | +| --grpc_cert | String | server certificate to use for gRPC connections, requires grpc_key, enables TLS | +| --grpc_compression | String | Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy | +| --grpc_crl | String | path to a certificate revocation list in PEM format, client certificates will be further verified against this file during TLS handshake | +| --grpc_enable_optional_tls | Boolean | enable optional TLS mode when a server accepts both TLS and plain-text connections on the same port | +| --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 | server private key to use for gRPC connections, 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. If zero, do not listen. | +| --grpc_prometheus | Boolean | Enable gRPC monitoring with Prometheus. | +| --grpc_server_ca | String | path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients | +| --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 10s) | +| --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. | +| --grpc-use-static-authentication-callerid | boolean | If set, will set the immediate caller id to the username authenticated by the static auth plugin. | +| --healthcheck_retry_delay | Duration | health check retry delay (default 2ms) | +| --healthcheck_timeout | Duration | the health check timeout period (default 1m0s) | +| -h, --help | Boolean | display usage and exit | +| --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 | Strings | 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 vttablets for serving. (default true) | +| --lock-timeout | Duration | Maximum time for which a shard/keyspace lock can be acquired for (default 45s) | +| --lock_heartbeat_time | Duration | If there is lock function used. This will keep the lock connection active by using this heartbeat (default 5s) | +| --log_backtrace_at | TraceLocation | when logging hits line file:N, emit a stack trace (default :0) | +| --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-stack-size | Int | configure the maximum stack size in bytes (default 67108864) | +| --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) | +| --max_payload_size | Int | The threshold for query payloads in bytes. A payload greater than this threshold will result in a failure to handle the query. | +| --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 for each replicating tablet_type (e.g. replica, rdonly) that will be continue to be used even with replication lag above discovery_low_replication_lag, but still below discovery_high_replication_lag_minimum_serving. (default 2) | +| --mysql-server-keepalive-period | Duration | TCP period between keep-alives | +| --mysql-server-pool-conn-read-buffers | Boolean | If set, the server will pool incoming connection read buffers | +| --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. Options: none, ldap, clientcert, static, vault. (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_auth_vault_addr | String | URL to Vault server | +| --mysql_auth_vault_path | String | Vault path to vtgate credentials JSON blob, e.g.: secret/data/prod/vtgatecreds | +| --mysql_auth_vault_role_mountpoint | String | Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") | +| --mysql_auth_vault_role_secretidfile | String | Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable | +| --mysql_auth_vault_roleid | String | Vault AppRole id; can also be passed using VAULT_ROLEID environment variable | +| --mysql_auth_vault_timeout | Duration | Timeout for vault API operations (default 10s) | +| --mysql_auth_vault_tls_ca | String | Path to CA PEM for validating Vault server certificate | +| --mysql_auth_vault_tokenfile | String | Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable | +| --mysql_auth_vault_ttl | Duration | How long to cache vtgate credentials from the Vault server (default 30m0s) | +| --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 "OLTP") | +| --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 be flushed to the 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_crl | String | Path to ssl CRL for mysql server plugin SSL | +| --mysql_server_ssl_key | String | Path to ssl key for mysql server plugin SSL | +| --mysql_server_ssl_server_ca | String | path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients | +| --mysql_server_tls_min_version | String | Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. | +| --mysql_server_version | String | MySQL server version to advertise. | +| --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") | +| --no_scatter | Boolean | when set to true, the planner will fail instead of producing a plan that includes scatter queries | +| --normalize_queries | Boolean | Rewrite queries with bind vars. Turn this off if the app itself sends normalized queries with bind vars. (default true) | +| --onclose_timeout | Duration | wait no more than this for OnClose handlers before stopping (default 10s) | +| --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. | +| --planner-version | String | Sets the default planner to use when the session has not changed it. Valid values are: Gen4, Gen4Greedy, Gen4Left2Right | +| --port | Int | port for the server | +| --pprof strings | Boolean | enable profiling | +| --proxy_protocol | Boolean | Enable HAProxy PROXY protocol on MySQL listener socket | +| --purge_logs_interval | Duration | how often try to remove old logs (default 1h0m0s) | +| --query-timeout | Int | Sets the default query timeout (in ms). Can be overridden by session variable (query_timeout) or comment directive (QUERY_TIMEOUT_MS) | +| --querylog-buffer-size | Int | Maximum number of buffered query logs before throttling log output (default 10) | +| --querylog-filter-tag | String | string that must be present in the query for it to be logged; if using a value as the tag, you need to disable query normalization | +| --querylog-format | String | format for query logs ("text" or "json") (default "text") | +| --querylog-row-threshold | Uint | Number of rows a query has to return or affect before being logged; not useful for streaming queries. 0 means all queries will be logged. | +| --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 15s) | +| --retry-count | Int | retry count (default 2) | +| --schema_change_signal | Boolean | Enable the schema tracker; requires queryserver-config-schema-change-signal to be enabled on the underlying vttablets for this to work (default true) | +| --schema_change_signal_user | String | User to be used to send down query to vttablet to retrieve schema changes | +| --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 | Strings | comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice | +| --sql-max-length-errors | Int | truncate queries in error logs to the given length (default unlimited) | +| --sql-max-length-ui | Int | truncate queries in debug UIs to the given length (default 512) (default 512) | +| --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) | +| --srv_topo_timeout | Duration | topo server timeout (default 5s) | +| --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_common_tags | Strings | Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2 | +| --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) | +| --statsd_address | String | Address for statsd client | +| --statsd_sample_rate | Float | Sample rate for statsd metrics (default 1) | +| --stderrthreshold | Severity | 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 | Strings | 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_crl | String | the server crl to use to validate server certificates when connecting | +| --tablet_grpc_key | String | the key to use to connect | +| --tablet_grpc_server_name | String | the server name to use to validate server certificate | +| --tablet_protocol | String | Protocol to use to make queryservice RPCs to vttablets. (default "grpc") | +| --tablet_refresh_interval | Duration | Tablet refresh interval. (default 1m0s) | +| --tablet_refresh_known_tablets | Boolean | Whether to reload the tablet's address/port map from topo in case they change. (default true) | +| --tablet_types_to_wait | Strings | Wait till connected for specified tablet types during Gateway initialization. Should be provided as a comma-separated set of tablet types. | +| --tablet_url_template | String | Format string describing debug tablet url formatting. See getTabletDebugURL() for how to customize this. (default "http://{{.GetTabletHostPort}}") | +| --topo_consul_lock_delay | Duration | LockDelay for consul session. (default 15s) | +| --topo_consul_lock_session_checks | String | List of checks for consul session. (default "serfHealth") | +| --topo_consul_lock_session_ttl | String | TTL for consul session. | +| --topo_consul_watch_poll_duration | Duration | time of the long poll for watch queries. (default 30s) | +| --topo_etcd_lease_ttl | Int | Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) | +| --topo_etcd_tls_ca | String | path to the ca to use to validate the server cert when connecting to the etcd topo server | +| --topo_etcd_tls_cert | String | path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS | +| --topo_etcd_tls_key | String | path to the client key to use to connect to the etcd topo server, enables TLS | +| --topo_global_root | String | the path of the global topology data in the global topology server | +| --topo_global_server_address | String | the address of the global topology server | +| --topo_implementation | String | the topology implementation to use | +| --topo_read_concurrency | Int | Concurrency of 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-enable-logging | Boolean | whether to enable logging in the tracing service | +| --tracing-sampling-rate | Float | sampling rate for the probabilistic jaeger sampler (default 0.1) | +| --tracing-sampling-type | String | sampling strategy to use for jaeger. possible values are 'const', 'probabilistic', 'rateLimiting', or 'remote' (default "const") | +| --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 | Level | log level for V logs | +| -v, --version | Boolean | print binary version | +| --vmodule | ModuleSpec | 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. | +| --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) | +| --warn_payload_size | Int | The warning threshold for query payloads in bytes. A payload greater than this threshold will cause the VtGateWarnings.WarnPayloadSizeExceeded counter to be incremented. | +| --warn_sharded_only | Boolean | If any features that are only available in unsharded mode are used, query execution warnings will be added to the session | ### Key Options diff --git a/content/en/docs/18.0/reference/programs/vttablet.md b/content/en/docs/18.0/reference/programs/vttablet.md index e773c39fc..0a6556636 100644 --- a/content/en/docs/18.0/reference/programs/vttablet.md +++ b/content/en/docs/18.0/reference/programs/vttablet.md @@ -295,7 +295,7 @@ The following global options apply to `vttablet`: | --queryserver-config-txpool-timeout | float | 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 | -| --queryserver-enable-settings-pool | boolean | Enable pooling of connections with modified system settings | +| --queryserver-enable-settings-pool | boolean | Enable pooling of connections with modified system settings (default true) | | --queryserver-enable-views | boolean | Enable views support in vttablet. | | --queryserver_enable_online_ddl | boolean | Enable online DDL. (default true) | | --redact-debug-ui-queries | boolean | redact full queries and bind variables from debug UI | @@ -398,10 +398,13 @@ The following global options apply to `vttablet`: | --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 | Synonym to -tx_throttler_config (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-config | string | Synonym to -tx_throttler_config (default "target_replication_lag_sec:2 max_replication_lag_sec:10 initial_rate:100 max_increase:1 emergency_decrease:0.5 min_duration_between_increases_sec:40 max_duration_between_increases_sec:62 min_duration_between_decreases_sec:20 spread_backlog_across_sec:20 age_bad_rate_after_sec:180 bad_rate_increase:0.1 max_rate_approach_threshold:0.9") | +| --tx-throttler-default-priority | int | Default priority assigned to queries that lack priority information | +| --tx-throttler-dry-run | boolean | If present, the TxThrottler only records metrics about requests received and throttled, but does not actually throttle any requests. | | --tx-throttler-healthcheck-cells | strings | Synonym to -tx_throttler_healthcheck_cells | | --tx-throttler-tablet-types | strings | A comma-separated list of tablet types. Only tablets of this type are monitored for replication lag by the transaction throttler. Supported types are replica and/or rdonly. (default replica) | -| --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-topo-refresh-interval | duration | The rate that the transaction throttler will refresh the topology to find cells. (default 5m0s) | +| --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 max_replication_lag_sec:10 initial_rate:100 max_increase:1 emergency_decrease:0.5 min_duration_between_increases_sec:40 max_duration_between_increases_sec:62 min_duration_between_decreases_sec:20 spread_backlog_across_sec:20 age_bad_rate_after_sec:180 bad_rate_increase:0.1 max_rate_approach_threshold:0.9") | | --tx_throttler_healthcheck_cells | strings | 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) | | --v | Level | log level for V logs | diff --git a/content/en/docs/18.0/reference/query-serving/reserved-conn.md b/content/en/docs/18.0/reference/query-serving/reserved-conn.md index 40b449351..bf5644a8e 100644 --- a/content/en/docs/18.0/reference/query-serving/reserved-conn.md +++ b/content/en/docs/18.0/reference/query-serving/reserved-conn.md @@ -39,7 +39,7 @@ What we want to highlight at the beginning is that there is a known issue when a To solve this problem, the connection pool implementation used by vttablet has been enhanced to keep the connections with settings in the pool and not to pin the connection to the client session. With this enhancement, we reduce the likelihood of MySQL running out of connections due to reserved connections, because the scenarios where we still need reserved connections are sharply reduced. -Since this is a new feature, it is currently disabled by default. It can be enabled by setting the flag `--queryserver-enable-settings-pool` on vttablet. +This is enabled by default from v17 onwards. It can be disabled by setting the flag `--queryserver-enable-settings-pool` on vttablet. This change takes effect only for the cases when system variable changes need a reserved connection. There are still cases like [temporary tables](#temporary-tables-and-reserved-connections) and [advisory locks](#get_lock-and-reserved-connections) where reserved connections will continue to be used. diff --git a/content/en/docs/18.0/reference/vtorc/ui_api_metrics.md b/content/en/docs/18.0/reference/vtorc/ui_api_metrics.md index 20cfb5fb1..91e08a5d9 100644 --- a/content/en/docs/18.0/reference/vtorc/ui_api_metrics.md +++ b/content/en/docs/18.0/reference/vtorc/ui_api_metrics.md @@ -22,18 +22,19 @@ VTOrc supports the following APIs which can be used for monitoring and changing | `/debug/health` | This API outputs the health of the VTOrc process. | | `/debug/liveness` | This API outputs the liveness of the VTOrc process. | | `/api/replication-analysis` | This API shows the replication analysis of VTOrc. Output is in JSON format. | +| `/api/errant-gtids` | This API shows the tablets that have errant GTIDs as detected by VTOrc. Output is in JSON format. This API supports filtering by keyspace and shard name. | # Metrics Metrics are available to be seen on the `/debug/vars` page. VTOrc exports the following metrics: -| Metric | Usage | -|------------------------|------------------------------------------------------------------------------------------------------| -| `PendingRecoveries` | The number of recoveries in progress which haven't completed. | -| `RecoveriesCount` | The number of recoveries run. This is further subdivided for all the different recoveries. | -| `SuccessfulRecoveries` | The number of succesful recoveries run. This is further subdivided for all the different recoveries. | -| `FailedRecoveries` | The number of recoveries that failed. This is further subdivided for all the different recoveries. | -| `ErrantGtidMap` | Metric to track the errant GTIDs detected by VTOrc. | +| Metric | Usage | +|-------------------------|------------------------------------------------------------------------------------------------------| +| `PendingRecoveries` | The number of recoveries in progress which haven't completed. | +| `RecoveriesCount` | The number of recoveries run. This is further subdivided for all the different recoveries. | +| `SuccessfulRecoveries` | The number of succesful recoveries run. This is further subdivided for all the different recoveries. | +| `FailedRecoveries` | The number of recoveries that failed. This is further subdivided for all the different recoveries. | +| `ErrantGtidTabletCount` | The number of tablets with errant GTIDs as detected by VTOrc. | {{< info >}} diff --git a/content/en/docs/18.0/user-guides/configuration-advanced/comment-directives.md b/content/en/docs/18.0/user-guides/configuration-advanced/comment-directives.md index daad76c7a..7afbcc6e8 100644 --- a/content/en/docs/18.0/user-guides/configuration-advanced/comment-directives.md +++ b/content/en/docs/18.0/user-guides/configuration-advanced/comment-directives.md @@ -89,7 +89,7 @@ Overrides the default planner to the one specified by the directive. Example que select /*vt+ PLANNER=gen4 */ * from user; ``` -Valid values are the same as for the planner flag - `v3` and `gen4`. +Valid values are the same as for the planner flag - `Gen4`, `Gen4Greedy` and `Gen4Left2Right`. ### Workload name (`WORKLOAD_NAME`) diff --git a/content/en/docs/18.0/user-guides/configuration-basic/monitoring.md b/content/en/docs/18.0/user-guides/configuration-basic/monitoring.md index 3b6317501..2bbbc111c 100644 --- a/content/en/docs/18.0/user-guides/configuration-basic/monitoring.md +++ b/content/en/docs/18.0/user-guides/configuration-basic/monitoring.md @@ -370,10 +370,14 @@ This is the main histogram variable to track for vtgates. It gives you a break u It shows the number of tablet connections for query/healthcheck per keyspace, shard, and tablet type. -### TopologyWatcherErrors and TopologyWatcherOperations +#### TopologyWatcherErrors and TopologyWatcherOperations These two variables track events related to how vtgate watches the topology. It is particularly important to monitor the error count. This can act as an early warning sign if a vtgate is not able to refresh the list of tablets from the topo. +#### VindexUnknownParameters + +Gauges the number of unknown Vindex params in the latest VSchema obtained from the topology. + ### /debug/health This URL prints out a simple "ok" or “not ok” string that can be used to check if the server is healthy. diff --git a/content/en/docs/18.0/user-guides/migration/troubleshooting.md b/content/en/docs/18.0/user-guides/migration/troubleshooting.md index 4a3b74c38..78ccc854d 100644 --- a/content/en/docs/18.0/user-guides/migration/troubleshooting.md +++ b/content/en/docs/18.0/user-guides/migration/troubleshooting.md @@ -137,7 +137,7 @@ This can be caused by a DDL executed on the source table as by default — contr If you want the same or similar DDL to be applied on the target then you can apply that DDL on the target keyspace and then restart the workflow. For example, using the example above: ```bash -$ vtctlclient ApplySchema -- --allow_long_unavailability --ddl_strategy=direct --sql="alter table customer add notes varchar(100) not null" customer +$ vtctlclient ApplySchema -- --ddl_strategy=direct --sql="alter table customer add notes varchar(100) not null" customer $ vtctlclient Workflow -- customer.commerce2customer start ``` diff --git a/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md b/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md index 5ab721ed7..fefc571b4 100644 --- a/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md +++ b/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md @@ -4,7 +4,8 @@ weight: 3 aliases: ['/docs/user-guides/backup-and-restore/'] --- -## Restoring a backup +Restores can be done automatically by way of seeding/bootstrapping new tablets, or they can be invoked manually on a tablet to restore a full backup or do a point-in-time recovery. +## Auto restoring a backup on startup When a tablet starts, Vitess checks the value of the `--restore_from_backup` command-line flag to determine whether to restore a backup to that tablet. Restores will always be done with whichever engine was used to create the backup. @@ -32,3 +33,67 @@ Bootstrapping a new tablet is almost identical to restoring an existing tablet. ``` The bootstrapped tablet will restore the data from the backup and then apply changes, which occurred after the backup, by restarting replication. + +## Manual restore + +A manual restore is done on a specific tablet. The tablet's MySQL server is shut down and its data is wiped out. + +### Restore a full backup + +To restore the tablet from the most recent full backup, run: + +```shell +vtctldclient --server=: RestoreFromBackup +``` + +Example: + +```shell +vtctldclient --server localhost:15999 --alsologtostderr RestoreFromBackup zone1-0000000101 +``` + +If successful, the tablet's MySQL server rejoins the shard's replication stream, to eventually captch up and be able to serve traffic. + +### Restore to a point-in-time + +Vitess supports restoring to a _timestamp_ or to a specific _position_. Either way, this restore method assumes backups have been taken that cover the specified position. The restore process will first determine a restore path: a sequence of backups, starting with a full backup followed by zero or more incremental backups, that when combined, include the specified timestamp or position. See more on [Restore Types](../overview/#restore-types) and on [Taking Incremental Backup](../creating-a-backup/#create-an-incremental-backup-with-vtctl). + +#### Restore to timestamp + +Starting with `v18`, it is possible to restore to a given timestamp. The restore process will apply all events up to, and excluding, the given timestamp, at 1 second granularity. That is, the restore will bring the database to a point in time which is _about_ 1 second before the specified timestamp. Example: + +```shell +vtctldclient RestoreFromBackup --restore-to-timestamp "2023-06-15T09:49:50Z" zone1-0000000100 +``` + +The timestamp must be in `RFC3339` format. + +#### Restore to a position + +It is possible to restore onto a precise GTID position. Vitess will restore up to, and including, the exact requested position. This gives you the utmost granularity into the state of the restored database. + +```shell +vtctldclient RestoreFromBackup --restore-to-pos +``` + +Example: + +```shell +vtctldclient RestoreFromBackup --restore-to-pos "MySQL56/0d7aaca6-1666-11ee-aeaf-0a43f95f28a3:1-60" zone1-0000000102 +``` + +#### Dry run + +It is possible to verify whether a restore-to-timestamp or restore-to-pos is possible without actually performing the restore. Run: + + +```shell +vtctldclient RestoreFromBackup --dry-run --restore-to-timestamp "2023-06-15T09:49:50Z" zone1-0000000100 +``` + +or +```shell +vtctldclient RestoreFromBackup --dry-run --restore-to-pos "MySQL56/0d7aaca6-1666-11ee-aeaf-0a43f95f28a3:1-60" zone1-0000000102 +``` + +A dry run restore looks at existing backups and sees whether there is a path that restores up to given timestamp or pos, but then quits and does not interrupt any tablet's execution and without changing the tablet's type. If there's no valid path to restore, the process exits with error. \ No newline at end of file diff --git a/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md b/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md index 665fba502..992de396f 100644 --- a/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md +++ b/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md @@ -4,6 +4,12 @@ weight: 2 aliases: ['/docs/user-guides/backup-and-restore/'] --- +## Choosing the backup type + +As described in [Backup types](../overview/#backup-types), you choose to run a full Backup (the default) or an incremental Backup. + +Full backups will use the backup engine chosen in the tablet's [configuration](#configuration). Incremental backups will always copy MySQL's binary logs, irrespective of the configured backup engine. + ## Using xtrabackup The default backup implementation is `builtin`, however we strongly recommend using the `xtrabackup` engine as it is more robust and allows for non-blocking backups. Restores will always be done with whichever engine was used to create the backup. @@ -75,12 +81,12 @@ I0310 12:49:32.279773 215835 backup.go:163] I0310 20:49:32.279485 xtrabackupeng To continue with risk: Set `--xtrabackup_backup_flags=--no-server-version-check`. Note this occurs when your MySQL server version is technically unsupported by `xtrabackup`. -## Create backups with vtctl +## Create a full backup with vtctl __Run the following vtctl command to create a backup:__ -``` sh -vtctldclient --server=: Backup +```sh +vtctldclient --server=: Backup [--upgrade-safe=false] ``` If the engine is `builtin`, replication will be stopped prior to shutting down mysqld for the backup. @@ -90,9 +96,34 @@ If the engine is `xtrabackup`, the tablet can continue to serve traffic while th __Run the following vtctl command to backup a specific shard:__ ``` sh -vtctldclient --server=: BackupShard [--allow_primary=false] +vtctldclient --server=: BackupShard [--allow_primary=false] [--upgrade-safe=false] ``` +## Create an incremental backup with vtctl + +An incremental backup requires additional information: the point from which to start the backup. An incremental backup is taken by supplying `--incremental-from-pos` to the `Backup` command. The argument may either indicate a valid position, or the value `auto`. Examples: + +```sh +vtctldclient Backup --incremental-from-pos="MySQL56/0d7aaca6-1666-11ee-aeaf-0a43f95f28a3:1-53" zone1-0000000102 + +vtctldclient Backup --incremental-from-pos="0d7aaca6-1666-11ee-aeaf-0a43f95f28a3:1-53" zone1-0000000102 + +vtctldclient Backup --incremental-from-pos="auto" zone1-0000000102 +``` + +When indicating a position, you may choose to use or to omit the `MySQL56/` prefix (which you can find in the backup manifest's Position). + +When `--incremental-from-pos="auto"`, Vitess chooses the position of the last successful backup as the starting point for the incremental backup. This is a convenient way to ensure a sequence of contiguous incremental backups. + +An incremental backup backs up one or more MySQL binary log files. These binary log files may begin with the requested position, or with an earlier position. They will necessarily include the requested position. When the incremental backup begins, Vitess rotates the MySQL binary logs on the tablet, so that it does not back up an active log file. + +An incremental backup fails in these scenarios: + +- It is unable to find binary log files that covers the requested position. This can happen if the binary logs are purged earlier than the incremental backup was taken. It essentially means there's a gap in the changelog events. **Note** that while on one tablet the binary logs may be missing, another tablet may still have binary logs that cover the requested position. +- There is no change to the database since the requested position, i.e. the GTID position has not changed since. + +`v17` only supports `--incremental-from-pos` in the `Backup` command, not in `BackupShard`. Also, only `vtctlclient` supports the flag, where `vtctldclient` does not. `v18` is expected to support incremental backups for `BackupShard` and for `vtctldclient`. + ## Backing up Topology Server The Topology Server stores metadata (and not tablet data). It is recommended to create a backup using the method described by the underlying plugin: diff --git a/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/overview.md b/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/overview.md index 1f7e98996..d7ac333d1 100644 --- a/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/overview.md +++ b/content/en/docs/18.0/user-guides/operating-vitess/backup-and-restore/overview.md @@ -26,6 +26,36 @@ The engine is the techology used for generating the backup. Currently Vitess has * Builtin: Shutdown an instance and copy all the database files (default) * XtraBackup: An online backup using Percona's [XtraBackup](https://www.percona.com/software/mysql-database/percona-xtrabackup) +### Backup types + +Vitess supports full backups as well as incremental backups, and their respective counterparts full restores and point-in-time restores. + +* A full backup contains the entire data in the database. The backup represents a consistent state of the data, i.e. it is a snapshot of the data at some point in time. +* An incremental backup contains a changelog, or a transition of data from one state to another. Vitess implements incremental backups by making a copy of MySQL binary logs. + +Generally speaking and on most workloads, the cost of a full backup is higher, and the cost of incremental backups is lower. The time it takes to create a full backup is significant, and it is therefore impractical to take full backups in very small intervals. Moreover, a full backup consumes the disk space needed for the entire dataset. Incremental backups, on the other hand, are quick to run, and have very little impact, if any, to the running servers. They only contain the changes in between two points in time, and on most workloads are more compact. + +Full and incremental backups are expected to be interleaved. For example: one would create a full backup once per day, and incremental backups once per hour. + +Full backups are simply states of the database. Incremental backups, however, need to start with some point and end with some point. The common practice is for an incremental backup to continue from the point of the last good backup, which can be a full or incremental backup. An inremental backup in Vitess ends at the point in time of execution. + +The identity of the tablet on which a full backup or an incremental backup is taken is immaterial. It is possible to take a full backup on one tablet and incremental backups on another. It is possible to take full backups on two different tablets. It is also possible to take incremental backups, independently, on two different tablets, even though the contents of those incremental backups overlaps. Vitess uses MySQL GTID sets to determine positioning and prune duplicates. + +### Restores + +Restores are the counterparts of backups. A restore uses the engine utilized to create a backup. One may run a restore from a full backup, or a point-in-time restore (PITR) based on additional incremental backups. + +A Vitess restore operates on a tablet. The restore process completely wipes out the data in the tablet's MySQL server and repopulates the server with the backup(s) data. The MySQL server is shutdown during the process. As a safety mechanism, Vitess by default prevents a restore onto a `PRIMARY` tablet. Any non-`PRIMARY` tablet is otherwise eligible to restore. + +### Restore Types + +Vitess supports full restores and incremental (AKA point-in-time) restores. The two serve different purposes. + +* A full restore loads the dataset from a full backup onto a non-`PRIMARY` tablet. Once the data is loaded, the restore process starts the MySQL service and makes it join the replication stream. It is expected that a freshly restored server will lag behind the shard's `PRIMARY` for a period of time. + The full restore flow is useful for seeding new replica tablets. It may also be used to fix replicas that have been corrupted. +* An incremental, or a point-in-time restore, restores a tablet/MySQL up to a specific position or time. This is done by first loading a full backup dataset, followed by applying the changelog captured in zero or more incremental backups. Once that is complete, the tablet type is set to `DRAINED` and the tablet does _not_ join the replication stream. + The common purpose of point-in-time restore is to recover data from an accidental write/deletion. If the database administrator knows at about what time the accidental write took place, they can restore a replica tablet to a point in time shortly before the accidental write. Since the server does not join the replication stream, its data then remains static, and the administrator may review or copy the data as they please. Finally, it is then possible to change the tablet type back to `REPLICA` and have it join the shard's replication. + ## Vtbackup, VTTablet and Vtctld Vtbackup, VTTablet, and Vtctld may all participate in backups and restores. diff --git a/content/en/docs/18.0/user-guides/schema-changes/audit-and-control.md b/content/en/docs/18.0/user-guides/schema-changes/audit-and-control.md index 349b18984..118fcbee9 100644 --- a/content/en/docs/18.0/user-guides/schema-changes/audit-and-control.md +++ b/content/en/docs/18.0/user-guides/schema-changes/audit-and-control.md @@ -496,7 +496,7 @@ $ vtctlclient -- ApplySchema --sql "alter vitess_migration cancel all" commerce Also available via `vtctlclient OnlineDDL` command: ``` -vtctlclient OnlineDDL cancel-all +vtctlclient OnlineDDL cancel all ``` Example: @@ -513,7 +513,7 @@ $ vtctlclient OnlineDDL commerce show all | zone1-0000000100 | 0 | vt_commerce | corder | 2c87f7cd_353a_11eb_8b72_f875a4d24e90 | online | | | queued | +------------------+-------+--------------+-------------+--------------------------------------+----------+-------------------+---------------------+------------------+ -$ vtctlclient OnlineDDL commerce cancel-all +$ vtctlclient OnlineDDL commerce cancel all $ vtctlclient OnlineDDL commerce show all +------------------+-------+--------------+-------------+--------------------------------------+----------+-------------------+---------------------+------------------+ @@ -655,6 +655,16 @@ mysql> alter vitess_migration 'aa89f255_8d68_11eb_815f_f875a4d24e90' cleanup; Query OK, 1 row affected (0.00 sec) ``` + +#### Via vtctlclient/ApplySchema + +Execute via `vtctlclient -- ApplySchema --sql "..." ` like previous commands, or use `OnlineDDL` command: + + +```shell +$ vtctlclient OnlineDDL commerce cleanup 2201058f_f266_11ea_bab4_0242c0a8b007 +``` + ## Reverting a migration Vitess offers _lossless revert_ for online schema migrations: the user may regret a table migration after completion, and roll back the table's schema to previous state _without loss of data_. See [Revertible Migrations](../revertible-migrations/). @@ -773,3 +783,15 @@ Use: ### Showing throttled apps The command `show vitess_throttled_apps;` is a general purpose throttler command, and shows all apps for which there are throttling rules. It will list any specific or general migration throttling status. + +### Via vtctlclient/ApplySchema + +Execute via `vtctlclient -- ApplySchema --sql "..." ` like previous commands, or use `OnlineDDL` commands: + + +```shell +$ vtctlclient OnlineDDL commerce throttle 2201058f_f266_11ea_bab4_0242c0a8b007 +$ vtctlclient OnlineDDL commerce throttle all +$ vtctlclient OnlineDDL commerce unthrottle 2201058f_f266_11ea_bab4_0242c0a8b007 +$ vtctlclient OnlineDDL commerce unthrottle all +``` diff --git a/content/en/docs/18.0/user-guides/schema-changes/ddl-strategy-flags.md b/content/en/docs/18.0/user-guides/schema-changes/ddl-strategy-flags.md index 8e13cef05..f2627fd3f 100644 --- a/content/en/docs/18.0/user-guides/schema-changes/ddl-strategy-flags.md +++ b/content/en/docs/18.0/user-guides/schema-changes/ddl-strategy-flags.md @@ -13,7 +13,9 @@ Vitess respects the following flags. They can be combined unless specifically in - `--allow-concurrent`: allow a migration to run concurrently to other migrations, rather than queue sequentially. Some restrictions apply, see [concurrent migrations](../concurrent-migrations). - `--allow-zero-in-date`: normally Vitess operates with a strict `sql_mode`. If you have columns such as `my_datetime DATETIME DEFAULT '0000-00-00 00:00:00'` and you wish to run DDL on these tables, Vitess will prevent the migration due to invalid values. Provide `--allow-zero-in-date` to allow either a fully zero-date or a zero-in-date inyour schema. See also [NO_ZERO_IN_DATE](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_no_zero_in_date) and [NO_ZERO_DATE](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_no_zero_date) documentation for [sql_mode](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html). --- `cut-over-threshold="`: set an explicit threshold and timeout for a `vitess` `ALTER TABLE` cut-over phase. The default cut-over threshold, if not specified, is `10s`. A `vitess` migration will not attempt to cut-over if the vstream, or replication lag, is more than the cut-over threshold. Also, during cut-over, table locks will timeout after the same cut-over threshold (aborting the operation). +- `--analyze-table`: for `ALTER TABLE` operation, and in `online/vitess` strategy, run an `ANALYZE NO_WRITE_TO_BINLOG TABLE` just before starting the migration process, to get better estimation of the number of rows on the migrated table. + +- `cut-over-threshold="`: set an explicit threshold and timeout for a `vitess` `ALTER TABLE` cut-over phase. The default cut-over threshold, if not specified, is `10s`. A `vitess` migration will not attempt to cut-over if the vstream, or replication lag, is more than the cut-over threshold. Also, during cut-over, table locks will timeout after the same cut-over threshold (aborting the operation). Normal values are in the range `5s`..`30s`. Too low and cut-over may never succeed because of the inherent async nature of `vitess` migrations. Too high and table locks will be placed for too long, effectively rendering the table inaccessible. - `--declarative`: mark the migration as declarative. You will define a desired schema state by supplying `CREATE` and `DROP` statements, ad Vitess will infer how to achieve the desired schema. If need be, it will generate an `ALTER` migration to convert to the new schema. See [declarative migrations](../declarative-migrations). diff --git a/content/en/docs/18.0/user-guides/schema-changes/postponed-migrations.md b/content/en/docs/18.0/user-guides/schema-changes/postponed-migrations.md index d5834d52f..0b58644f8 100644 --- a/content/en/docs/18.0/user-guides/schema-changes/postponed-migrations.md +++ b/content/en/docs/18.0/user-guides/schema-changes/postponed-migrations.md @@ -95,6 +95,13 @@ mysql> alter vitess_migration launch all; Launches all currently postponed migrations on all shards. +It is also possible to use `vtctlclient OnlineDDL` commands: + +```shell +$ vtctlclient OnlineDDL commerce launch 2201058f_f266_11ea_bab4_0242c0a8b007 +$ vtctlclient OnlineDDL commerce launch all +``` + Postponed launch is supported for all migrations. ## Postpone completion @@ -248,6 +255,14 @@ mysql> show vitess_migrations like '3091ef2a_4b87_11ec_a827_0a43f95f28a3' \G postpone_completion: 0 ``` + +It is also possible to use `vtctlclient OnlineDDL` commands: + +```shell +$ vtctlclient OnlineDDL commerce complete 2201058f_f266_11ea_bab4_0242c0a8b007 +$ vtctlclient OnlineDDL commerce complete all +``` + ### Supported migrations Postponed completion is supported for: diff --git a/content/en/docs/18.0/user-guides/schema-changes/unmanaged-schema-changes.md b/content/en/docs/18.0/user-guides/schema-changes/unmanaged-schema-changes.md index 4e4abe924..45a8aa21f 100644 --- a/content/en/docs/18.0/user-guides/schema-changes/unmanaged-schema-changes.md +++ b/content/en/docs/18.0/user-guides/schema-changes/unmanaged-schema-changes.md @@ -37,31 +37,6 @@ CREATE TABLE `demo` ( ``` In the above, we run a direct, synchronous, blocking `ALTER TABLE` statement. Knowing the table is in `commerce` keyspace, Vitess autodetects the relevant shards, and then autodetects which is the `primary` server in each shard. It then directly invokes the `ALTER TABLE` statement on all shards (concurrently), and the `vtctlclient` command only returns when all are complete. -Vitess will run some validations: - -```shell -$ vtctlclient ApplySchema -- --sql "ALTER TABLE demo add column status int" commerce -E0908 10:35:53.478462 3711762 main.go:67] remote error: rpc error: code = Unknown desc = schema change failed, ExecuteResult: { - "FailedShards": null, - "SuccessShards": null, - "CurSQLIndex": 0, - "Sqls": [ - "ALTER TABLE demo add column status int" - ], - "ExecutorErr": "rpc error: code = Unknown desc = TabletManager.PreflightSchema on zone1-0000000100 error: /usr/bin/mysql: exit status 1, output: ERROR 1060 (42S21) at line 3: Duplicate column name 'status'\n: /usr/bin/mysql: exit status 1, output: ERROR 1060 (42S21) at line 3: Duplicate column name 'status'\n", - "TotalTimeSpent": 87104194 -} -``` - -Vitess was able to determine that the migration is invalid because a column named `status` already exists. The statement never made it to the MySQL servers. These checks are not thorough, though they cover common scenarios. - -If the table is large, then `ApplySchema` will reject the statement, try to protect the user from blocking their production servers. You may override that by supplying `--allow_long_unavailability` as follows: - -```shell -$ vtctlclient ApplySchema -- --allow_long_unavailability --sql "ALTER TABLE demo modify id bigint unsigned" commerce -``` - - ## VTGate You may run DDL directly from VTGate just like you would send to a MySQL instance. For example: diff --git a/content/en/docs/releases/_index.md b/content/en/docs/releases/_index.md index c7c8c70ca..75b2a050a 100644 --- a/content/en/docs/releases/_index.md +++ b/content/en/docs/releases/_index.md @@ -18,21 +18,22 @@ Each major release is maintained for 1 year. > The latest and current vitess release is v17.0 ### v17.0 -- **Current version:** [v17.0.0](https://github.com/vitessio/vitess/releases/tag/v17.0.0) (2023-06-27) +- **Current version:** [v17.0.1](https://github.com/vitessio/vitess/releases/tag/v17.0.1) (2023-07-28) - **Initial GA release:** [v17.0.0](https://github.com/vitessio/vitess/releases/tag/v17.0.0) (2023-06-27) - **End of life:** 2024-06-27 +- **Patch releases:** [v17.0.1](https://github.com/vitessio/vitess/releases/tag/v17.0.1) ### v16.0 -- **Current version:** [v16.0.2](https://github.com/vitessio/vitess/releases/tag/v16.0.2) (2023-05-09) +- **Current version:** [v16.0.3](https://github.com/vitessio/vitess/releases/tag/v16.0.3) (2023-07-28) - **Initial GA release:** [v16.0.0](https://github.com/vitessio/vitess/releases/tag/v16.0.0) (2023-02-28) - **End of life:** 2024-02-28 -- **Patch releases:** [v16.0.1](https://github.com/vitessio/vitess/releases/tag/v16.0.1), [v16.0.2](https://github.com/vitessio/vitess/releases/tag/v16.0.2) +- **Patch releases:** [v16.0.1](https://github.com/vitessio/vitess/releases/tag/v16.0.1), [v16.0.2](https://github.com/vitessio/vitess/releases/tag/v16.0.2), [v16.0.3](https://github.com/vitessio/vitess/releases/tag/v16.0.3) ### v15.0 -- **Current version:** [v15.0.3](https://github.com/vitessio/vitess/releases/tag/v15.0.3) (2023-03-30) +- **Current version:** [v15.0.4](https://github.com/vitessio/vitess/releases/tag/v15.0.4) (2023-07-28) - **Initial GA release:** [v15.0.0](https://github.com/vitessio/vitess/releases/tag/v15.0.0) (2022-10-25) - **End of life:** 2023-10-25 -- **Patch releases:** [v15.0.1](https://github.com/vitessio/vitess/releases/tag/v15.0.1), [v15.0.2](https://github.com/vitessio/vitess/releases/tag/v15.0.2), [v15.0.3](https://github.com/vitessio/vitess/releases/tag/v15.0.3) +- **Patch releases:** [v15.0.1](https://github.com/vitessio/vitess/releases/tag/v15.0.1), [v15.0.2](https://github.com/vitessio/vitess/releases/tag/v15.0.2), [v15.0.3](https://github.com/vitessio/vitess/releases/tag/v15.0.3), [v15.0.4](https://github.com/vitessio/vitess/releases/tag/v15.0.4) ---- diff --git a/content/zh/docs/18.0/reference/vtctl.md b/content/zh/docs/18.0/reference/vtctl.md index 173c1c65e..2cdbdf62a 100644 --- a/content/zh/docs/18.0/reference/vtctl.md +++ b/content/zh/docs/18.0/reference/vtctl.md @@ -1085,17 +1085,16 @@ Updates the configuration of the MaxReplicationLag module. The configuration mus ### 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. +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. #### Example -
ApplySchema [-allow_long_unavailability] [-wait_replicas_timeout=10s] {-sql=<sql> || -sql-file=<filename>} <keyspace>
+
ApplySchema [-wait_replicas_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_replicas_timeout | Duration | The amount of time to wait for slaves to receive the schema change via replication. | diff --git a/layouts/partials/javascript.html b/layouts/partials/javascript.html index 610ea3bb0..da336260c 100644 --- a/layouts/partials/javascript.html +++ b/layouts/partials/javascript.html @@ -26,6 +26,8 @@ "use strict"; let index; let debounceTimer = null; + const _debug = false; + const debugLog = _debug ? console.log : () => { }; const currentUrl = window.location.pathname; const currentLocation = String(currentUrl).split("/"); const currentVersion = currentLocation[2]; @@ -139,6 +141,7 @@ } }); search(query); + trackSearchEvent(query); } function search(keywords) { @@ -169,23 +172,51 @@ // show the matched result results.forEach(function (result) { const doc = parse[result.ref]; - const element = template.content.cloneNode(true); - element.querySelector(".title").textContent = doc.title; - element.querySelector(".subtitle").textContent = doc.summary; - element.querySelector(".subtitle").setAttribute("href", doc.href); - element - .querySelector(".is-read-more") - .setAttribute("href", doc.href); - element.querySelector(".search-path").textContent = doc.path; - element - .querySelector(".search-path") - .setAttribute("href", doc.href); - - target.appendChild(element); + const searchResultItem = template.content.cloneNode(true) + .querySelector('.search-result-item'); + + const searchPath = searchResultItem.querySelector('a.search-path'); + searchPath.setAttribute('href', doc.href); + searchPath.textContent = doc.path; + + const title = searchResultItem.querySelector('a.title'); + title.setAttribute('href', doc.href); + title.textContent = doc.title; + + const subtitle = searchResultItem.querySelector('a.subtitle'); + subtitle.setAttribute('href', doc.href); + subtitle.textContent = doc.summary; + + searchResultItem.addEventListener('click', + () => trackSearchResultClick(doc.href, query)); + target.appendChild(searchResultItem); }, this); } } + const lunrSearchEventCategory = 'Lunr Search'; + + function trackSearchEvent(searchTerm) { + debugLog('trackSearchEvent: searchTerm = ' + searchTerm); + if (typeof gtag !== 'function') return; + gtag('event', 'search', { + event_category: lunrSearchEventCategory, + event_label: 'Search Input', + search_term: searchTerm, + }); + } + + function trackSearchResultClick(searchResultURL, searchTerm) { + debugLog(`trackSearchResultClick: searchTerm = ${searchTerm}, link = ${searchResultURL}`); + if (typeof gtag !== 'function') return; + gtag('event', 'click', { + event_category: lunrSearchEventCategory, + event_label: 'Search-result Click', + search_term: searchTerm, + value: searchResultURL, + }); + } + // click outside the search modal to close document.addEventListener("click", () => { searchPopover.style.display = "none"; diff --git a/layouts/partials/search-results.html b/layouts/partials/search-results.html index 6b40280e7..24a0acf51 100644 --- a/layouts/partials/search-results.html +++ b/layouts/partials/search-results.html @@ -6,7 +6,7 @@