Merge remote-tracking branch 'origin/prod' into kill-stmt-doc

Signed-off-by: Harshit Gangal <[email protected]>

content/en/docs/15.0/get-started/local.md

@@ -110,9 +110,9 @@ You are now ready to start your first cluster! Open a new terminal window to ens
 Start by copying the local examples included with Vitess to your preferred location. For our first example we will deploy a [single unsharded keyspace](../../concepts/keyspace). The file `101_initial_cluster.sh` is for example `1` phase `01`. Lets execute it now:
 
 ```sh
-mkdir -p ~/my-vitess-example/examples/local
-cp -r /usr/local/vitess/examples/local ~/my-vitess-example/examples
-cp -r /usr/local/vitess/web ~/my-vitess-example
+vitess_path=/usr/local/vitess
+mkdir ~/my-vitess-example
+cp -r ${vitess_path}/{examples,web} ~/my-vitess-example
 cd ~/my-vitess-example/examples/local
 ./101_initial_cluster.sh
 ```

content/en/docs/15.0/get-started/vttestserver-docker-image.md

@@ -72,16 +72,56 @@ Environment variables in docker can be specified using the `-e` aka `--env` flag
 The vtgate listens for MySQL connections on 3 + the `PORT` environment variable specified. i.e. if you specify `PORT` to be 33574, then vtgate will be listening to connections on 33577, on the `MYSQL_BIND_HOST` which defaults to localhost. But this port will be on the docker container side. To connect to vtgate externally from a MySQL client, you will need to publish that port as well and specify the `MYSQL_BIND_HOST` to `0.0.0.0`. This can be done via the `-p` aka `--publish` flag to docker. For eg: adding `-p 33577:33577` to the `docker
 run` command will publish the container's 33577 port to your local 33577 port, which can now be used to connect to the vtgate.
 
+### Persisting container data
+
+If you wish to keep the state of the test container across reboots, such as when running the vttestserver container as a database container in local application development environments, you may optionally pass the `--persistent_mode` flag, along with a `--data_dir` directory which is bound to a docker volume. Due to a bug, the `--port` argument must also be present for correct operation.
+
+When running in this mode, underlying MySQL table schemas and their data are persisted under the provided `--data_dir`.
+
+For example:
+
+```shell
+docker run --name=vttestserver \
+  -p 33577:33577 \
+  --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" \
+  --health-interval=5s \
+  --health-timeout=2s \
+  --health-retries=5 \
+  -v vttestserver_data:/vt/vtdataroot/vitess \
+  vitess/vttestserver:mysql57
+  /vt/bin/vttestserver \
+  --alsologtostderr \
+  --data_dir=/vt/vtdataroot/vitess \
+  --persistent_mode \
+  --port=33574 \
+  --mysql_bind_host=0.0.0.0 \
+  --keyspaces=test,unsharded \
+  --num_shards=2,1 \
+  --planner-version=gen4fallback
+```
+
 ## Example
 
 An example command to run the docker image is as follows :
 
 ```shell
-docker run --name=vttestserver -p 33577:33577 -e PORT=33574 -e PLANNER_VERSION=gen4fallback -e KEYSPACES=test,unsharded -e NUM_SHARDS=2,1 -e MYSQL_MAX_CONNECTIONS=70000 -e MYSQL_BIND_HOST=0.0.0.0 --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" --health-interval=5s --health-timeout=2s --health-retries=5 vitess/vttestserver:mysql57
+docker run --name=vttestserver \
+  -p 33577:33577 \
+  -e PORT=33574 \
+  -e PLANNER_VERSION=gen4fallback \
+  -e KEYSPACES=test,unsharded \
+  -e NUM_SHARDS=2,1 \
+  -e MYSQL_MAX_CONNECTIONS=70000 \
+  -e MYSQL_BIND_HOST=0.0.0.0 \
+  --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" \
+  --health-interval=5s \
+  --health-timeout=2s \
+  --health-retries=5 \
+  vitess/vttestserver:mysql57
 ```
 
 Now, we can connect to the vtgate from a MySQL client as follows :
- 
+
 ```shell
 mysql --host 127.0.0.1 --port 33577 --user "root"
 ```

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 <table>` 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 <vtgate params>
+mysql> SET WORKLOAD=OLAP;
+mysql> STREAM * FROM <table>;
+```
+
+</br>
+
+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

content/en/docs/16.0/get-started/local.md

@@ -111,9 +111,9 @@ You are now ready to start your first cluster! Open a new terminal window to ens
 Start by copying the local examples included with Vitess to your preferred location. For our first example we will deploy a [single unsharded keyspace](../../concepts/keyspace). The file `101_initial_cluster.sh` is for example `1` phase `01`. Lets execute it now:
 
 ```sh
-mkdir -p ~/my-vitess-example/examples
-cp -r <vitess source path>/examples ~/my-vitess-example/examples
-cp -r <vitess source path>/web ~/my-vitess-example
+vitess_path=/usr/local/vitess
+mkdir ~/my-vitess-example
+cp -r ${vitess_path}/{examples,web} ~/my-vitess-example
 cd ~/my-vitess-example/examples/local
 ./101_initial_cluster.sh
 ```

content/en/docs/16.0/get-started/vttestserver-docker-image.md

@@ -73,16 +73,54 @@ Environment variables in docker can be specified using the `-e` aka `--env` flag
 The vtgate listens for MySQL connections on 3 + the `PORT` environment variable specified. i.e. if you specify `PORT` to be 33574, then vtgate will be listening to connections on 33577, on the `MYSQL_BIND_HOST` which defaults to localhost. But this port will be on the docker container side. To connect to vtgate externally from a MySQL client, you will need to publish that port as well and specify the `MYSQL_BIND_HOST` to `0.0.0.0`. This can be done via the `-p` aka `--publish` flag to docker. For eg: adding `-p 33577:33577` to the `docker
 run` command will publish the container's 33577 port to your local 33577 port, which can now be used to connect to the vtgate.
 
+### Persisting container data
+
+If you wish to keep the state of the test container across reboots, such as when running the vttestserver container as a database container in local application development environments, you may optionally pass the `--persistent_mode` flag, along with a `--data_dir` directory which is bound to a docker volume. Due to a bug, the `--port` argument must also be present for correct operation.
+
+When running in this mode, underlying MySQL table schemas and their data are persisted under the provided `--data_dir`.
+
+For example:
+
+```shell
+docker run --name=vttestserver \
+  -p 33577:33577 \
+  --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" \
+  --health-interval=5s \
+  --health-timeout=2s \
+  --health-retries=5 \
+  -v vttestserver_data:/vt/vtdataroot/vitess \
+  vitess/vttestserver:mysql80
+  /vt/bin/vttestserver \
+  --alsologtostderr \
+  --data_dir=/vt/vtdataroot/vitess \
+  --persistent_mode \
+  --port=33574 \
+  --mysql_bind_host=0.0.0.0 \
+  --keyspaces=test,unsharded \
+  --num_shards=2,1
+```
+
 ## Example
 
 An example command to run the docker image is as follows :
 
 ```shell
-docker run --name=vttestserver -p 33577:33577 -e PORT=33574 -e KEYSPACES=test,unsharded -e NUM_SHARDS=2,1 -e MYSQL_MAX_CONNECTIONS=70000 -e MYSQL_BIND_HOST=0.0.0.0 --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" --health-interval=5s --health-timeout=2s --health-retries=5 vitess/vttestserver:mysql80
+docker run --name=vttestserver \
+  -p 33577:33577 \
+  -e PORT=33574 \
+  -e KEYSPACES=test,unsharded \
+  -e NUM_SHARDS=2,1 \
+  -e MYSQL_MAX_CONNECTIONS=70000 \
+  -e MYSQL_BIND_HOST=0.0.0.0 \
+  --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" \
+  --health-interval=5s \
+  --health-timeout=2s \
+  --health-retries=5 \
+  vitess/vttestserver:mysql80
 ```
 
 Now, we can connect to the vtgate from a MySQL client as follows :
- 
+
 ```shell
 mysql --host 127.0.0.1 --port 33577 --user "root"
 ```

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 <table>` 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 <vtgate params>
+mysql> SET WORKLOAD=OLAP;
+mysql> STREAM * FROM <table>;
+```
+
+</br>
+
+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

content/en/docs/16.0/reference/programs/vtctldclient/_index.md

@@ -6,6 +6,10 @@ series: vtctldclient
 
 Executes a cluster management command on the remote vtctld server.
 
+```
+vtctldclient [flags]
+```
+
 ### Options
 
 ```
@@ -20,7 +24,7 @@ Executes a cluster management command on the remote vtctld server.
 * [vtctldclient AddCellsAlias](./vtctldclient_addcellsalias/)	 - Defines a group of cells that can be referenced by a single name (the alias).
 * [vtctldclient ApplyRoutingRules](./vtctldclient_applyroutingrules/)	 - Applies the VSchema routing rules.
 * [vtctldclient ApplySchema](./vtctldclient_applyschema/)	 - Applies the schema change to the specified keyspace on every primary, running in parallel on all shards. The changes are then propagated to replicas via replication.
-* [vtctldclient ApplyShardRoutingRules](./vtctldclient_applyshardroutingrules/)	 - Applies VSchema shard routing rules.
+* [vtctldclient ApplyShardRoutingRules](./vtctldclient_applyshardroutingrules/)	 - Applies the provided shard routing rules.
 * [vtctldclient ApplyVSchema](./vtctldclient_applyvschema/)	 - Applies the VTGate routing schema to the provided keyspace. Shows the result after application.
 * [vtctldclient Backup](./vtctldclient_backup/)	 - Uses the BackupStorage service on the given tablet to create and store a new backup.
 * [vtctldclient BackupShard](./vtctldclient_backupshard/)	 - Finds the most up-to-date REPLICA, RDONLY, or SPARE tablet in the given shard and uses the BackupStorage service on that tablet to create and store a new backup.

content/en/docs/16.0/reference/programs/vtctldclient/vtctldclient_TabletExternallyReparented.md

@@ -10,7 +10,7 @@ Updates the topology record for the tablet's shard to acknowledge that an extern
 
 Updates the topology record for the tablet's shard to acknowledge that an external tool made this tablet the primary.
 
-See the Reparenting guide for more information: https://vitess.io/docs/user-guides/reparenting/#external-reparenting.
+See the Reparenting guide for more information: https://vitess.io/docs/user-guides/configuration-advanced/reparenting/#external-reparenting.
 
 
 ```

content/en/docs/17.0/get-started/local.md

@@ -87,9 +87,9 @@ You are now ready to start your first cluster! Open a new terminal window to ens
 Start by copying the local examples included with Vitess to your preferred location. For our first example we will deploy a [single unsharded keyspace](../../concepts/keyspace). The file `101_initial_cluster.sh` is for example `1` phase `01`. Lets execute it now:
 
 ```sh
-mkdir -p ~/my-vitess-example/examples
-cp -r <vitess source path>/examples ~/my-vitess-example/examples
-cp -r <vitess source path>/web ~/my-vitess-example
+vitess_path=/usr/local/vitess
+mkdir ~/my-vitess-example
+cp -r ${vitess_path}/{examples,web} ~/my-vitess-example
 cd ~/my-vitess-example/examples/local
 ./101_initial_cluster.sh
 ```

content/en/docs/17.0/get-started/vttestserver-docker-image.md

@@ -73,16 +73,54 @@ Environment variables in docker can be specified using the `-e` aka `--env` flag
 The vtgate listens for MySQL connections on 3 + the `PORT` environment variable specified. i.e. if you specify `PORT` to be 33574, then vtgate will be listening to connections on 33577, on the `MYSQL_BIND_HOST` which defaults to localhost. But this port will be on the docker container side. To connect to vtgate externally from a MySQL client, you will need to publish that port as well and specify the `MYSQL_BIND_HOST` to `0.0.0.0`. This can be done via the `-p` aka `--publish` flag to docker. For eg: adding `-p 33577:33577` to the `docker
 run` command will publish the container's 33577 port to your local 33577 port, which can now be used to connect to the vtgate.
 
+### Persisting container data
+
+If you wish to keep the state of the test container across reboots, such as when running the vttestserver container as a database container in local application development environments, you may optionally pass the `--persistent_mode` flag, along with a `--data_dir` directory which is bound to a docker volume. Due to a bug, the `--port` argument must also be present for correct operation.
+
+When running in this mode, underlying MySQL table schemas, their data, and the Vitess VSchema objects are persisted under the provided `--data_dir`.
+
+For example:
+
+```shell
+docker run --name=vttestserver \
+  -p 33577:33577 \
+  --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" \
+  --health-interval=5s \
+  --health-timeout=2s \
+  --health-retries=5 \
+  -v vttestserver_data:/vt/vtdataroot/vitess \
+  vitess/vttestserver:mysql80
+  /vt/bin/vttestserver \
+  --alsologtostderr \
+  --data_dir=/vt/vtdataroot/vitess \
+  --persistent_mode \
+  --port=33574 \
+  --mysql_bind_host=0.0.0.0 \
+  --keyspaces=test,unsharded \
+  --num_shards=2,1
+```
+
 ## Example
 
 An example command to run the docker image is as follows :
 
 ```shell
-docker run --name=vttestserver -p 33577:33577 -e PORT=33574 -e KEYSPACES=test,unsharded -e NUM_SHARDS=2,1 -e MYSQL_MAX_CONNECTIONS=70000 -e MYSQL_BIND_HOST=0.0.0.0 --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" --health-interval=5s --health-timeout=2s --health-retries=5 vitess/vttestserver:mysql80
+docker run --name=vttestserver \
+  -p 33577:33577 \
+  -e PORT=33574 \
+  -e KEYSPACES=test,unsharded \
+  -e NUM_SHARDS=2,1 \
+  -e MYSQL_MAX_CONNECTIONS=70000 \
+  -e MYSQL_BIND_HOST=0.0.0.0 \
+  --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" \
+  --health-interval=5s \
+  --health-timeout=2s \
+  --health-retries=5 \
+  vitess/vttestserver:mysql80
 ```
 
 Now, we can connect to the vtgate from a MySQL client as follows :
- 
+
 ```shell
 mysql --host 127.0.0.1 --port 33577 --user "root"
 ```

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 <table>` 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 <vtgate params>
+mysql> SET WORKLOAD=OLAP;
+mysql> STREAM * FROM <table>;
+```
+
+</br>
+
+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

content/en/docs/17.0/reference/programs/vtctldclient/vtctldclient_TabletExternallyReparented.md

@@ -10,7 +10,7 @@ Updates the topology record for the tablet's shard to acknowledge that an extern
 
 Updates the topology record for the tablet's shard to acknowledge that an external tool made this tablet the primary.
 
-See the Reparenting guide for more information: https://vitess.io/docs/user-guides/reparenting/#external-reparenting.
+See the Reparenting guide for more information: https://vitess.io/docs/user-guides/configuration-advanced/reparenting/#external-reparenting.
 
 
 ```