diff --git a/.travis.yml b/.travis.yml
index 312dfda58eb..0f65b297ea8 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -28,7 +28,7 @@ services:
language: go
go:
- - 1.11.x
+ - 1.12.x
go_import_path: vitess.io/vitess
env:
global:
diff --git a/bootstrap.sh b/bootstrap.sh
index 0476dc1e7eb..afcd975ccd6 100755
--- a/bootstrap.sh
+++ b/bootstrap.sh
@@ -20,24 +20,15 @@
# 0. Initialization and helper methods.
# 1. Installation of dependencies.
# 2. Installation of Go tools and vendored Go dependencies.
-# 3. Detection of installed MySQL and setting MYSQL_FLAVOR.
-# 4. Installation of development related steps e.g. creating Git hooks.
BUILD_TESTS=${BUILD_TESTS:-1}
+BUILD_PYTHON=${BUILD_PYTHON:-1}
+BUILD_JAVA=${BUILD_JAVA:-1}
#
# 0. Initialization and helper methods.
#
-# Run parallel make, based on number of cores available.
-case $(uname) in
- Linux) NB_CORES=$(grep -c '^processor' /proc/cpuinfo);;
- Darwin) NB_CORES=$(sysctl hw.ncpu | awk '{ print $2 }');;
-esac
-if [ -n "$NB_CORES" ]; then
- export MAKEFLAGS="-j$((NB_CORES+1)) -l${NB_CORES}"
-fi
-
function fail() {
echo "ERROR: $1"
exit 1
@@ -48,6 +39,20 @@ function fail() {
go version &>/dev/null || fail "Go is not installed or is not on \$PATH"
[[ "$(go version 2>&1)" =~ go1\.[1-9][1-9] ]] || fail "Go is not version 1.11+"
+# Create main directories.
+mkdir -p "$VTROOT/dist"
+mkdir -p "$VTROOT/bin"
+mkdir -p "$VTROOT/lib"
+mkdir -p "$VTROOT/vthook"
+
+# Install git hooks.
+echo "creating git hooks"
+mkdir -p "$VTTOP/.git/hooks"
+ln -sf "$VTTOP/misc/git/pre-commit" "$VTTOP/.git/hooks/pre-commit"
+ln -sf "$VTTOP/misc/git/commit-msg" "$VTTOP/.git/hooks/commit-msg"
+(cd "$VTTOP" && git config core.hooksPath "$VTTOP/.git/hooks")
+
+
# Set up the proper GOPATH for go get below.
if [ "$BUILD_TESTS" == 1 ] ; then
source ./dev.env
@@ -55,12 +60,6 @@ else
source ./build.env
fi
-# Create main directories.
-mkdir -p "$VTROOT/dist"
-mkdir -p "$VTROOT/bin"
-mkdir -p "$VTROOT/lib"
-mkdir -p "$VTROOT/vthook"
-
if [ "$BUILD_TESTS" == 1 ] ; then
# Set up required soft links.
# TODO(mberlin): Which of these can be deleted?
@@ -144,12 +143,13 @@ function install_grpc() {
PIP=$grpc_virtualenv/bin/pip
$PIP install --upgrade pip
$PIP install --upgrade --ignore-installed virtualenv
+ $PIP install mysql-connector-python
grpcio_ver=$version
$PIP install --upgrade grpcio=="$grpcio_ver" grpcio-tools=="$grpcio_ver"
}
-if [ "$BUILD_TESTS" == 1 ] ; then
+if [ "$BUILD_PYTHON" == 1 ] ; then
install_dep "gRPC" "1.16.0" "$VTROOT/dist/grpc" install_grpc
fi
@@ -186,9 +186,11 @@ function install_zookeeper() {
zip -d "lib/$zk-fatjar.jar" 'META-INF/*.SF' 'META-INF/*.RSA' 'META-INF/*SF' || true # needed for >=3.4.10 <3.5
rm -rf "$zk" "$zk.tar.gz"
}
-zk_ver=${ZK_VERSION:-3.4.14}
-install_dep "Zookeeper" "$zk_ver" "$VTROOT/dist/vt-zookeeper-$zk_ver" install_zookeeper
+zk_ver=${ZK_VERSION:-3.4.14}
+if [ "$BUILD_JAVA" == 1 ] ; then
+ install_dep "Zookeeper" "$zk_ver" "$VTROOT/dist/vt-zookeeper-$zk_ver" install_zookeeper
+fi
# Download and install etcd, link etcd binary into our root.
function install_etcd() {
@@ -252,7 +254,7 @@ function install_pymock() {
popd >/dev/null
}
pymock_version=1.0.1
-if [ "$BUILD_TESTS" == 1 ] ; then
+if [ "$BUILD_PYTHON" == 1 ] ; then
install_dep "py-mock" "$pymock_version" "$VTROOT/dist/py-mock-$pymock_version" install_pymock
fi
@@ -267,7 +269,7 @@ function install_selenium() {
# instead of go/dist/selenium/lib/python3.5/site-packages and then can't find module 'pip._vendor.requests'
PYTHONPATH='' $PIP install selenium
}
-if [ "$BUILD_TESTS" == 1 ] ; then
+if [ "$BUILD_PYTHON" == 1 ] ; then
install_dep "Selenium" "latest" "$VTROOT/dist/selenium" install_selenium
fi
@@ -281,10 +283,13 @@ function install_chromedriver() {
unzip -o -q chromedriver_linux64.zip -d "$dist"
rm chromedriver_linux64.zip
}
-if [ "$BUILD_TESTS" == 1 ] ; then
+if [ "$BUILD_PYTHON" == 1 ] ; then
install_dep "chromedriver" "73.0.3683.20" "$VTROOT/dist/chromedriver" install_chromedriver
fi
+if [ "$BUILD_PYTHON" == 1 ] ; then
+ PYTHONPATH='' $PIP install mysql-connector-python
+fi
#
# 2. Installation of Go tools and vendored Go dependencies.
@@ -324,59 +329,5 @@ go get -u $gotools || fail "Failed to download some Go tools with 'go get'. Plea
echo "Updating govendor dependencies..."
govendor sync || fail "Failed to download/update dependencies with govendor. Please re-run bootstrap.sh in case of transient errors."
-
-#
-# 3. Detection of installed MySQL and setting MYSQL_FLAVOR.
-#
-
-
-# find mysql and prepare to use libmysqlclient
-
-if [ "$BUILD_TESTS" == 1 ] ; then
- if [ -z "$MYSQL_FLAVOR" ]; then
- export MYSQL_FLAVOR=MySQL56
- echo "MYSQL_FLAVOR environment variable not set. Using default: $MYSQL_FLAVOR"
- fi
- case "$MYSQL_FLAVOR" in
- "MySQL56" | "MySQL80")
- myversion="$("$VT_MYSQL_ROOT/bin/mysql" --version)"
- [[ "$myversion" =~ Distrib\ 5\.[67] || "$myversion" =~ Ver\ 8\. ]] || fail "Couldn't find MySQL 5.6+ in $VT_MYSQL_ROOT. Set VT_MYSQL_ROOT to override search location."
- echo "Found MySQL 5.6+ installation in $VT_MYSQL_ROOT."
- ;;
-
- "MariaDB" | "MariaDB103")
- myversion="$("$VT_MYSQL_ROOT/bin/mysql" --version)"
- [[ "$myversion" =~ MariaDB ]] || fail "Couldn't find MariaDB in $VT_MYSQL_ROOT. Set VT_MYSQL_ROOT to override search location."
- echo "Found MariaDB installation in $VT_MYSQL_ROOT."
- ;;
-
- *)
- fail "Unsupported MYSQL_FLAVOR $MYSQL_FLAVOR"
- ;;
-
- esac
- # save the flavor that was used in bootstrap, so it can be restored
- # every time dev.env is sourced.
- echo "$MYSQL_FLAVOR" > "$VTROOT/dist/MYSQL_FLAVOR"
-fi
-
-#
-# 4. Installation of development related steps e.g. creating Git hooks.
-#
-
-if [ "$BUILD_TESTS" == 1 ] ; then
- # Create the Git hooks.
- echo "creating git hooks"
- mkdir -p "$VTTOP/.git/hooks"
- ln -sf "$VTTOP/misc/git/pre-commit" "$VTTOP/.git/hooks/pre-commit"
- ln -sf "$VTTOP/misc/git/prepare-commit-msg.bugnumber" "$VTTOP/.git/hooks/prepare-commit-msg"
- ln -sf "$VTTOP/misc/git/commit-msg" "$VTTOP/.git/hooks/commit-msg"
- (cd "$VTTOP" && git config core.hooksPath "$VTTOP/.git/hooks")
- echo
- echo "bootstrap finished - run 'source dev.env' in your shell before building."
-else
- echo
- echo "bootstrap finished - run 'source build.env' in your shell before building."
-fi
-
-
+echo
+echo "bootstrap finished - run 'source dev.env' or 'source build.env' in your shell before building."
diff --git a/build.env b/build.env
index a9d46a99b92..29e0d992dbb 100644
--- a/build.env
+++ b/build.env
@@ -36,4 +36,3 @@ export VTROOT
if [[ "$VTTOP" == "${VTTOP/\/src\/vitess.io\/vitess/}" ]]; then
echo "WARNING: VTTOP($VTTOP) does not contain src/vitess.io/vitess"
fi
-
diff --git a/config/mycnf/master_mariadb.cnf b/config/mycnf/master_mariadb.cnf
index 83f6f318e4c..1e41cd8f3ce 100644
--- a/config/mycnf/master_mariadb.cnf
+++ b/config/mycnf/master_mariadb.cnf
@@ -1,16 +1,8 @@
+# This file is auto-included when MariaDB (any version) is detected.
+
# enable strict mode so it's safe to compare sequence numbers across different server IDs.
gtid_strict_mode = 1
innodb_stats_persistent = 0
-innodb_support_xa = 0
-
-# Semi-sync replication is required for automated unplanned failover
-# (when the master goes away). Here we just load the plugin so it's
-# available if desired, but it's disabled at startup.
-#
-# If the -enable_semi_sync flag is used, VTTablet will enable semi-sync
-# at the proper time when replication is set up, or when masters are
-# promoted or demoted.
-plugin-load = rpl_semi_sync_master=semisync_master.so;rpl_semi_sync_slave=semisync_slave.so
# When semi-sync is enabled, don't allow fallback to async
# if you get no ack, or have no slaves. This is necessary to
diff --git a/config/mycnf/master_mariadb100.cnf b/config/mycnf/master_mariadb100.cnf
new file mode 100644
index 00000000000..ce85c641c13
--- /dev/null
+++ b/config/mycnf/master_mariadb100.cnf
@@ -0,0 +1,12 @@
+# This file is auto-included when MariaDB 10.0 is detected.
+
+innodb_support_xa = 0
+
+# Semi-sync replication is required for automated unplanned failover
+# (when the master goes away). Here we just load the plugin so it's
+# available if desired, but it's disabled at startup.
+#
+# If the -enable_semi_sync flag is used, VTTablet will enable semi-sync
+# at the proper time when replication is set up, or when masters are
+# promoted or demoted.
+plugin-load = rpl_semi_sync_master=semisync_master.so;rpl_semi_sync_slave=semisync_slave.so
diff --git a/config/mycnf/master_mariadb101.cnf b/config/mycnf/master_mariadb101.cnf
new file mode 100644
index 00000000000..d613b155d68
--- /dev/null
+++ b/config/mycnf/master_mariadb101.cnf
@@ -0,0 +1,12 @@
+# This file is auto-included when MariaDB 10.1 is detected.
+
+innodb_support_xa = 0
+
+# Semi-sync replication is required for automated unplanned failover
+# (when the master goes away). Here we just load the plugin so it's
+# available if desired, but it's disabled at startup.
+#
+# If the -enable_semi_sync flag is used, VTTablet will enable semi-sync
+# at the proper time when replication is set up, or when masters are
+# promoted or demoted.
+plugin-load = rpl_semi_sync_master=semisync_master.so;rpl_semi_sync_slave=semisync_slave.so
diff --git a/config/mycnf/master_mariadb102.cnf b/config/mycnf/master_mariadb102.cnf
new file mode 100644
index 00000000000..487baa9bf87
--- /dev/null
+++ b/config/mycnf/master_mariadb102.cnf
@@ -0,0 +1,12 @@
+# This file is auto-included when MariaDB 10.2 is detected.
+
+innodb_support_xa = 0
+
+# Semi-sync replication is required for automated unplanned failover
+# (when the master goes away). Here we just load the plugin so it's
+# available if desired, but it's disabled at startup.
+#
+# If the -enable_semi_sync flag is used, VTTablet will enable semi-sync
+# at the proper time when replication is set up, or when masters are
+# promoted or demoted.
+plugin-load = rpl_semi_sync_master=semisync_master.so;rpl_semi_sync_slave=semisync_slave.so
diff --git a/config/mycnf/master_mariadb103.cnf b/config/mycnf/master_mariadb103.cnf
index a4dfb50ab18..ac8b38404fd 100644
--- a/config/mycnf/master_mariadb103.cnf
+++ b/config/mycnf/master_mariadb103.cnf
@@ -1,3 +1,5 @@
+# This file is auto-included when MariaDB 10.3 is detected.
+
# enable strict mode so it's safe to compare sequence numbers across different server IDs.
gtid_strict_mode = 1
innodb_stats_persistent = 0
diff --git a/config/mycnf/master_mysql56.cnf b/config/mycnf/master_mysql56.cnf
index 2c802b2332a..dcb8a4e113f 100644
--- a/config/mycnf/master_mysql56.cnf
+++ b/config/mycnf/master_mysql56.cnf
@@ -1,3 +1,5 @@
+# This file is auto-included when MySQL 5.6 is detected.
+
# Options for enabling GTID
# https://dev.mysql.com/doc/refman/5.6/en/replication-gtids-howto.html
gtid_mode = ON
diff --git a/config/mycnf/master_mysql57.cnf b/config/mycnf/master_mysql57.cnf
new file mode 100644
index 00000000000..381b05ac14c
--- /dev/null
+++ b/config/mycnf/master_mysql57.cnf
@@ -0,0 +1,32 @@
+# This file is auto-included when MySQL 5.7 is detected.
+
+# Options for enabling GTID
+# https://dev.mysql.com/doc/refman/5.6/en/replication-gtids-howto.html
+gtid_mode = ON
+log_bin
+log_slave_updates
+enforce_gtid_consistency
+innodb_use_native_aio = 0
+
+# Crash-safe replication settings.
+master_info_repository = TABLE
+relay_log_info_repository = TABLE
+relay_log_purge = 1
+relay_log_recovery = 1
+
+# Semi-sync replication is required for automated unplanned failover
+# (when the master goes away). Here we just load the plugin so it's
+# available if desired, but it's disabled at startup.
+#
+# If the -enable_semi_sync flag is used, VTTablet will enable semi-sync
+# at the proper time when replication is set up, or when masters are
+# promoted or demoted.
+plugin-load = rpl_semi_sync_master=semisync_master.so;rpl_semi_sync_slave=semisync_slave.so
+
+# When semi-sync is enabled, don't allow fallback to async
+# if you get no ack, or have no slaves. This is necessary to
+# prevent alternate futures when doing a failover in response to
+# a master that becomes unresponsive.
+rpl_semi_sync_master_timeout = 1000000000000000000
+rpl_semi_sync_master_wait_no_slave = 1
+
diff --git a/config/mycnf/master_mysql80.cnf b/config/mycnf/master_mysql80.cnf
index f81761ad906..e92b794ef9b 100644
--- a/config/mycnf/master_mysql80.cnf
+++ b/config/mycnf/master_mysql80.cnf
@@ -1,3 +1,5 @@
+# This file is auto-included when MySQL 8.0 is detected.
+
# Options for enabling GTID
# https://dev.mysql.com/doc/refman/5.6/en/replication-gtids-howto.html
gtid_mode = ON
diff --git a/dev.env b/dev.env
index e31c16167e2..ca7bc608721 100644
--- a/dev.env
+++ b/dev.env
@@ -95,16 +95,6 @@ if [[ "$VT_MYSQL_ROOT" == "" ]]; then
fi
fi
-# restore MYSQL_FLAVOR, saved by bootstrap.sh
-if [ -r "$VTROOT/dist/MYSQL_FLAVOR" ]; then
- MYSQL_FLAVOR=$(cat "$VTROOT/dist/MYSQL_FLAVOR")
- export MYSQL_FLAVOR
-fi
-
-# mysql cgo library config
-if [ -z "$MYSQL_FLAVOR" ]; then
- export MYSQL_FLAVOR=MariaDB
-fi
PKG_CONFIG_PATH=$(prepend_path "$PKG_CONFIG_PATH" "$VTROOT/lib")
export PKG_CONFIG_PATH
diff --git a/doc/AdvancedFeaturesIndex.md b/doc/AdvancedFeaturesIndex.md
deleted file mode 100644
index c2fe3a753d2..00000000000
--- a/doc/AdvancedFeaturesIndex.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Advanced Features
-
-The pages below this navigation entry `Advanced Features` can be understood as an addition to the `User Guide`. Here we describe advanced Vitess features which you may want to enable or tune in a production setup.
-
-As of October 2017, many of these features are not documented yet. We plan to add pages for them later.
-
-Examples for undocumented features:
-
-* hot row protection in vttablet
-* vtgate buffer for lossless failovers
-* vttablet consolidator (avoids duplicated read queries to MySQL, turned on by default)
-* [vtexplain](https://github.com/vitessio/vitess/blob/master/doc/VtExplain.md)
diff --git a/doc/BackupAndRestore.md b/doc/BackupAndRestore.md
deleted file mode 100644
index 00f700e3111..00000000000
--- a/doc/BackupAndRestore.md
+++ /dev/null
@@ -1,250 +0,0 @@
-This document explains how to create and restore data backups with
-Vitess. Vitess uses backups for two purposes:
-
-* Provide a point-in-time backup of the data on a tablet.
-* Bootstrap new tablets in an existing shard.
-
-## Prerequisites
-
-Vitess stores data backups on a Backup Storage service, which is
-a
-[pluggable interface](https://github.com/vitessio/vitess/blob/master/go/vt/mysqlctl/backupstorage/interface.go).
-
-Currently, we have plugins for:
-
-* A network-mounted path (e.g. NFS)
-* Google Cloud Storage
-* Amazon S3
-* Ceph
-
-Before you can back up or restore a tablet, you need to ensure that the
-tablet is aware of the Backup Storage system that you are using. To do so,
-use the following command-line flags when starting a vttablet that has
-access to the location where you are storing backups.
-
-
-
-
-
Flags
-
-
-
-
-
backup_storage_implementation
-
Specifies the implementation of the Backup Storage interface to
- use.
- Current plugin options available are:
-
-
file: NFS or any other filesystem-mounted network
- drive.
-
gcs: Google Cloud Storage.
-
s3: Amazon S3.
-
ceph: Ceph Object Gateway S3 API.
-
-
-
-
-
backup_storage_hook
-
If set, the contents of every file to backup is sent to a hook. The
- hook receives the data for each file on stdin. It should echo the
- transformed data to stdout. Anything the hook prints to stderr will
- be printed in the vttablet logs.
- Hooks should be located in the vthook subdirectory of the
- VTROOT directory.
- The hook receives a -operation write or a
- -operation read parameter depending on the direction
- of the data processing. For instance, write would be for
- encryption, and read would be for decryption.
-
-
-
-
backup_storage_compress
-
This flag controls if the backups are compressed by the Vitess code.
- By default it is set to true. Use
- -backup_storage_compress=false to disable.
- This is meant to be used with a -backup_storage_hook
- hook that already compresses the data, to avoid compressing the data
- twice.
-
-
-
-
file_backup_storage_root
-
For the file plugin, this identifies the root directory
- for backups.
-
-
-
-
gcs_backup_storage_bucket
-
For the gcs plugin, this identifies the
- bucket
- to use.
-
-
-
s3_backup_aws_region
-
For the s3 plugin, this identifies the AWS region.
-
-
-
s3_backup_storage_bucket
-
For the s3 plugin, this identifies the AWS S3
- bucket.
-
-
-
ceph_backup_storage_config
-
For the ceph plugin, this identifies the path to a text
- file with a JSON object as configuration. The JSON object requires the
- following keys: accessKey, secretKey,
- endPoint and useSSL. Bucket name is computed
- from keyspace name and shard name and is separate for different
- keyspaces / shards.
-
-
-
restore_from_backup
-
Indicates that, when started with an empty MySQL instance, the
- tablet should restore the most recent backup from the specified
- storage plugin.
-
-
-
-
-### Authentication
-
-Note that for the Google Cloud Storage plugin, we currently only
-support
-[Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials).
-It means that access to Cloud Storage is automatically granted by virtue of
-the fact that you're already running within Google Compute Engine or Container
-Engine.
-
-For this to work, the GCE instances must have been created with
-the [scope](https://cloud.google.com/compute/docs/authentication#using) that
-grants read-write access to Cloud Storage. When using Container Engine, you can
-do this for all the instances it creates by adding `--scopes storage-rw` to the
-`gcloud container clusters create` command as shown in the [Vitess on Kubernetes
-guide]({% link getting-started/index.md %}#start-a-container-engine-cluster).
-
-## Creating a backup
-
-Run the following vtctl command to create a backup:
-
-``` sh
-vtctl Backup
-```
-
-In response to this command, the designated tablet performs the following
-sequence of actions:
-
-1. Switches its type to `BACKUP`. After this step, the tablet is no
- longer used by vtgate to serve any query.
-
-1. Stops replication, get the current replication position (to be saved in the
- backup along with the data).
-
-1. Shuts down its mysqld process.
-
-1. Copies the necessary files to the Backup Storage implementation that was
- specified when the tablet was started. Note if this fails, we still keep
- going, so the tablet is not left in an unstable state because of a storage
- failure.
-
-1. Restarts mysqld.
-
-1. Restarts replication (with the right semi-sync flags corresponding to its
- original type, if applicable).
-
-1. Switches its type back to its original type. After this, it will most likely
- be behind on replication, and not used by vtgate for serving until it catches
- up.
-
-## Restoring a backup
-
-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.
-
-* If the flag is present, Vitess tries to restore the most recent backup from
- the Backup Storage system when starting the tablet.
-* If the flag is absent, Vitess does not try to restore a backup to the
- tablet. This is the equivalent of starting a new tablet in a new shard.
-
-As noted in the [Prerequisites](#prerequisites) section, the flag is
-generally enabled all of the time for all of the tablets in a shard.
-By default, if Vitess cannot find a backup in the Backup Storage system,
-the tablet will start up empty. This behavior allows you to bootstrap a new
-shard before any backups exist.
-
-If the `-wait_for_backup_interval` flag is set to a value greater than zero,
-the tablet will instead keep checking for a backup to appear at that interval.
-This can be used to ensure tablets launched concurrently while an initial backup
-is being seeded for the shard (e.g. uploaded from cold storage or created by
-another tablet) will wait until the proper time and then pull the new backup
-when it's ready.
-
-``` sh
-vttablet ... -backup_storage_implementation=file \
- -file_backup_storage_root=/nfs/XXX \
- -restore_from_backup
-```
-
-## Managing backups
-
-**vtctl** provides two commands for managing backups:
-
-* [ListBackups]({% link reference/vtctl.md %}#listbackups) displays the
- existing backups for a keyspace/shard in chronological order.
-
- ``` sh
- vtctl ListBackups
- ```
-
-* [RemoveBackup]({% link reference/vtctl.md %}#removebackup) deletes a
- specified backup for a keyspace/shard.
-
- ``` sh
- RemoveBackup
- ```
-
-## Bootstrapping a new tablet
-
-Bootstrapping a new tablet is almost identical to restoring an existing tablet.
-The only thing you need to be cautious about is that the tablet specifies its
-keyspace, shard and tablet type when it registers itself at the topology.
-Specifically, make sure that the following vttablet parameters are set:
-
-``` sh
- -init_keyspace
- -init_shard
- -init_tablet_type replica|rdonly
-```
-
-The bootstrapped tablet will restore the data from the backup and then apply
-changes, which occurred after the backup, by restarting replication.
-
-
-## Backup Frequency
-
-We recommend to take backups regularly e.g. you should set up a cron
-job for it.
-
-To determine the proper frequency for creating backups, consider
-the amount of time that you keep replication logs and allow enough
-time to investigate and fix problems in the event that a backup
-operation fails.
-
-For example, suppose you typically keep four days of replication logs
-and you create daily backups. In that case, even if a backup fails,
-you have at least a couple of days from the time of the failure to
-investigate and fix the problem.
-
-## Concurrency
-
-The back-up and restore processes simultaneously copy and either
-compress or decompress multiple files to increase throughput. You
-can control the concurrency using command-line flags:
-
-* The vtctl [Backup]({% link reference/vtctl.md %}#backup) command uses the
- `-concurrency` flag.
-* vttablet uses the `-restore_concurrency` flag.
-
-If the network link is fast enough, the concurrency matches the CPU
-usage of the process during the backup or restore process.
-
diff --git a/doc/CodeReviews.md b/doc/CodeReviews.md
deleted file mode 100644
index 61e13385320..00000000000
--- a/doc/CodeReviews.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# Code Reviews
-
-Every GitHub pull request must go through a code review and get approved before it will be merged into the master branch.
-
-## What to look for in a Review
-
-Both authors and reviewers need to answer these general questions:
-
-* Does this change match an existing design / bug?
-* Is there proper unit test coverage for this change? All changes should
- increase coverage. We need at least integration test coverage when unit test
- coverage is not possible.
-* Is this change going to log too much? (Error logs should only happen when
- the component is in bad shape, not because of bad transient state or bad
- user queries)
-* Does this change match our coding conventions / style? Linter was run and is
- happy?
-* Does this match our current patterns? Example include RPC patterns,
- Retries / Waits / Timeouts patterns using Context, ...
-
-Additionally, we recommend every author to look over your own reviews just before committing them and check if you are following the recommendations below.
-We usually check these kinds of things while skimming through `git diff --cached` just before committing.
-
-* Scan the diffs as if you're the reviewer.
- * Look for files that shouldn't be checked in (temporary/generated files).
- * Googlers only: Remove Google confidential info (e.g. internal URLs).
- * Look for temporary code/comments you added while debugging.
- * Example: fmt.Println(`AAAAAAAAAAAAAAAAAA`)
- * Look for inconsistencies in indentation.
- * Use 2 spaces in everything except Go.
- * In Go, just use goimports.
-* Commit message format:
- * ```
- : This is a short description of the change.
-
- If necessary, more sentences follow e.g. to explain the intent of the change, how it fits into the bigger picture or which implications it has (e.g. other parts in the system have to be adapted.)
-
- Sometimes this message can also contain more material for reference e.g. benchmark numbers to justify why the change was implemented in this way.
- ```
-* Comments
- * `// Prefer complete sentences when possible.`
- * Leave a space after the comment marker `//`.
-
-During the review make sure you address all comments. Click Done (reviewable.io) or reply with "Done." (GitHub Review) to mark comments as addressed. There should be 0 unresolved discussions when it's ready to merge.
-
-## Assigning a Pull Request
-
-If you want to address your review to a particular set of teammates, add them as Assignee (righthand side on the pull request).
-They'll receive an email.
-
-During discussions, you can also refer to somebody using the *@username* syntax and they'll receive an email as well.
-
-If you want to receive notifications even when you aren't mentioned, you can go to the [repository page](https://github.com/vitessio/vitess) and click *Watch*.
-
-## Approving a Pull Request
-
-As a reviewer you can approve a pull request through two ways:
-
-* Approve the pull request via GitHub's new code review system
-* reply with a comment that contains the word *LGTM* (Looks Good To Me)
-
-## Merging a Pull Request
-
-Pull requests can be merged after they were approved and the Travis tests have passed.
-External contributions will be merged by a team member.
-Internal team members can merge their **own** pull requests.
-
-## Internal Bug Numbers
-
-Most of the bugs the team is working on are tracked internally.
-We reference to them as `b/########` or `BUG=########` in commit messages and comments.
-External users can ignore these.
diff --git a/doc/Concepts.md b/doc/Concepts.md
deleted file mode 100644
index acb87277522..00000000000
--- a/doc/Concepts.md
+++ /dev/null
@@ -1,221 +0,0 @@
-This document defines common Vitess concepts and terminology.
-
-## Keyspace
-
-A *keyspace* is a logical database. In the unsharded case, it maps directly
-to a MySQL database name. If [sharded](https://en.wikipedia.org/wiki/Shard_(database_architecture)),
-a keyspace maps to multiple MySQL databases. However, it appears as a single
-database to the application.
-
-Reading data from a keyspace is like reading from a MySQL database. However,
-depending on the consistency requirements of the read operation, Vitess
-might fetch the data from a master database or from a replica. By routing
-each query to the appropriate database, Vitess allows your code to be
-structured as if it were reading from a single MySQL database.
-
-
-## Keyspace ID
-
-The *keyspace ID* is the value that is used to decide on which shard a given
-row lives. [Range-based Sharding]({% link user-guide/sharding.md %}#range-based-sharding)
-refers to creating shards that each cover a particular range of keyspace IDs.
-
-Using this technique means you can split a given shard by replacing it with two
-or more new shards that combine to cover the original range of keyspace IDs,
-without having to move any records in other shards.
-
-The keyspace ID itself is computed using a function of some column in your data,
-such as the user ID. Vitess allows you to choose from a variety of functions
-([vindexes]({% link user-guide/vschema.md %}#vindex))
-to perform this mapping. This allows you to choose the right one to achieve optimal
-distribution of the data across shards.
-
-## VSchema
-
-A [VSchema]({% link user-guide/vschema.md %}) allows you to describe how data is organized
-within keyspaces and shards. This information is used for routing queries, and also during
-resharding operations.
-
-For a Keyspace, you can specify if it's sharded or not. For sharded keyspaces, you can specify
-the list of vindexes for each table.
-
-Vitess also supports [sequence generators]({% link user-guide/vschema.md %}#sequences)
-that can be used to generate new ids that work like MySQL auto increment columns.
-The VSchema allows you to associate table columns to sequence tables.
-If no value is specified for such a column, then VTGate will know to use
-the sequence table to generate a new value for it.
-
-
-## Shard
-
-A *shard* is a division within a keyspace. A shard typically contains one MySQL
-master and many MySQL slaves.
-
-Each MySQL instance within a shard has the same data (excepting some replication
-lag). The slaves can serve read-only traffic (with eventual consistency guarantees),
-execute long-running data analysis tools, or perform administrative tasks
-(backup, restore, diff, etc.).
-
-An unsharded keyspace has effectively one shard.
-Vitess names the shard `0` by convention. When sharded, a keyspace has `N`
-shards with non-overlapping data.
-
-### Resharding
-
-Vitess supports [dynamic resharding]({% link user-guide/sharding.md %}#resharding),
-in which the number of shards is changed on a live cluster. This can be either
-splitting one or more shards into smaller pieces, or merging neighboring shards
-into bigger pieces.
-
-During dynamic resharding, the data in the source shards is copied into the
-destination shards, allowed to catch up on replication, and then compared
-against the original to ensure data integrity. Then the live serving
-infrastructure is shifted to the destination shards, and the source shards are
-deleted.
-
-## Tablet
-
-A *tablet* is a combination of a `mysqld` process and a corresponding `vttablet`
-process, usually running on the same machine.
-
-Each tablet is assigned a *tablet type*, which specifies what role it currently
-performs.
-
-### Tablet Types
-
-* **master** - A *replica* tablet that happens to currently be the MySQL master
- for its shard.
-* **replica** - A MySQL slave that is eligible to be promoted to *master*.
- Conventionally, these are reserved for serving live, user-facing
- requests (like from the website's frontend).
-* **rdonly** - A MySQL slave that cannot be promoted to *master*.
- Conventionally, these are used for background processing jobs,
- such as taking backups, dumping data to other systems, heavy
- analytical queries, MapReduce, and resharding.
-* **backup** - A tablet that has stopped replication at a consistent snapshot,
- so it can upload a new backup for its shard. After it finishes,
- it will resume replication and return to its previous type.
-* **restore** - A tablet that has started up with no data, and is in the process
- of restoring itself from the latest backup. After it finishes,
- it will begin replicating at the GTID position of the backup,
- and become either *replica* or *rdonly*.
-* **drained** - A tablet that has been reserved by a Vitess background
- process (such as rdonly tablets for resharding).
-
-
-
-## Keyspace Graph
-
-The *keyspace graph* allows Vitess to decide which set of shards to use for a
-given keyspace, cell, and tablet type.
-
-### Partitions
-
-During horizontal resharding (splitting or merging shards), there can be shards
-with overlapping key ranges. For example, the source shard of a split may serve
-`c0-d0` while its destination shards serve `c0-c8` and `c8-d0` respectively.
-
-Since these shards need to exist simultaneously during the migration,
-the keyspace graph maintains a list (called a *partitioning* or just a *partition*)
-of shards whose ranges cover all possible keyspace ID values, while being
-non-overlapping and contiguous. Shards can be moved in and out of this list to
-determine whether they are active.
-
-The keyspace graph stores a separate partitioning for each `(cell, tablet type)` pair.
-This allows migrations to proceed in phases: first migrate *rdonly* and
-*replica* requests, one cell at a time, and finally migrate *master* requests.
-
-### Served From
-
-During vertical resharding (moving tables out from one keyspace to form a new
-keyspace), there can be multiple keyspaces that contain the same table.
-
-Since these multiple copies of the table need to exist simultaneously during
-the migration, the keyspace graph supports keyspace redirects, called
-`ServedFrom` records. That enables a migration flow like this:
-
-1. Create `new_keyspace` and set its `ServedFrom` to point to `old_keyspace`.
-1. Update the app to look for the tables to be moved in `new_keyspace`.
- Vitess will automatically redirect these requests to `old_keyspace`.
-1. Perform a vertical split clone to copy data to the new keyspace and start
- filtered replication.
-1. Remove the `ServedFrom` redirect to begin actually serving from `new_keyspace`.
-1. Drop the now unused copies of the tables from `old_keyspace`.
-
-There can be a different `ServedFrom` record for each `(cell, tablet type)` pair.
-This allows migrations to proceed in phases: first migrate *rdonly* and
-*replica* requests, one cell at a time, and finally migrate *master* requests.
-
-## Replication Graph
-
-The *replication graph* identifies the relationships between master
-databases and their respective replicas. During a master failover,
-the replication graph enables Vitess to point all existing replicas
-to a newly designated master database so that replication can continue.
-
-## Topology Service
-
-The *[Topology Service]({% link user-guide/topology-service.md %})*
-is a set of backend processes running on different servers.
-Those servers store topology data and provide a distributed locking service.
-
-Vitess uses a plug-in system to support various backends for storing topology
-data, which are assumed to provide a distributed, consistent key-value store.
-By default, our [local example]({% link getting-started/local-instance.md %})
-uses the ZooKeeper plugin, and the [Kubernetes example]({% link getting-started/index.md %})
-uses etcd.
-
-The topology service exists for several reasons:
-
-* It enables tablets to coordinate among themselves as a cluster.
-* It enables Vitess to discover tablets, so it knows where to route queries.
-* It stores Vitess configuration provided by the database administrator that is
- needed by many different servers in the cluster, and that must persist between
- server restarts.
-
-A Vitess cluster has one global topology service, and a local topology service
-in each cell. Since *cluster* is an overloaded term, and one Vitess cluster is
-distinguished from another by the fact that each has its own global topology
-service, we refer to each Vitess cluster as a **toposphere**.
-
-### Global Topology
-
-The global topology stores Vitess-wide data that does not change frequently.
-Specifically, it contains data about keyspaces and shards as well as the
-master tablet alias for each shard.
-
-The global topology is used for some operations, including reparenting and
-resharding. By design, the global topology server is not used a lot.
-
-In order to survive any single cell going down, the global topology service
-should have nodes in multiple cells, with enough to maintain quorum in the
-event of a cell failure.
-
-### Local Topology
-
-Each local topology contains information related to its own cell.
-Specifically, it contains data about tablets in the cell, the keyspace graph
-for that cell, and the replication graph for that cell.
-
-The local topology service must be available for Vitess to discover tablets
-and adjust routing as tablets come and go. However, no calls to the topology
-service are made in the critical path of serving a query at steady state.
-That means queries are still served during temporary unavailability of topology.
-
-## Cell (Data Center)
-
-A *cell* is a group of servers and network infrastructure collocated in an area,
-and isolated from failures in other cells. It is typically either a full data
-center or a subset of a data center, sometimes called a *zone* or *availability zone*.
-Vitess gracefully handles cell-level failures, such as when a cell is cut off the network.
-
-Each cell in a Vitess implementation has a [local topology service](#topology-service),
-which is hosted in that cell. The topology service contains most of the
-information about the Vitess tablets in its cell.
-This enables a cell to be taken down and rebuilt as a unit.
-
-Vitess limits cross-cell traffic for both data and metadata.
-While it may be useful to also have the ability to route read traffic to
-individual cells, Vitess currently serves reads only from the local cell.
-Writes will go cross-cell when necessary, to wherever the master for that shard
-resides.
diff --git a/doc/Contributing.md b/doc/Contributing.md
deleted file mode 100644
index 70bf486e408..00000000000
--- a/doc/Contributing.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Contributing to Vitess
-
-You want to contribute to Vitess? That's awesome!
-
-We're looking forward to any contribution! Before you start larger contributions, make sure to reach out first and discuss your plans with us.
-
-This page describes for new contributors how to make yourself familiar with Vitess and the programming language Go.
-
-## Learning Go
-
-Vitess was one of the early adaptors of [Google's programming language Go](https://golang.org/).
-
-We love it for its simplicity (e.g. compared to C++ or Java) and performance (e.g. compared to Python).
-
-Contributing to our server code will require you to learn Go. We recommend to read the following resources.
-
-### Go Tour
-
-https://tour.golang.org/
-
-The Go tour is a browser based tutorial which explains the different concepts of the programming language.
-It's interactive i.e. you can change and run all examples on the right side.
-The later steps also have specific exercises which you're supposed to implement yourself.
-It's a lot of fun and demonstrates how simple it is to write Go code.
-
-### Go Readability
-
-While there's no Go style guide, there is a set of recommendations in the Go community which add up to an implicit style guide.
-To make sure you're writing idiomatic Go code, please read the following documents:
-
-* Go Readability slides: https://talks.golang.org/2014/readability.slide
- * Talk about Go readability with many specific examples.
-* `Effective Go`: https://golang.org/doc/effective_go.html
- * Recommendations for writing good Go code.
-* Go Code Review Comments: https://github.com/golang/go/wiki/CodeReviewComments
- * The closest thing to a style guide.
-
-### Other Resources
-
-If you're unsure about Go's behavior or syntax, we recommend to look it up in the specification: https://golang.org/ref/spec
-It is well written and easy to understand.
-
-### Appreciating Go
-
-After using Go for several weeks, we hope that you'll start to love Go as much as we do.
-
-In our opinion, the song "Write in Go" from ScaleAbility, a Google acapella band, perfectly captures what's so special about Go. Watch it and enjoy that you learnt Go: www.youtube.com/watch?v=LJvEIjRBSDA
-
-## Learning Vitess
-
-Vitess is a complex distributed system. There are a few design docs in the `/doc` section. The best way to ramp up on vitess is by starting to use it.
-Then, you can dive into the code to see how the various parts work. For questions, the best place to get them answered is by asking on the slack channel.
-You can sign up to the channel by clicking on the top right link at vitess.io.
diff --git a/doc/FAQ.md b/doc/FAQ.md
deleted file mode 100644
index d34acbc4b0a..00000000000
--- a/doc/FAQ.md
+++ /dev/null
@@ -1,77 +0,0 @@
-## Does the application need to know about the sharding scheme underneath Vitess?
-
-The application does not need to know about how the data is sharded. This information is stored in a VSchema which the VTGates use to automatically route your queries. This allows the application to connect to vitess and use it as if it’s a single giant database server.
-
-## Can I address a specific shard if I want to?
-
-If necessary, you can access a specific shard by connecting to it using the shard specific database name. For a keyspace `ks` and shard `-80`, you would connect to `ks:-80`.
-
-## How do I choose between master vs. replica for queries?
-
-You can qualify the keyspace name with the desired tablet type using the `@` suffix. This can be specified as part of the connection as the database name, or can be changed on the fly through the `USE` command.
-
-For example, `ks@master` will select `ks` as the default keyspace with all queries being sent to the master. Consequently `ks@replica` will load balance requests across all `REPLICA` tablet types, and `ks@rdonly` will choose `RDONLY`.
-
-You can also specify the database name as `@master`, etc, which instructs vitess that no default keyspace was specified, but that the requests are for the specified tablet type.
-
-If no tablet type was specified, then VTGate chooses its default, which can be overridden with the `-default_tablet_type` command line argument.
-
-## There seems to be a 10,000 row limit per query. What if I want to do a full table scan?
-
-Vitess supports different modes. In OLTP mode, the result size is typically limited to a preset number (10,000 rows by default). This limit can be adjusted based on your needs.
-
-However, OLAP mode has no limit to the number of rows returned. In order to change to this mode, you may issue the following command before executing your query:
-
-```
-set workload='olap'
-```
-
-You can also set the workload to `dba` mode, which allows you to override the implicit timeouts that exist in vttablet. However, this mode should be used judiciously as it supersedes shutdown and reparent commands.
-
-The general convention is to send OLTP queries to `REPLICA` tablet types, and OLAP queries to `RDONLY`.
-
-## Is there a list of supported/unsupported queries?
-
-The list of unsupported constructs is currently in the form of test cases contained in this [test file](https://github.com/vitessio/vitess/blob/master/go/vt/vtgate/planbuilder/testdata/unsupported_cases.txt). However, contrary to the test cases, there is limited support for SET, DDL and DBA constructs. This will be documented soon.
-
-
-## If I have a log of all queries from my app. Is there a way I can try them against vitess to see how they’ll work?
-
-Yes. The [vtexplain tool]({% link user-guide/vtexplain.md %}) can be used to preview how your queries will be executed by vitess. It can also be used to try different sharding scenarios before deciding on one.
-
-## Does the Primary Vindex for a tablet have to be the same as its Primary Key.
-
-It is not necessary that a Primary Vindex be the same as the Primary Key. In fact, there are many use cases where you would not want this. For example, if there are tables with one-to-many relationships, the Primary Vindex of the main table is likely to be the same as the Primary Key. However, if you want the rows of the secondary table to reside in the same shard as the parent row, the Primary Vindex for that table must be the foreign key that points to the main table. A typical example is a `user` and `order` table. In this case, the order table has the `user_id` as a foreign key to the `id` of the `user` table. The `order_id` may be the primary key for `order`, but you may still want to choose `user_id` as Primary Vindex, which will make a user's orders live in the same shard as the user.
-
-## How do I connect to vtgate using mysql protocol?
-
-If you look at the example [vtgate-up.sh script](https://github.com/vitessio/vitess/blob/master/examples/local/vtgate-up.sh), you'll see the following lines:
-
-
-```
- -mysql_server_port $mysql_server_port \
- -mysql_server_socket_path $mysql_server_socket_path \
- -mysql_auth_server_static_file "./mysql_auth_server_static_creds.json" \
-```
-
-In that example, vtgate accepts mysql connections on port 15306, and the authentication info is stored in the json file. So, you should be able to connect to it using the following command:
-
-```
-mysql -h 127.0.0.1 -P 15306 -u mysql_user --password=mysql_password
-```
-
-## Can I override the default db name from `vt_xxx` to my own?
-
-Yes. You can start vttablet with the `-init_db_name_override` command line option to specify a different db name. There is no downside to performing this override.
-
-## I cannot start a cluster, and see these errors in the logs: Could not open required defaults file: /path/to/my.cnf
-
-Most likely this means that apparmor is running on your server and is preventing vitess processes from accessing the my.cnf file. The workaround is to uninstall apparmor:
-
-```
-sudo service apparmor stop
-sudo service apparmor teardown
-sudo update-rc.d -f apparmor remove
-```
-
-You may also need to reboot the machine after this. Many programs automatically install apparmor, so you may need to uninstall again.
diff --git a/doc/GettingStarted.md b/doc/GettingStarted.md
deleted file mode 100644
index f8e42628b5e..00000000000
--- a/doc/GettingStarted.md
+++ /dev/null
@@ -1,673 +0,0 @@
-You can build Vitess using either [Docker](#docker-build) or a
-[manual](#manual-build) build process.
-
-If you run into issues or have questions, please post on our
-[forum](https://groups.google.com/forum/#!forum/vitess).
-
-## Docker Build
-
-To run Vitess in Docker, you can either use our pre-built images on [Docker Hub](https://hub.docker.com/u/vitess/), or build them yourself.
-
-### Docker Hub Images
-
-* The [vitess/base](https://hub.docker.com/r/vitess/base/) image contains a full
- development environment, capable of building Vitess and running integration tests.
-
-* The [vitess/lite](https://hub.docker.com/r/vitess/lite/) image contains only
- the compiled Vitess binaries, excluding ZooKeeper. It can run Vitess, but
- lacks the environment needed to build Vitess or run tests. It's primarily used
- for the [Vitess on Kubernetes]({% link getting-started/index.md %}) guide.
-
-For example, you can directly run `vitess/base`, and Docker will download the
-image for you:
-
-``` sh
-$ sudo docker run -ti vitess/base bash
-vitess@32f187ef9351:/vt/src/vitess.io/vitess$ make build
-```
-
-Now you can proceed to [start a Vitess cluster](#start-a-vitess-cluster) inside
-the Docker container you just started. Note that if you want to access the
-servers from outside the container, you'll need to expose the ports as described
-in the [Docker Engine Reference Guide](https://docs.docker.com/engine/reference/run/#/expose-incoming-ports).
-
-For local testing, you can also access the servers on the local IP address
-created for the container by Docker:
-
-``` sh
-$ docker inspect 32f187ef9351 | grep IPAddress
-### example output:
-# "IPAddress": "172.17.3.1",
-```
-
-### Custom Docker Image
-
-You can also build Vitess Docker images yourself to include your
-own patches or configuration data. The
-[Dockerfile](https://github.com/vitessio/vitess/blob/master/Dockerfile)
-in the root of the Vitess tree builds the `vitess/base` image.
-The [docker](https://github.com/vitessio/vitess/tree/master/docker)
-subdirectory contains scripts for building other images, such as `vitess/lite`.
-
-Our `Makefile` also contains rules to build the images. For example:
-
-``` sh
-# Create vitess/bootstrap, which prepares everything up to ./bootstrap.sh
-vitess$ make docker_bootstrap
-# Create vitess/base from vitess/bootstrap by copying in your local working directory.
-vitess$ make docker_base
-```
-
-## Manual Build
-
-The following sections explain the process for manually building
-Vitess without Docker.
-
-### Install Dependencies
-
-We currently test Vitess regularly on Ubuntu 14.04 (Trusty) and Debian 8 (Jessie).
-OS X 10.11 (El Capitan) should work as well, the installation instructions are below.
-
-#### Ubuntu and Debian
-
-In addition, Vitess requires the software and libraries listed below.
-
-1. [Install Go 1.11+](https://golang.org/doc/install).
-
-2. Install [MariaDB 10.0](https://downloads.mariadb.org/) or
- [MySQL 5.6](https://dev.mysql.com/downloads/mysql). You can use any
- installation method (src/bin/rpm/deb), but be sure to include the client
- development headers (`libmariadbclient-dev` or `libmysqlclient-dev`).
-
- The Vitess development team currently tests against MariaDB 10.0.21
- and MySQL 5.6.27.
-
- If you are installing MariaDB, note that you must install version 10.0 or
- higher. If you are using `apt-get`, confirm that your repository
- offers an option to install that version. You can also download the source
- directly from [mariadb.org](https://downloads.mariadb.org/mariadb/).
-
- If you are using Ubuntu 14.04 with MySQL 5.6, the default install may be
- missing a file too, `/usr/share/mysql/my-default.cnf`. It would show as an
- error like `Could not find my-default.cnf`. If you run into this, just add
- it with the following contents:
-
- ```
- [mysqld]
- sql_mode=NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES
- ```
-
-3. Uninstall or disable `AppArmor`. Some versions of MySQL come with default
- AppArmor configurations that the Vitess tools don't recognize yet. This causes
- various permission failures when Vitess initializes MySQL instances through
- the `mysqlctl` tool. This is only an issue for a test environment. If AppArmor
- is necessary in production, you can configure the MySQL instances appropriately
- without going through mysqlctl.
-
- ``` sh
- $ sudo service apparmor stop
- $ sudo service apparmor teardown
- $ sudo update-rc.d -f apparmor remove
- ```
-
- Reboot, just to be sure that `AppArmor` is fully disabled.
-
-
-4. Select a lock service from the options listed below. It is technically
- possible to use another lock server, but plugins currently exist only
- for ZooKeeper, etcd and consul.
- - ZooKeeper 3.4.14 is included by default.
- - [Install etcd v3.0+](https://github.com/coreos/etcd/releases).
- If you use etcd, remember to include the `etcd` command
- on your path.
- - [Install Consul](https://www.consul.io/).
- If you use consul, remember to include the `consul` command
- on your path.
-
-5. Install the following other tools needed to build and run Vitess:
- - make
- - automake
- - libtool
- - python-dev
- - python-virtualenv
- - python-mysqldb
- - libssl-dev
- - g++
- - git
- - pkg-config
- - bison
- - curl
- - unzip
-
- These can be installed with the following apt-get command:
-
- ``` sh
- $ sudo apt-get install make automake libtool python-dev python-virtualenv python-mysqldb libssl-dev g++ git pkg-config bison curl unzip
- ```
-
-6. If you decided to use ZooKeeper in step 3, you also need to install a
- Java Runtime, such as OpenJDK.
-
- ``` sh
- $ sudo apt-get install openjdk-7-jre
- ```
-
-#### OS X
-
-1. [Install Homebrew](https://brew.sh/). If your /usr/local directory is not empty and you never used Homebrew before,
- it will be
- [mandatory](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/El_Capitan_and_Homebrew.md)
- to run the following command:
-
- ``` sh
- sudo chown -R $(whoami):admin /usr/local
- ```
-
-2. On OS X, MySQL 5.6 has to be used, MariaDB doesn't work for some reason yet. It should be installed from Homebrew
- (`install steps are below`).
-
-3. If Xcode is installed (with Console tools, which should be bundled automatically since the 7.1 version), all
- the dev dependencies should be satisfied in this step. If no Xcode is present, it is necessary to install pkg-config.
-
- ``` sh
- brew install pkg-config
- ```
-
-4. ZooKeeper is used as lock service.
-
-5. Run the following commands:
-
- ``` sh
- brew install go automake libtool python git bison curl wget mysql56
- pip install --upgrade pip setuptools
- pip install virtualenv
- pip install MySQL-python
- pip install tox
-
- ```
-
-6. The Vitess bootstrap script makes some checks for the go runtime, so it is recommended to have the following
- commands in your ~/.profile or ~/.bashrc or ~/.zshrc or ~/.bash_profile:
-
- ``` sh
- export PATH="/usr/local/opt/mysql@5.6/bin:$PATH"
- export PATH=/usr/local/go/bin:$PATH
- export GOROOT=/usr/local/go
- ```
-
-7. For the Vitess hostname resolving functions to work correctly, a new entry has to be added into the /etc/hosts file
- with the current LAN IP address of the computer (preferably IPv4) and the current hostname, which you get by
- typing the 'hostname' command in the terminal.
-
- It is also a good idea to put the following line to [force the Go DNS resolver](https://golang.org/doc/go1.5#net)
- in your ~/.profile or ~/.bashrc or ~/.zshrc:
-
- ```
- export GODEBUG=netdns=go
- ```
-
-### Build Vitess
-
-1. Navigate to the directory where you want to download the Vitess
- source code and clone the Vitess Github repo. After doing so,
- navigate to the `src/vitess.io/vitess` directory. For go to work
- correctly, you should create a symbolic link to this inide your ${HOME}/go/src
-
- ``` sh
- cd $WORKSPACE
- git clone https://github.com/vitessio/vitess.git \
- src/vitess.io/vitess
- ln -s src/vitess.io ${HOME}/go/src/vitess.io
- cd ${HOME}/go/src/vitess.io/vitess
- ```
-
-1. Set the `MYSQL_FLAVOR` environment variable. Choose the appropriate
- value for your database. This value is case-sensitive.
-
- ``` sh
- # export MYSQL_FLAVOR=MariaDB
- # or (mandatory for OS X)
- export MYSQL_FLAVOR=MySQL56
- ```
-
-1. If your selected database installed in a location other than `/usr/bin`,
- set the `VT_MYSQL_ROOT` variable to the root directory of your
- MariaDB installation. For example, if mysql is installed in
- `/usr/local/mysql`, run the following command.
-
- ``` sh
- # export VT_MYSQL_ROOT=/usr/local/mysql
-
- # on OS X, this is the correct value:
- export VT_MYSQL_ROOT=/usr/local/opt/mysql@5.6
- ```
-
- Note that the command indicates that the `mysql` executable should
- be found at `/usr/local/opt/mysql@5.6/bin/mysql`.
-
-1. Run `mysqld --version` and confirm that you
- are running the correct version of MariaDB or MySQL. The value should
- be 10 or higher for MariaDB and 5.6.x for MySQL.
-
-1. Build Vitess using the commands below. Note that the
- `bootstrap.sh` script needs to download some dependencies.
- If your machine requires a proxy to access the Internet, you will need
- to set the usual environment variables (e.g. `http_proxy`,
- `https_proxy`, `no_proxy`).
-
- Run the boostrap.sh script:
-
- ``` sh
- ./bootstrap.sh
- ### example output:
- # skipping zookeeper build
- # go install golang.org/x/tools/cmd/cover ...
- # Found MariaDB installation in ...
- # creating git pre-commit hooks
- #
- # source dev.env in your shell before building
- ```
-
- ``` sh
- # Remaining commands to build Vitess
- source ./dev.env
- make build
- ```
-
-### Run Tests
-
-**Note:** If you are using etcd, set the following environment variable:
-
-``` sh
-export VT_TEST_FLAGS='--topo-server-flavor=etcd2'
-```
-
-**Note:** If you are using consul, set the following environment variable:
-
-``` sh
-export VT_TEST_FLAGS='--topo-server-flavor=consul
-```
-
-The default targets when running `make test` contain a full set of
-tests intended to help Vitess developers to verify code changes. Those tests
-simulate a small Vitess cluster by launching many servers on the local
-machine. To do so, they require a lot of resources; a minimum of 8GB RAM
-and SSD is recommended to run the tests.
-
-Some tests require extra packages. For example, on Ubuntu:
-
-``` sh
-$ sudo apt-get install chromium-browser mvn xvfb
-```
-
-If you want only to check that Vitess is working in your environment,
-you can run a lighter set of tests:
-
-``` sh
-make site_test
-```
-
-#### Common Test Issues
-
-Attempts to run the full developer test suite (`make test`)
-on an underpowered machine often results in failure. If you still see
-the same failures when running the lighter set of tests (`make site_test`),
-please let the development team know in the
-[vitess@googlegroups.com](https://groups.google.com/forum/#!forum/vitess)
-discussion forum.
-
-##### Node already exists, port in use, etc.
-
-A failed test can leave orphaned processes. If you use the default
-settings, you can use the following commands to identify and kill
-those processes:
-
-``` sh
-pgrep -f -l '(vtdataroot|VTDATAROOT)' # list Vitess processes
-pkill -f '(vtdataroot|VTDATAROOT)' # kill Vitess processes
-```
-
-##### Too many connections to MySQL, or other timeouts
-
-This error often means your disk is too slow. If you don't have access
-to an SSD, you can try [testing against a
-ramdisk](https://github.com/vitessio/vitess/blob/master/doc/TestingOnARamDisk.md).
-
-##### Connection refused to tablet, MySQL socket not found, etc.
-
-These errors might indicate that the machine ran out of RAM and a server
-crashed when trying to allocate more RAM. Some of the heavier tests
-require up to 8GB RAM.
-
-##### Connection refused in zkctl test
-
-This error might indicate that the machine does not have a Java Runtime
-installed, which is a requirement if you are using ZooKeeper as the lock server.
-
-##### Running out of disk space
-
-Some of the larger tests use up to 4GB of temporary space on disk.
-
-
-## Start a Vitess cluster
-
-After completing the instructions above to [build Vitess](#build-vitess),
-you can use the example scripts in the Github repo to bring up a Vitess
-cluster on your local machine. These scripts use ZooKeeper as the
-lock service. ZooKeeper is included in the Vitess distribution.
-
-1. **Check system settings**
-
- Some Linux distributions ship with default file descriptor limits
- that are too low for database servers. This issue could show up
- as the database crashing with the message `too many open files`.
-
- Check the system-wide `file-max` setting as well as user-specific
- `ulimit` values. We recommend setting them above 100K to be safe.
- The exact [procedure](https://www.cyberciti.biz/faq/linux-increase-the-maximum-number-of-open-files/)
- may vary depending on your Linux distribution.
-
-1. **Configure environment variables**
-
- If you are still in the same terminal window that
- you used to run the build commands, you can skip to the next
- step since the environment variables will already be set.
-
- If you're adapting this example to your own deployment, the only environment
- variables required before running the scripts are `VTROOT` and `VTDATAROOT`.
-
- Set `VTROOT` to the parent of the Vitess source tree. For example, if you
- ran `make build` while in `$HOME/vt/src/vitess.io/vitess`,
- then you should set:
-
- ``` sh
- export VTROOT=$HOME/vt
- ```
-
- Set `VTDATAROOT` to the directory where you want data files and logs to
- be stored. For example:
-
- ``` sh
- export VTDATAROOT=$HOME/vtdataroot
- ```
-
-1. **Start ZooKeeper or Etcd**
-
- Servers in a Vitess cluster find each other by looking for
- dynamic configuration data stored in a distributed lock
- service. The following script creates a small ZooKeeper cluster:
-
- ``` sh
- $ cd $VTROOT/src/vitess.io/vitess/examples/local
- vitess/examples/local$ ./zk-up.sh
- ### example output:
- # Starting zk servers...
- # Waiting for zk servers to be ready...
- ```
-
- After the ZooKeeper cluster is running, we only need to tell each
- Vitess process how to connect to ZooKeeper. Then, each process can
- find all of the other Vitess processes by coordinating via ZooKeeper.
-
- Each of our scripts automatically uses the `TOPOLOGY_FLAGS` environment
- variable to point to the global ZooKeeper instance. The global instance in
- turn is configured to point to the local instance. In our sample scripts,
- they are both hosted in the same ZooKeeper service.
-
- If you want to use Etcd as a distributed lock service, The following script
- creates a Etcd instance:
-
- ``` sh
- $ cd $VTROOT/src/vitess.io/vitess/examples/local
- vitess/examples/local$ source ./topo-etcd2.sh
- vitess/examples/local$ ./etcd-up.sh
- ### example output:
- # enter etcd2 env
- # etcdmain: etcd Version: 3.X.X
- # ...
- # etcd start done...
- ```
-
-1. **Start vtctld**
-
- The *vtctld* server provides a web interface that
- displays all of the coordination information stored in ZooKeeper.
-
- ``` sh
- vitess/examples/local$ ./vtctld-up.sh
- # Starting vtctld
- # Access vtctld web UI at http://localhost:15000
- # Send commands with: vtctlclient -server localhost:15999 ...
- ```
-
- Open `http://localhost:15000` to verify that
- *vtctld* is running. There won't be any information
- there yet, but the menu should come up, which indicates that
- *vtctld* is running.
-
- The *vtctld* server also accepts commands from the `vtctlclient` tool,
- which is used to administer the cluster. Note that the port for RPCs
- (in this case `15999`) is different from the web UI port (`15000`).
- These ports can be configured with command-line flags, as demonstrated
- in `vtctld-up.sh`.
-
- For convenience, we'll use the `lvtctl.sh` script in example commands,
- to avoid having to type the *vtctld* address every time.
-
- ``` sh
- # List available commands
- vitess/examples/local$ ./lvtctl.sh help
- ```
-
-1. **Start vttablets**
-
- The `vttablet-up.sh` script brings up three vttablets, and assigns them to
- a [keyspace]({% link overview/concepts.md %}#keyspace) and [shard]({% link overview/concepts.md %}#shard)
- according to the variables set at the top of the script file.
-
- ``` sh
- vitess/examples/local$ ./vttablet-up.sh
- # Output from vttablet-up.sh is below
- # Starting MySQL for tablet test-0000000100...
- # Starting vttablet for test-0000000100...
- # Access tablet test-0000000100 at http://localhost:15100/debug/status
- # Starting MySQL for tablet test-0000000101...
- # Starting vttablet for test-0000000101...
- # Access tablet test-0000000101 at http://localhost:15101/debug/status
- # Starting MySQL for tablet test-0000000102...
- # Starting vttablet for test-0000000102...
- # Access tablet test-0000000102 at http://localhost:15102/debug/status
- ```
-
- After this command completes, refresh the *vtctld* web UI, and you should
- see a keyspace named `test_keyspace` with a single shard named `0`.
- This is what an unsharded keyspace looks like.
-
- If you click on the shard box, you'll see a list of [tablets]({% link overview/concepts.md %}#tablet)
- in that shard. Note that it's normal for the tablets to be unhealthy at this point, since
- you haven't initialized them yet.
-
- You can also click the **STATUS** link on each tablet to be taken to its
- status page, showing more details on its operation. Every Vitess server has
- a status page served at `/debug/status` on its web port.
-
-1. **Initialize MySQL databases**
-
- Next, designate one of the tablets to be the initial master.
- Vitess will automatically connect the other slaves' mysqld instances so
- that they start replicating from the master's mysqld.
- This is also when the default database is created. Since our keyspace is
- named `test_keyspace`, the MySQL database will be named `vt_test_keyspace`.
-
- ``` sh
- vitess/examples/local$ ./lvtctl.sh InitShardMaster -force test_keyspace/0 test-100
- ### example output:
- # master-elect tablet test-0000000100 is not the shard master, proceeding anyway as -force was used
- # master-elect tablet test-0000000100 is not a master in the shard, proceeding anyway as -force was used
- ```
-
- **Note:** Since this is the first time the shard has been started,
- the tablets are not already doing any replication, and there is no
- existing master. The `InitShardMaster` command above uses the `-force` flag
- to bypass the usual sanity checks that would apply if this wasn't a
- brand new shard.
-
- After running this command, go back to the **Shard Status** page
- in the *vtctld* web interface. When you refresh the
- page, you should see that one *vttablet* is the master,
- two are replicas and two are rdonly.
-
- You can also see this on the command line:
-
- ``` sh
- vitess/examples/local$ ./lvtctl.sh ListAllTablets test
- ### example output:
- # test-0000000100 test_keyspace 0 master localhost:15100 localhost:17100 []
- # test-0000000101 test_keyspace 0 replica localhost:15101 localhost:17101 []
- # test-0000000102 test_keyspace 0 replica localhost:15102 localhost:17102 []
- # test-0000000103 test_keyspace 0 rdonly localhost:15103 localhost:17103 []
- # test-0000000104 test_keyspace 0 rdonly localhost:15104 localhost:17104 []
- ```
-
-1. **Create a table**
-
- The `vtctlclient` tool can be used to apply the database schema across all
- tablets in a keyspace. The following command creates the table defined in
- the `create_test_table.sql` file:
-
- ``` sh
- # Make sure to run this from the examples/local dir, so it finds the file.
- vitess/examples/local$ ./lvtctl.sh ApplySchema -sql "$(cat create_test_table.sql)" test_keyspace
- ```
-
- The SQL to create the table is shown below:
-
- ``` sql
- CREATE TABLE messages (
- page BIGINT(20) UNSIGNED,
- time_created_ns BIGINT(20) UNSIGNED,
- message VARCHAR(10000),
- PRIMARY KEY (page, time_created_ns)
- ) ENGINE=InnoDB
- ```
-
-1. **Take a backup**
-
- Now that the initial schema is applied, it's a good time to take the first
- [backup]({% link user-guide/backup-and-restore.md %}). This backup
- will be used to automatically restore any additional replicas that you run,
- before they connect themselves to the master and catch up on replication.
- If an existing tablet goes down and comes back up without its data, it will
- also automatically restore from the latest backup and then resume replication.
-
- ``` sh
- vitess/examples/local$ ./lvtctl.sh Backup test-0000000102
- ```
-
- After the backup completes, you can list available backups for the shard:
-
- ``` sh
- vitess/examples/local$ ./lvtctl.sh ListBackups test_keyspace/0
- ### example output:
- # 2016-05-06.072724.test-0000000102
- ```
-
- **Note:** In this single-server example setup, backups are stored at
- `$VTDATAROOT/backups`. In a multi-server deployment, you would usually mount
- an NFS directory there. You can also change the location by setting the
- `-file_backup_storage_root` flag on *vtctld* and *vttablet*, as demonstrated
- in `vtctld-up.sh` and `vttablet-up.sh`.
-
-1. **Initialize Vitess Routing Schema**
-
- In the examples, we are just using a single database with no specific
- configuration. So we just need to make that (empty) configuration visible
- for serving. This is done by running the following command:
-
- ``` sh
- vitess/examples/local$ ./lvtctl.sh RebuildVSchemaGraph
- ```
-
- (As it works, this command will not display any output.)
-
-1. **Start vtgate**
-
- Vitess uses *vtgate* to route each client query to
- the correct *vttablet*. This local example runs a
- single *vtgate* instance, though a real deployment
- would likely run multiple *vtgate* instances to share
- the load.
-
- ``` sh
- vitess/examples/local$ ./vtgate-up.sh
- ```
-
-### Run a Client Application
-
-The `client.py` file is a simple sample application
-that connects to *vtgate* and executes some queries.
-To run it, you need to either:
-
-* Add the Vitess Python packages to your `PYTHONPATH`.
-
- or
-
-* Use the `client.sh` wrapper script, which temporarily
- sets up the environment and then runs `client.py`.
-
- ``` sh
- vitess/examples/local$ ./client.sh
- ### example output:
- # Inserting into master...
- # Reading from master...
- # (5L, 1462510331910124032L, 'V is for speed')
- # (15L, 1462519383758071808L, 'V is for speed')
- # (42L, 1462510369213753088L, 'V is for speed')
- # ...
- ```
-
-There are also sample clients in the same directory for Java, PHP, and Go.
-See the comments at the top of each sample file for usage instructions.
-
-### Try Vitess resharding
-
-Now that you have a full Vitess stack running, you may want to go on to the
-[Horizontal Sharding workflow guide]({% link user-guide/horizontal-sharding-workflow.md %})
-or [Horizontal Sharding codelab]({% link user-guide/horizontal-sharding.md %})
-(if you prefer to run each step manually through commands) to try out
-[dynamic resharding]({% link user-guide/sharding.md %}#resharding).
-
-If so, you can skip the tear-down since the sharding guide picks up right here.
-If not, continue to the clean-up steps below.
-
-### Tear down the cluster
-
-Each `-up.sh` script has a corresponding `-down.sh` script to stop the servers.
-
-``` sh
-vitess/examples/local$ ./vtgate-down.sh
-vitess/examples/local$ ./vttablet-down.sh
-vitess/examples/local$ ./vtctld-down.sh
-vitess/examples/local$ ./zk-down.sh # If you use Etcd, run ./etcd-down.sh
-```
-
-Note that the `-down.sh` scripts will leave behind any data files created.
-If you're done with this example data, you can clear out the contents of `VTDATAROOT`:
-
-``` sh
-$ cd $VTDATAROOT
-/path/to/vtdataroot$ rm -rf *
-```
-
-## Troubleshooting
-
-If anything goes wrong, check the logs in your `$VTDATAROOT/tmp` directory
-for error messages. There are also some tablet-specific logs, as well as
-MySQL logs in the various `$VTDATAROOT/vt_*` directories.
-
-If you need help diagnosing a problem, send a message to our
-[mailing list](https://groups.google.com/forum/#!forum/vitess).
-In addition to any errors you see at the command-line, it would also help to
-upload an archive of your `VTDATAROOT` directory to a file sharing service
-and provide a link to it.
-
diff --git a/doc/GettingStartedKubernetes.md b/doc/GettingStartedKubernetes.md
deleted file mode 100644
index d38e7946283..00000000000
--- a/doc/GettingStartedKubernetes.md
+++ /dev/null
@@ -1,747 +0,0 @@
-This page explains how to run Vitess on [Kubernetes](https://kubernetes.io).
-It also gives the steps to start a Kubernetes cluster with
-[Google Container Engine](https://cloud.google.com/container-engine/).
-
-If you already have Kubernetes v1.0+ running in one of the other
-[supported platforms](https://kubernetes.io/docs/setup/pick-right-solution/),
-you can skip the `gcloud` steps.
-The `kubectl` steps will apply to any Kubernetes cluster.
-
-## Prerequisites
-
-To complete the exercise in this guide, you must
-[install etcd-operator](https://github.com/coreos/etcd-operator/blob/master/doc/user/install_guide.md)
-in the same namespace in which you plan to run Vitess.
-
-You also must locally install Go 1.11+,
-the Vitess' `vtctlclient` tool, and `kubectl`.
-The following sections explain how to set these up in your environment.
-
-### Install Go 1.11+
-
-You need to install [Go 1.11+](https://golang.org/doc/install) to build the
-`vtctlclient` tool, which issues commands to Vitess.
-
-After installing Go, make sure your `GOPATH` environment
-variable is set to the root of your workspace. The most common setting
-is `GOPATH=$HOME/go`, and the value should identify a
-directory to which your non-root user has write access.
-
-In addition, make sure that `$GOPATH/bin` is included in
-your `$PATH`. More information about setting up a Go
-workspace can be found at
-[How to Write Go Code](https://golang.org/doc/code.html#Organization).
-
-### Build and install vtctlclient
-
-The `vtctlclient` tool issues commands to Vitess.
-
-``` sh
-$ go get vitess.io/vitess/go/cmd/vtctlclient
-```
-
-This command downloads and builds the Vitess source code at:
-
-``` sh
-$GOPATH/src/vitess.io/vitess/
-```
-
-It also copies the built `vtctlclient` binary into `$GOPATH/bin`.
-
-### Set up Google Compute Engine, Container Engine, and Cloud tools
-
-**Note:** If you are running Kubernetes elsewhere, skip to
-[Locate kubectl](#locate-kubectl).
-
-To run Vitess on Kubernetes using Google Compute Engine (GCE),
-you must have a GCE account with billing enabled. The instructions
-below explain how to enable billing and how to associate a billing
-account with a project in the Google Developers Console.
-
-1. Log in to the Google Developers Console to [enable billing](https://console.developers.google.com/billing).
- 1. Click the **Billing** pane if you are not there already.
- 1. Click **New billing account**.
- 1. Assign a name to the billing account -- e.g. "Vitess on
- Kubernetes." Then click **Continue**. You can sign up
- for the [free trial](https://cloud.google.com/free-trial/)
- to avoid any charges.
-
-1. Create a project in the Google Developers Console that uses
- your billing account:
- 1. At the top of the Google Developers Console, click the **Projects** dropdown.
- 1. Click the Create a Project... link.
- 1. Assign a name to your project. Then click the **Create** button.
- Your project should be created and associated with your
- billing account. (If you have multiple billing accounts,
- confirm that the project is associated with the correct account.)
- 1. After creating your project, click **API Manager** in the left menu.
- 1. Find **Google Compute Engine** and **Google Container Engine API**.
- (Both should be listed under "Google Cloud APIs".)
- For each, click on it, then click the **"Enable API"** button.
-
-1. Follow the [Google Cloud SDK quickstart instructions](https://cloud.google.com/sdk/#Quick_Start)
- to set up and test the Google Cloud SDK. You will also set your default project
- ID while completing the quickstart.
-
- **Note:** If you skip the quickstart guide because you've previously set up
- the Google Cloud SDK, just make sure to set a default project ID by running
- the following command. Replace `PROJECT` with the project ID assigned to
- your [Google Developers Console](https://console.developers.google.com/)
- project. You can [find the ID](https://cloud.google.com/compute/docs/projects#projectids)
- by navigating to the **Overview** page for the project in the Console.
-
- ``` sh
- $ gcloud config set project PROJECT
- ```
-
-1. Install or update the `kubectl` tool:
-
- ``` sh
- $ gcloud components update kubectl
- ```
-
-### Locate kubectl
-
-Check if `kubectl` is on your `PATH`:
-
-``` sh
-$ which kubectl
-### example output:
-# ~/google-cloud-sdk/bin/kubectl
-```
-
-If `kubectl` isn't on your `PATH`, you can tell our scripts where
-to find it by setting the `KUBECTL` environment variable:
-
-``` sh
-$ export KUBECTL=/example/path/to/google-cloud-sdk/bin/kubectl
-```
-
-## Start a Container Engine cluster
-
-**Note:** If you are running Kubernetes elsewhere, skip to
-[Start a Vitess cluster](#start-a-vitess-cluster).
-
-1. Set the [zone](https://cloud.google.com/compute/docs/zones#overview)
- that your installation will use:
-
- ``` sh
- $ gcloud config set compute/zone us-central1-b
- ```
-
-1. Create a Container Engine cluster:
-
- ``` sh
- $ gcloud container clusters create example --machine-type n1-standard-4 --num-nodes 5 --scopes storage-rw
- ### example output:
- # Creating cluster example...done.
- # Created [https://container.googleapis.com/v1/projects/vitess/zones/us-central1-b/clusters/example].
- # kubeconfig entry generated for example.
- ```
-
- **Note:** The `--scopes storage-rw` argument is necessary to allow
- [built-in backup/restore]({% link user-guide/backup-and-restore.md %})
- to access [Google Cloud Storage](https://cloud.google.com/storage/).
-
-1. Create a Cloud Storage bucket:
-
- To use the Cloud Storage plugin for built-in backups, first create a
- [bucket](https://cloud.google.com/storage/docs/concepts-techniques#concepts)
- for Vitess backup data. See the
- [bucket naming guidelines](https://cloud.google.com/storage/docs/bucket-naming)
- if you're new to Cloud Storage.
-
- ``` sh
- $ gsutil mb gs://my-backup-bucket
- ```
-
-## Start a Vitess cluster
-
-1. **Navigate to your local Vitess source code**
-
- This directory would have been created when you installed
- `vtctlclient`:
-
- ``` sh
- $ cd $GOPATH/src/vitess.io/vitess/examples/kubernetes
- ```
-
-1. **Configure site-local settings**
-
- Run the `configure.sh` script to generate a `config.sh` file, which will be
- used to customize your cluster settings.
-
- Currently, we have out-of-the-box support for storing
- [backups]({% link user-guide/backup-and-restore.md %}) in
- [Google Cloud Storage](https://cloud.google.com/storage/). If you're using
- GCS, fill in the fields requested by the configure script, including the
- name of the bucket you created above.
-
- ``` sh
- vitess/examples/kubernetes$ ./configure.sh
- ### example output:
- # Backup Storage (file, gcs) [gcs]:
- # Google Developers Console Project [my-project]:
- # Google Cloud Storage bucket for Vitess backups: my-backup-bucket
- # Saving config.sh...
- ```
-
- For other platforms, you'll need to choose the `file` backup storage plugin,
- and mount a read-write network volume into the `vttablet` and `vtctld` pods.
- For example, you can mount any storage service accessible through NFS into a
- [Kubernetes volume](https://kubernetes.io/docs/concepts/storage/volumes#nfs).
- Then provide the mount path to the configure script here.
-
- Direct support for other cloud blob stores like Amazon S3 can be added by
- implementing the Vitess [BackupStorage plugin interface](https://github.com/vitessio/vitess/blob/master/go/vt/mysqlctl/backupstorage/interface.go).
- Let us know on the [discussion forum](https://groups.google.com/forum/#!forum/vitess)
- if you have any specific plugin requests.
-
-1. **Start an etcd cluster**
-
- The Vitess [topology service]({% link overview/concepts.md %}#topology-service)
- stores coordination data for all the servers in a Vitess cluster.
- It can store this data in one of several consistent storage systems.
- In this example, we'll use [etcd](https://github.com/coreos/etcd).
- Note that we need our own etcd clusters, separate from the one used by
- Kubernetes itself. We will use etcd-operator to manage these clusters.
-
- If you haven't done so already, make sure you
- [install etcd-operator](https://github.com/coreos/etcd-operator/blob/master/doc/user/install_guide.md)
- in the same namespace in which you plan to run Vitess
- before continuing.
-
- ``` sh
- vitess/examples/kubernetes$ ./etcd-up.sh
- ### example output:
- # Creating etcd service for 'global' cell...
- # etcdcluster "etcd-global" created
- # Creating etcd service for 'global' cell...
- # etcdcluster "etcd-test" created
- # ...
- ```
-
- This command creates two clusters. One is for the
- [global cell]({% link user-guide/topology-service.md %}#global-vs-local),
- and the other is for a
- [local cell]({% link overview/concepts.md %}#cell-data-center)
- called *test*. You can check the status of the
- [pods](https://kubernetes.io/docs/concepts/workloads/pods/)
- in the cluster by running:
-
- ``` sh
- $ kubectl get pods
- ### example output:
- # NAME READY STATUS RESTARTS AGE
- # etcd-global-0000 1/1 Running 0 1m
- # etcd-global-0001 1/1 Running 0 1m
- # etcd-global-0002 1/1 Running 0 1m
- # etcd-operator-857677187-rvgf5 1/1 Running 0 28m
- # etcd-test-0000 1/1 Running 0 1m
- # etcd-test-0001 1/1 Running 0 1m
- # etcd-test-0002 1/1 Running 0 1m
- ```
-
- It may take a while for each Kubernetes node to download the
- Docker images the first time it needs them. While the images
- are downloading, the pod status will be Pending.
-
- **Note:** In this example, each script that has a name ending in
- `-up.sh` also has a corresponding `-down.sh`
- script, which can be used to stop certain components of the
- Vitess cluster without bringing down the whole cluster. For
- example, to tear down the `etcd` deployment, run:
-
- ``` sh
- vitess/examples/kubernetes$ ./etcd-down.sh
- ```
-
-1. **Start vtctld**
-
- The `vtctld` server provides a web interface to inspect the state of the
- Vitess cluster. It also accepts RPC commands from `vtctlclient` to modify
- the cluster.
-
- ``` sh
- vitess/examples/kubernetes$ ./vtctld-up.sh
- ### example output:
- # Creating vtctld ClusterIP service...
- # service "vtctld" created
- # Creating vtctld replicationcontroller...
- # replicationcontroller "vtctld" create createdd
- ```
-
-1. **Access vtctld web UI**
-
- To access vtctld from outside Kubernetes, use [kubectl proxy](https://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/)
- to create an authenticated tunnel on your workstation:
-
- **Note:** The proxy command runs in the foreground,
- so you may want to run it in a separate terminal.
-
- ``` sh
- $ kubectl proxy --port=8001
- ### example output:
- # Starting to serve on localhost:8001
- ```
-
- You can then load the vtctld web UI on `localhost`:
-
- http://localhost:8001/api/v1/namespaces/default/services/vtctld:web/proxy
-
- You can also use this proxy to access the [Kubernetes Dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/),
- where you can monitor nodes, pods, and services:
-
- http://localhost:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/.
-
-1. **Use vtctlclient to send commands to vtctld**
-
- You can now run `vtctlclient` locally to issue commands
- to the `vtctld` service on your Kubernetes cluster.
-
- To enable RPC access into the Kubernetes cluster, we'll again use
- `kubectl` to set up an authenticated tunnel. Unlike the HTTP proxy
- we used for the web UI, this time we need raw [port forwarding](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/)
- for vtctld's [gRPC](https://grpc.io) port.
-
- Since the tunnel needs to target a particular vtctld pod name,
- we've provided the `kvtctl.sh` script, which uses `kubectl` to
- discover the pod name and set up the tunnel before running `vtctlclient`.
-
- Now, running `kvtctl.sh help` will test your connection to
- `vtctld` and also list the `vtctlclient`
- commands that you can use to administer the Vitess cluster.
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh help
- ### example output:
- # Available commands:
- #
- # Tablets:
- # InitTablet ...
- # ...
- ```
-
- You can also use the `help` command to get more details about each command:
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh help ListAllTablets
- ```
-
- See the [vtctl reference]({% link reference/vtctl.md %}) for a
- web-formatted version of the `vtctl help` output.
-
-1. **Setup the cell in the topology**
-
- The global etcd cluster is configured from command-line parameters,
- specified in the Kubernetes configuration files. The per-cell etcd cluster
- however needs to be configured, so it is reachable by Vitess. The following
- command sets it up:
-
- ``` sh
- ./kvtctl.sh AddCellInfo --root /test -server_address http://etcd-test-client:2379 test
- ```
-
-
-1. **Start vttablets**
-
- A Vitess [tablet]({% link overview/concepts.md %}#tablet) is the
- unit of scaling for the database. A tablet consists of the
- `vttablet` and `mysqld` processes, running on the same
- host. We enforce this coupling in Kubernetes by putting the respective
- containers for vttablet and mysqld inside a single
- [pod](https://kubernetes.io/docs/concepts/workloads/pods/).
-
- Run the following script to launch the vttablet pods, which also include
- mysqld:
-
- ``` sh
- vitess/examples/kubernetes$ ./vttablet-up.sh
- ### example output:
- # Creating test_keyspace.shard-0 pods in cell test...
- # Creating pod for tablet test-0000000100...
- # pod "vttablet-100" created
- # Creating pod for tablet test-0000000101...
- # pod "vttablet-101" created
- # Creating pod for tablet test-0000000102...
- # pod "vttablet-102" created
- # Creating pod for tablet test-0000000103...
- # pod "vttablet-103" created
- # Creating pod for tablet test-0000000104...
- # pod "vttablet-104" created
- ```
-
- In the vtctld web UI, you should soon see a
- [keyspace]({% link overview/concepts.md %}#keyspace) named `test_keyspace`
- with a single [shard]({% link overview/concepts.md %}#shard) named `0`.
- Click on the shard name to see the list of tablets. When all 5 tablets
- show up on the shard status page, you're ready to continue. Note that it's
- normal for the tablets to be unhealthy at this point, since you haven't
- initialized the databases on them yet.
-
- It can take some time for the tablets to come up for the first time if a pod
- was scheduled on a node that hasn't downloaded the [Vitess Docker image](https://hub.docker.com/u/vitess/)
- yet. You can also check the status of the
- tablets from the command line using `kvtctl.sh`:
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh ListAllTablets test
- ### example output:
- # test-0000000100 test_keyspace 0 spare 10.64.1.6:15002 10.64.1.6:3306 []
- # test-0000000101 test_keyspace 0 spare 10.64.2.5:15002 10.64.2.5:3306 []
- # test-0000000102 test_keyspace 0 spare 10.64.0.7:15002 10.64.0.7:3306 []
- # test-0000000103 test_keyspace 0 spare 10.64.1.7:15002 10.64.1.7:3306 []
- # test-0000000104 test_keyspace 0 spare 10.64.2.6:15002 10.64.2.6:3306 []
- ```
-
-1. **Initialize MySQL databases**
-
- Once all the tablets show up, you're ready to initialize the underlying
- MySQL databases.
-
- **Note:** Many `vtctlclient` commands produce no output on success.
-
- First, designate one of the tablets to be the initial master. Vitess will
- automatically connect the other slaves' mysqld instances so that they start
- replicating from the master's mysqld. This is also when the default database
- is created. Since our keyspace is named `test_keyspace`, the MySQL database
- will be named `vt_test_keyspace`.
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh InitShardMaster -force test_keyspace/0 test-0000000100
- ### example output:
- # master-elect tablet test-0000000100 is not the shard master, proceeding anyway as -force was used
- # master-elect tablet test-0000000100 is not a master in the shard, proceeding anyway as -force was used
- ```
-
- **Note:** Since this is the first time the shard has been started, the
- tablets are not already doing any replication, and there is no existing
- master. The `InitShardMaster` command above uses the `-force` flag to bypass
- the usual sanity checks that would apply if this wasn't a brand new shard.
-
- After the tablets finish updating, you should see one **master**, and
- several **replica** and **rdonly** tablets:
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh ListAllTablets test
- ### example output:
- # test-0000000100 test_keyspace 0 master 10.64.1.6:15002 10.64.1.6:3306 []
- # test-0000000101 test_keyspace 0 replica 10.64.2.5:15002 10.64.2.5:3306 []
- # test-0000000102 test_keyspace 0 replica 10.64.0.7:15002 10.64.0.7:3306 []
- # test-0000000103 test_keyspace 0 rdonly 10.64.1.7:15002 10.64.1.7:3306 []
- # test-0000000104 test_keyspace 0 rdonly 10.64.2.6:15002 10.64.2.6:3306 []
- ```
-
- The **replica** tablets are used for serving live web traffic, while the
- **rdonly** tablets are used for offline processing, such as batch jobs and backups.
- The amount of each [tablet type]({% link overview/concepts.md %}#tablet)
- that you launch can be configured in the `vttablet-up.sh` script.
-
-1. **Create a table**
-
- The `vtctlclient` tool can be used to apply the database schema
- across all tablets in a keyspace. The following command creates
- the table defined in the `create_test_table.sql` file:
-
- ``` sh
- # Make sure to run this from the examples/kubernetes dir, so it finds the file.
- vitess/examples/kubernetes$ ./kvtctl.sh ApplySchema -sql "$(cat create_test_table.sql)" test_keyspace
- ```
-
- The SQL to create the table is shown below:
-
- ``` sql
- CREATE TABLE messages (
- page BIGINT(20) UNSIGNED,
- time_created_ns BIGINT(20) UNSIGNED,
- message VARCHAR(10000),
- PRIMARY KEY (page, time_created_ns)
- ) ENGINE=InnoDB
- ```
-
- You can run this command to confirm that the schema was created
- properly on a given tablet, where `test-0000000100`
- is a tablet alias as shown by the `ListAllTablets` command:
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh GetSchema test-0000000100
- ### example output:
- # {
- # "DatabaseSchema": "CREATE DATABASE `{{.DatabaseName}}` /*!40100 DEFAULT CHARACTER SET utf8 */",
- # "TableDefinitions": [
- # {
- # "Name": "messages",
- # "Schema": "CREATE TABLE `messages` (\n `page` bigint(20) unsigned NOT NULL DEFAULT '0',\n `time_created_ns` bigint(20) unsigned NOT NULL DEFAULT '0',\n `message` varchar(10000) DEFAULT NULL,\n PRIMARY KEY (`page`,`time_created_ns`)\n) ENGINE=InnoDB DEFAULT CHARSET=utf8",
- # "Columns": [
- # "page",
- # "time_created_ns",
- # "message"
- # ],
- # ...
- ```
-
-1. **Take a backup**
-
- Now that the initial schema is applied, it's a good time to take the first
- [backup]({% link user-guide/backup-and-restore.md %}). This backup
- will be used to automatically restore any additional replicas that you run,
- before they connect themselves to the master and catch up on replication.
- If an existing tablet goes down and comes back up without its data, it will
- also automatically restore from the latest backup and then resume replication.
-
- Select one of the **rdonly** tablets and tell it to take a backup. We use a
- **rdonly** tablet instead of a **replica** because the tablet will pause
- replication and stop serving during data copy to create a consistent snapshot.
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh Backup test-0000000104
- ```
-
- After the backup completes, you can list available backups for the shard:
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh ListBackups test_keyspace/0
- ### example output:
- # 2015-10-21.042940.test-0000000104
- ```
-
-1. **Initialize Vitess Routing Schema**
-
- In the examples, we are just using a single database with no specific
- configuration. So we just need to make that (empty) configuration visible
- for serving. This is done by running the following command:
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh RebuildVSchemaGraph
- ```
-
- (As it works, this command will not display any output.)
-
-1. **Start vtgate**
-
- Vitess uses [vtgate]({% link overview/index.md %}#vtgate) to route each client
- query to the correct `vttablet`. In Kubernetes, a `vtgate` service
- distributes connections to a pool of `vtgate` pods. The pods are curated by
- a [replication controller](https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller/).
-
- ``` sh
- vitess/examples/kubernetes$ ./vtgate-up.sh
- ### example output:
- # Creating vtgate service in cell test...
- # service "vtgate-test" created
- # Creating vtgate replicationcontroller in cell test...
- # replicationcontroller "vtgate-test" created
- ```
-
-## Test your cluster with a client app
-
-The GuestBook app in the example is ported from the
-[Kubernetes GuestBook example](https://github.com/kubernetes/kubernetes/tree/master/examples/guestbook-go).
-The server-side code has been rewritten in Python to use Vitess as the storage
-engine. The client-side code (HTML/JavaScript) has been modified to support
-multiple Guestbook pages, which will be useful to demonstrate Vitess sharding in
-a later guide.
-
-``` sh
-vitess/examples/kubernetes$ ./guestbook-up.sh
-### example output:
-# Creating guestbook service...
-# services "guestbook" created
-# Creating guestbook replicationcontroller...
-# replicationcontroller "guestbook" created
-```
-
-As with the `vtctld` service, by default the GuestBook app is not accessible
-from outside Kubernetes. In this case, since this is a user-facing frontend,
-we set `type: LoadBalancer` in the GuestBook service definition,
-which tells Kubernetes to create a public
-[load balancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/)
-using the API for whatever platform your Kubernetes cluster is in.
-
-You also need to [allow access through your platform's firewall](https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/).
-
-``` sh
-# For example, to open port 80 in the GCE firewall:
-$ gcloud compute firewall-rules create guestbook --allow tcp:80
-```
-
-**Note:** For simplicity, the firewall rule above opens the port on **all**
-GCE instances in your project. In a production system, you would likely
-limit it to specific instances.
-
-Then, get the external IP of the load balancer for the GuestBook service:
-
-``` sh
-$ kubectl get service guestbook
-### example output:
-# NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
-# guestbook 10.67.242.247 3.4.5.6 80/TCP 1m
-```
-
-If the `EXTERNAL-IP` is still empty, give it a few minutes to create
-the external load balancer and check again.
-
-Once the pods are running, the GuestBook app should be accessible
-from the load balancer's external IP. In the example above, it would be at
-`http://3.4.5.6`.
-
-You can see Vitess' replication capabilities by opening the app in
-multiple browser windows, with the same Guestbook page number.
-Each new entry is committed to the master database.
-In the meantime, JavaScript on the page continuously polls
-the app server to retrieve a list of GuestBook entries. The app serves
-read-only requests by querying Vitess in 'replica' mode, confirming
-that replication is working.
-
-You can also inspect the data stored by the app:
-
-``` sh
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-0000000100 "SELECT * FROM messages"
-### example output:
-# +------+---------------------+---------+
-# | page | time_created_ns | message |
-# +------+---------------------+---------+
-# | 42 | 1460771336286560000 | Hello |
-# +------+---------------------+---------+
-```
-
-The [GuestBook source code](https://github.com/vitessio/vitess/tree/master/examples/kubernetes/guestbook)
-provides more detail about how the app server interacts with Vitess.
-
-## Try Vitess resharding
-
-Now that you have a full Vitess stack running, you may want to go on to the
-[Sharding in Kubernetes workflow guide]({% link user-guide/sharding-kubernetes.md %})
-or [Sharding in Kubernetes codelab]({% link user-guide/sharding-kubernetes.md %})
-(if you prefer to run each step manually through commands) to try out
-[dynamic resharding]({% link user-guide/sharding.md %}#resharding).
-
-If so, you can skip the tear-down since the sharding guide picks up right here.
-If not, continue to the clean-up steps below.
-
-## Tear down and clean up
-
-Before stopping the Container Engine cluster, you should tear down the Vitess
-services. Kubernetes will then take care of cleaning up any entities it created
-for those services, like external load balancers.
-
-``` sh
-vitess/examples/kubernetes$ ./guestbook-down.sh
-vitess/examples/kubernetes$ ./vtgate-down.sh
-vitess/examples/kubernetes$ ./vttablet-down.sh
-vitess/examples/kubernetes$ ./vtctld-down.sh
-vitess/examples/kubernetes$ ./etcd-down.sh
-```
-
-Then tear down the Container Engine cluster itself, which will stop the virtual
-machines running on Compute Engine:
-
-``` sh
-$ gcloud container clusters delete example
-```
-
-It's also a good idea to remove any firewall rules you created, unless you plan
-to use them again soon:
-
-``` sh
-$ gcloud compute firewall-rules delete guestbook
-```
-
-## Troubleshooting
-
-### Server logs
-
-If a pod enters the `Running` state, but the server
-doesn't respond as expected, use the `kubectl logs`
-command to check the pod output:
-
-``` sh
-# show logs for container 'vttablet' within pod 'vttablet-100'
-$ kubectl logs vttablet-100 vttablet
-
-# show logs for container 'mysql' within pod 'vttablet-100'
-# Note that this is NOT MySQL error log.
-$ kubectl logs vttablet-100 mysql
-```
-
-Post the logs somewhere and send a link to the [Vitess
-mailing list](https://groups.google.com/forum/#!forum/vitess)
-to get more help.
-
-### Shell access
-
-If you want to poke around inside a container, you can use `kubectl exec` to run
-a shell.
-
-For example, to launch a shell inside the `vttablet` container of the
-`vttablet-100` pod:
-
-``` sh
-$ kubectl exec vttablet-100 -c vttablet -t -i -- bash -il
-root@vttablet-100:/# ls /vt/vtdataroot/vt_0000000100
-### example output:
-# bin-logs innodb my.cnf relay-logs
-# data memcache.sock764383635 mysql.pid slow-query.log
-# error.log multi-master.info mysql.sock tmp
-```
-
-### Root certificates
-
-If you see in the logs a message like this:
-
-```
-x509: failed to load system roots and no roots provided
-```
-
-It usually means that your Kubernetes nodes are running a host OS
-that puts root certificates in a different place than our configuration
-expects by default (for example, Fedora). See the comments in the
-[etcd controller template](https://github.com/kubernetes/examples/blob/master/staging/storage/vitess/etcd-controller-template.yaml)
-for examples of how to set the right location for your host OS.
-You'll also need to adjust the same certificate path settings in the
-`vtctld` and `vttablet` templates.
-
-### Status pages for vttablets
-
-Each `vttablet` serves a set of HTML status pages on its primary port.
-The `vtctld` interface provides a **STATUS** link for each tablet.
-
-If you access the vtctld web UI through the kubectl proxy as described above,
-it will automatically link to the vttablets through that same proxy,
-giving you access from outside the cluster.
-
-You can also use the proxy to go directly to a tablet. For example,
-to see the status page for the tablet with ID `100`, you could navigate to:
-
-http://localhost:8001/api/v1/proxy/namespaces/default/pods/vttablet-100:15002/debug/status
-
-### Direct connection to mysqld
-
-Since the `mysqld` within the `vttablet` pod is only meant to be accessed
-via vttablet, our default bootstrap settings only allow connections from
-localhost.
-
-If you want to check or manipulate the underlying mysqld, you can issue
-simple queries or commands through `vtctlclient` like this:
-
-``` sh
-# Send a query to tablet 100 in cell 'test'.
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-0000000100 "SELECT VERSION()"
-### example output:
-# +------------+
-# | VERSION() |
-# +------------+
-# | 5.7.13-log |
-# +------------+
-```
-
-If you need a truly direct connection to mysqld, you can [launch a shell](#shell-access)
-inside the mysql container, and then connect with the `mysql`
-command-line client:
-
-``` sh
-$ kubectl exec vttablet-100 -c mysql -t -i -- bash -il
-root@vttablet-100:/# export TERM=ansi
-root@vttablet-100:/# mysql -S /vt/vtdataroot/vt_0000000100/mysql.sock -u vt_dba
-```
-
diff --git a/doc/GitHubWorkflow.md b/doc/GitHubWorkflow.md
deleted file mode 100644
index c81aefb69b0..00000000000
--- a/doc/GitHubWorkflow.md
+++ /dev/null
@@ -1,137 +0,0 @@
-# GitHub Workflow
-
-If you are new to Git and GitHub, we recommend to read this page. Otherwise, you may skip it.
-
-Our GitHub workflow is a so called triangular workflow:
-
-
-
-*Image Source:* https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows
-
-The Vitess code is hosted on GitHub (https://github.com/vitessio/vitess).
-This repository is called *upstream*.
-You develop and commit your changes in a clone of our upstream repository (shown as *local* in the image above).
-Then you push your changes to your forked repository (*origin*) and send us a pull request.
-Eventually, we will merge your pull request back into the *upstream* repository.
-
-## Remotes
-
-Since you should have cloned the repository from your fork, the `origin` remote
-should look like this:
-
-```
-$ git remote -v
-origin git@github.com:/vitess.git (fetch)
-origin git@github.com:/vitess.git (push)
-```
-
-To help you keep your fork in sync with the main repo, add an `upstream` remote:
-
-```
-$ git remote add upstream git@github.com:vitessio/vitess.git
-$ git remote -v
-origin git@github.com:/vitess.git (fetch)
-origin git@github.com:/vitess.git (push)
-upstream git@github.com:vitessio/vitess.git (fetch)
-upstream git@github.com:vitessio/vitess.git (push)
-```
-
-Now to sync your local `master` branch, do this:
-
-```
-$ git checkout master
-(master) $ git pull upstream master
-```
-
-Note: In the example output above we prefixed the prompt with `(master)` to
-stress the fact that the command must be run from the branch `master`.
-
-You can omit the `upstream master` from the `git pull` command when you let your
-`master` branch always track the main `vitessio/vitess` repository. To achieve
-this, run this command once:
-
-```
-(master) $ git branch --set-upstream-to=upstream/master
-```
-
-Now the following command syncs your local `master` branch as well:
-
-```
-(master) $ git pull
-```
-
-## Topic Branches
-
-Before you start working on changes, create a topic branch:
-
-```
-$ git checkout master
-(master) $ git pull
-(master) $ git checkout -b new-feature
-(new-feature) $ # You are now in the new-feature branch.
-```
-
-Try to commit small pieces along the way as you finish them, with an explanation
-of the changes in the commit message.
-Please see the [Code Review page]({% link contributing/code-reviews.md %}) for more guidance.
-
-As you work in a package, you can run just
-the unit tests for that package by running `go test` from within that package.
-
-When you're ready to test the whole system, run the full test suite with `make
-test` from the root of the Git tree.
-If you haven't installed all dependencies for `make test`, you can rely on the Travis CI test results as well.
-These results will be linked on your pull request.
-
-## Committing your work
-
-When running `git commit` use the `-s` option to add a Signed-off-by line.
-This is needed for [the Developer Certificate of Origin](https://github.com/apps/dco).
-
-## Sending Pull Requests
-
-Push your branch to the repository (and set it to track with `-u`):
-
-```
-(new-feature) $ git push -u origin new-feature
-```
-
-You can omit `origin` and `-u new-feature` parameters from the `git push`
-command with the following two Git configuration changes:
-
-```
-$ git config remote.pushdefault origin
-$ git config push.default current
-```
-
-The first setting saves you from typing `origin` every time. And with the second
-setting, Git assumes that the remote branch on the GitHub side will have the
-same name as your local branch.
-
-After this change, you can run `git push` without arguments:
-
-```
-(new-feature) $ git push
-```
-
-Then go to the [repository page](https://github.com/vitessio/vitess) and it
-should prompt you to create a Pull Request from a branch you recently pushed.
-You can also [choose a branch manually](https://github.com/vitessio/vitess/compare).
-
-## Addressing Changes
-
-If you need to make changes in response to the reviewer's comments, just make
-another commit on your branch and then push it again:
-
-```
-$ git checkout new-feature
-(new-feature) $ git commit
-(new-feature) $ git push
-```
-
-That is because a pull request always mirrors all commits from your topic branch which are not in the master branch.
-
-Once your pull request is merged:
-
-* close the GitHub issue (if it wasn't automatically closed)
-* delete your local topic branch (`git branch -d new-feature`)
diff --git a/doc/HorizontalReshardingGuide.md b/doc/HorizontalReshardingGuide.md
deleted file mode 100644
index f38c5563ef4..00000000000
--- a/doc/HorizontalReshardingGuide.md
+++ /dev/null
@@ -1,262 +0,0 @@
-This guide walks you through the process of sharding an existing unsharded
-Vitess [keyspace]({% link overview/concepts.md %}#keyspace).
-
-## Prerequisites
-
-We begin by assuming you've completed the
-[Getting Started]({% link getting-started/local-instance.md %}) guide,
-and have left the cluster running.
-
-## Overview
-
-The sample clients in the `examples/local` folder use the following schema:
-
-``` sql
-CREATE TABLE messages (
- page BIGINT(20) UNSIGNED,
- time_created_ns BIGINT(20) UNSIGNED,
- message VARCHAR(10000),
- PRIMARY KEY (page, time_created_ns)
-) ENGINE=InnoDB
-```
-
-The idea is that each page number represents a separate guestbook in a
-multi-tenant app. Each guestbook page consists of a list of messages.
-
-In this guide, we'll introduce sharding by page number.
-That means pages will be randomly distributed across shards,
-but all records for a given page are always guaranteed to be on the same shard.
-In this way, we can transparently scale the database to support arbitrary growth
-in the number of pages.
-
-## Configure sharding information
-
-The first step is to tell Vitess how we want to partition the data.
-We do this by providing a VSchema definition as follows:
-
-``` json
-{
- "sharded": true,
- "vindexes": {
- "hash": {
- "type": "hash"
- }
- },
- "tables": {
- "messages": {
- "column_vindexes": [
- {
- "column": "page",
- "name": "hash"
- }
- ]
- }
- }
-}
-```
-
-This says that we want to shard the data by a hash of the `page` column.
-In other words, keep each page's messages together, but spread pages around
-the shards randomly.
-
-We can load this VSchema into Vitess like this:
-
-``` sh
-vitess/examples/local$ ./lvtctl.sh ApplyVSchema -vschema "$(cat vschema.json)" test_keyspace
-```
-
-## Bring up tablets for new shards
-
-In the unsharded example, you started tablets for a shard
-named *0* in *test_keyspace*, written as *test_keyspace/0*.
-Now you'll start tablets for two additional shards,
-named *test_keyspace/-80* and *test_keyspace/80-*:
-
-``` sh
-vitess/examples/local$ ./sharded-vttablet-up.sh
-```
-
-Since the sharding key is the page number,
-this will result in half the pages going to each shard,
-since *0x80* is the midpoint of the
-[sharding key range]({% link user-guide/sharding.md %}#key-ranges-and-partitions).
-
-These new shards will run in parallel with the original shard during the
-transition, but actual traffic will be served only by the original shard
-until we tell it to switch over.
-
-Check the *vtctld* web UI, or the output of `lvtctl.sh ListAllTablets test`,
-to see when the tablets are ready. There should be 5 tablets in each shard.
-
-Once the tablets are ready, initialize replication by electing the first master
-for each of the new shards:
-
-``` sh
-vitess/examples/local$ ./lvtctl.sh InitShardMaster -force test_keyspace/-80 test-0000000200
-vitess/examples/local$ ./lvtctl.sh InitShardMaster -force test_keyspace/80- test-0000000300
-```
-
-Now there should be a total of 15 tablets, with one master for each shard:
-
-``` sh
-vitess/examples/local$ ./lvtctl.sh ListAllTablets test
-### example output:
-# test-0000000100 test_keyspace 0 master 10.64.3.4:15002 10.64.3.4:3306 []
-# ...
-# test-0000000200 test_keyspace -80 master 10.64.0.7:15002 10.64.0.7:3306 []
-# ...
-# test-0000000300 test_keyspace 80- master 10.64.0.9:15002 10.64.0.9:3306 []
-# ...
-```
-
-## Copy data from original shard
-
-The new tablets start out empty, so we need to copy everything from the
-original shard to the two new ones, starting with the schema:
-
-``` sh
-vitess/examples/local$ ./lvtctl.sh CopySchemaShard test_keyspace/0 test_keyspace/-80
-vitess/examples/local$ ./lvtctl.sh CopySchemaShard test_keyspace/0 test_keyspace/80-
-```
-
-Next we copy the data. Since the amount of data to copy can be very large,
-we use a special batch process called *vtworker* to stream the data from a
-single source to multiple destinations, routing each row based on its
-*keyspace_id*:
-
-``` sh
-vitess/examples/local$ ./sharded-vtworker.sh SplitClone test_keyspace/0
-### example output:
-# I0416 02:08:59.952805 9 instance.go:115] Starting worker...
-# ...
-# State: done
-# Success:
-# messages: copy done, copied 11 rows
-```
-
-Notice that we've only specified the source shard, *test_keyspace/0*.
-The *SplitClone* process will automatically figure out which shards to use
-as the destinations based on the key range that needs to be covered.
-In this case, shard *0* covers the entire range, so it identifies
-*-80* and *80-* as the destination shards, since they combine to cover the
-same range.
-
-Next, it will pause replication on one *rdonly* (offline processing) tablet
-to serve as a consistent snapshot of the data. The app can continue without
-downtime, since live traffic is served by *replica* and *master* tablets,
-which are unaffected. Other batch jobs will also be unaffected, since they
-will be served only by the remaining, un-paused *rdonly* tablets.
-
-## Check filtered replication
-
-Once the copy from the paused snapshot finishes, *vtworker* turns on
-[filtered replication]({% link user-guide/sharding.md %}#filtered-replication)
-from the source shard to each destination shard. This allows the destination
-shards to catch up on updates that have continued to flow in from the app since
-the time of the snapshot.
-
-When the destination shards are caught up, they will continue to replicate
-new updates. You can see this by looking at the contents of each shard as
-you add new messages to various pages in the Guestbook app. Shard *0* will
-see all the messages, while the new shards will only see messages for pages
-that live on that shard.
-
-``` sh
-# See what's on shard test_keyspace/0:
-vitess/examples/local$ ./lvtctl.sh ExecuteFetchAsDba test-0000000100 "SELECT * FROM messages"
-# See what's on shard test_keyspace/-80:
-vitess/examples/local$ ./lvtctl.sh ExecuteFetchAsDba test-0000000200 "SELECT * FROM messages"
-# See what's on shard test_keyspace/80-:
-vitess/examples/local$ ./lvtctl.sh ExecuteFetchAsDba test-0000000300 "SELECT * FROM messages"
-```
-
-You can run the client script again to add some messages on various pages
-and see how they get routed.
-
-## Check copied data integrity
-
-The *vtworker* batch process has another mode that will compare the source
-and destination to ensure all the data is present and correct.
-The following commands will run a diff for each destination shard:
-
-``` sh
-vitess/examples/local$ ./sharded-vtworker.sh SplitDiff test_keyspace/-80
-vitess/examples/local$ ./sharded-vtworker.sh SplitDiff test_keyspace/80-
-```
-
-If any discrepancies are found, they will be printed.
-If everything is good, you should see something like this:
-
-```
-I0416 02:10:56.927313 10 split_diff.go:496] Table messages checks out (4 rows processed, 1072961 qps)
-```
-
-## Switch over to new shards
-
-Now we're ready to switch over to serving from the new shards.
-The [MigrateServedTypes]({% link reference/vtctl.md %}#migrateservedtypes)
-command lets you do this one
-[tablet type]({% link overview/concepts.md %}#tablet) at a time,
-and even one [cell]({% link overview/concepts.md %}#cell-data-center)
-at a time. The process can be rolled back at any point *until* the master is
-switched over.
-
-``` sh
-vitess/examples/local$ ./lvtctl.sh MigrateServedTypes test_keyspace/0 rdonly
-vitess/examples/local$ ./lvtctl.sh MigrateServedTypes test_keyspace/0 replica
-vitess/examples/local$ ./lvtctl.sh MigrateServedTypes test_keyspace/0 master
-```
-
-During the *master* migration, the original shard master will first stop
-accepting updates. Then the process will wait for the new shard masters to
-fully catch up on filtered replication before allowing them to begin serving.
-Since filtered replication has been following along with live updates, there
-should only be a few seconds of master unavailability.
-
-When the master traffic is migrated, the filtered replication will be stopped.
-Data updates will be visible on the new shards, but not on the original shard.
-See it for yourself: Add a message to the guestbook page and then inspect
-the database content:
-
-``` sh
-# See what's on shard test_keyspace/0
-# (no updates visible since we migrated away from it):
-vitess/examples/local$ ./lvtctl.sh ExecuteFetchAsDba test-0000000100 "SELECT * FROM messages"
-# See what's on shard test_keyspace/-80:
-vitess/examples/local$ ./lvtctl.sh ExecuteFetchAsDba test-0000000200 "SELECT * FROM messages"
-# See what's on shard test_keyspace/80-:
-vitess/examples/local$ ./lvtctl.sh ExecuteFetchAsDba test-0000000300 "SELECT * FROM messages"
-```
-
-## Remove original shard
-
-Now that all traffic is being served from the new shards, we can remove the
-original one. To do that, we use the `vttablet-down.sh` script from the
-unsharded example:
-
-``` sh
-vitess/examples/local$ ./vttablet-down.sh
-```
-
-Then we can delete the now-empty shard:
-
-``` sh
-vitess/examples/local$ ./lvtctl.sh DeleteShard -recursive test_keyspace/0
-```
-
-You should then see in the vtctld **Topology** page, or in the output of
-`lvtctl.sh ListAllTablets test` that the tablets for shard *0* are gone.
-
-## Tear down and clean up
-
-Since you already cleaned up the tablets from the original unsharded example by
-running `./vttablet-down.sh`, that step has been replaced with
-`./sharded-vttablet-down.sh` to clean up the new sharded tablets.
-
-``` sh
-vitess/examples/local$ ./vtgate-down.sh
-vitess/examples/local$ ./sharded-vttablet-down.sh
-vitess/examples/local$ ./vtctld-down.sh
-vitess/examples/local$ ./zk-down.sh
-```
-
diff --git a/doc/HorizontalReshardingWorkflowGuide.md b/doc/HorizontalReshardingWorkflowGuide.md
deleted file mode 100644
index ff3eb8b0809..00000000000
--- a/doc/HorizontalReshardingWorkflowGuide.md
+++ /dev/null
@@ -1,262 +0,0 @@
-This guide shows you an example about how to apply range-based sharding
-process in an existing unsharded Vitess [keyspace]({% link overview/concepts.md %}#keyspace)
-using the horizontal resharding workflow. In this example, we will reshard
-from 1 shard "0" into 2 shards "-80" and "80-".
-
-## Overview
-
-The horizontal resharding process mainly contains the following steps
-(each step is a phase in the workflow):
-
-1. Copy schema from original shards to destination shards.
- (**Phase: CopySchemaShard**)
-1. Copy the data with a batch process called *vtworker*
- (**Phase: SplitClone**).
- [more details](#details-in-splitclone-phase)
-1. Check filtered replication (**Phase: WaitForFilteredReplication**).
- [more details](#details-in-waitforfilteredreplication-phase)
-1. Check copied data integrity using *vtworker* batch process in the mode
- to compare the source and destination data. (**Phase: SplitDiff**)
-1. Migrate all the serving rdonly tablets in the original shards.
- (**Phase: MigrateServedTypeRdonly**)
-1. Migrate all the serving replica tablets in the original shards.
- (**Phase: MigrateServedTypeReplica**)
-1. Migrate all the serving master tablets in the original shards.
- (**Phase: MigrateServedTypeMaster**)
- [more details](#details-in-migrateservedtypemaste-phase)
-
-## Prerequisites
-
-You should complete the [Getting Started]({% link getting-started/local-instance.md %}) guide
-(please finish all the steps before Try Vitess resharding) and have left
-the cluster running. Then, please follow these steps before running
-the resharding process:
-
-1. Configure sharding information. By running the command below, we tell
- Vitess to shard the data using the page column through the provided VSchema.
-
- ``` sh
- vitess/examples/local$ ./lvtctl.sh ApplyVSchema -vschema "$(cat vschema.json)" test_keyspace
- ```
-
-1. Bring up tablets for 2 additional shards: *test_keyspace/-80* and
- *test_keyspace/80-* (you can learn more about sharding key range
- [here]({% link user-guide/sharding.md %}#key-ranges-and-partitions)):
-
- ``` sh
- vitess/examples/local$ ./sharded-vttablet-up.sh
- ```
-
- Initialize replication by electing the first master for each of the new shards:
-
- ``` sh
- vitess/examples/local$ ./lvtctl.sh InitShardMaster -force test_keyspace/-80 test-200
- vitess/examples/local$ ./lvtctl.sh InitShardMaster -force test_keyspace/80- test-300
- ```
-
- After this set up, you should see the shards on Dashboard page of vtctld UI
- (http://localhost:15000). There should be 1 serving shard named "0" and
- 2 non-serving shards named "-80" and "80-". Click the shard node, you can
- inspect all its tablets information.
-
-1. Bring up a vtworker process, which can be connected through port 15033.
- (The number of *vtworker* should be the same of original shards,
- we start one vtworker process here since we have only one original shard
- in this example.)
-
- ``` sh
- vitess/examples/local$ ./vtworker-up.sh
- ```
-
- You can verify this *vtworker* process set up through http://localhost:15032/Debugging.
- It should be pinged successfully. After you ping the vtworker, please click
- "Reset Job". Otherwise, the vtworker is not ready for executing other tasks.
-
-## Horizontal resharding workflow
-
-### Create the workflow
-
-1. Open the *Workflows* section on the left menu of vtctld UI (http://localhost:15000).
- Click the "+" button in the top right corner to open the "Create
- a new Workflow" dialog.
-1. Fill in the "Create a new Workflow" dialogue following the instructions
- below (you can checkout our example [here](https://cloud.githubusercontent.com/assets/23492389/24314500/27f27988-109f-11e7-8e10-630bad14a286.png)):
- * Select the "Skip Start" checkbox if you don't want to start the workflow
- immediately after creation. If so, you need to click a "Start" button in
- the workflow bar later to run the workflow.
- * Open the "Factory Name" menu and select "Horizontal Resharding". This field
- defines the type of workflow you want to create.
- * Fill in *test_keyspace* in the "Keyspace" slot.
- * Fill in *localhost:15033* in the "vtworker Addresses" slot.
- * Unselect the "enable_approvals" checkbox if you don't want to manually
- approve task executions for canarying. (We suggest you to keep the default
- selected choice since this will enable the canary feature)
-1. Click "Create" button at the bottom of the dialog. You will see a workflow
- node created in the *Workflows* page if the creation succeeds.
- The workflow has started running now if "Skip Start" is not selected.
-
-Another way to start the workflow is through the vtctlclient command, you can
-also visualize the workflow on vtctld UI *Workflows* section after executing
-the command:
-
-``` sh
-vitess/examples/local$ ./lvtctl.sh WorkflowCreate -skip_start=false horizontal_resharding -keyspace=test_keyspace -vtworkers=localhost:15033 -enable_approvals=true
-```
-
-When creating the resharding workflow, the program automatically detect the
-source shards and destination shards and create tasks for the resharding
-process. After the creation, click the workflow node, you can see a list of
-child nodes. Each child node represents a phase in the workflow (each phase
-represents a step mentioned in [Overview]({% link user-guide/horizontal-sharding-workflow.md %}#overview)).
-Further click a phase node, you can inspect tasks in this phase.
-For example, in the "CopySchemaShard" phase, it includes tasks to copy schema
-to 2 destination shards, therefore you can see task node "Shard -80" and
-"Shard 80-". You should see a page similar to
-[this](https://cloud.githubusercontent.com/assets/23492389/24313539/71c9c8ae-109a-11e7-9e4a-0c3e8ee8ba85.png).
-
-### Approvals of Tasks Execution (Canary feature)
-
-Once the workflow start to run (click the "Start" button if you selected
-"Skip Start" and the workflow hasn't started yet.), you need to approve the
-task execution for each phase if "enable_approvals" is selected. The approvals
-include 2 stages. The first stage approves only the first task, which runs as
-canarying. The second stage approves the remaining tasks.
-
-The resharding workflow runs through phases sequentially. Once the phase starts,
-you can see the approval buttons for all the stages under the phase node (click
-the phase node if you didn't see the approval buttons, you should see a page
-like [this](https://cloud.githubusercontent.com/assets/23492389/24313613/c9508ef0-109a-11e7-8848-75a1ae18a6c5.png)). The
-button is enabled when the corresponding task(s) are ready to run. Click the
-enabled button to approve task execution, then you can see approved message
-on the clicked button. The approval buttons are cleared after the phase has
-finished. The next phase will only starts if its previous phase has finished
-successfully.
-
-If the workflow is restored from a checkpoint, you will still see the
-approval button with approved message when there are running tasks under this
-approval. But you don't need to approve the same tasks again for a restarted
-workflow.
-
-### Retry
-
-A "Retry" button will be enabled under the task node if the task failed (click
-the task node if your job get stuck but don't see the Retry button). Click this
-button if you have fixed the bugs and want to retry the failed task. You can
-retry as many times as you want if the task continually failed. The workflow
-can continue from your failure point once it is fixed.
-
-For example, you might forget to bring up a vtworker process. The task which
-requires that vtworker process in SplitClone phase will fail. After you fix
-this, click the retry button on the task node and the workflow will continue
-to run.
-
-When a task failed, the execution of other tasks under this phase won't be
-affected if this phase runs tasks in parallel (applied to phase
-"CopySchemaShard", "SplitClone", "WaitForFilteredReplication"). For phases
-that runs tasks sequentially, remaining unstarted tasks under this phase will
-no long be executed. The phases afterwards will no longer be executed.
-
-### Checkpoint and Recovery
-
-The resharding workflow tracks the status for every task and checkpoint these
-status into topology server whenever there is a status update. When a workflow
-is stopped and restarted by loading the checkpoint in the topology, it can
-continue to run all the unfinished tasks.
-
-
-## Verify Results and Clean up
-
-After the resharding process, data in the original shard is identically copied
-to new shards. Data updates will be visible on the new shards, but not on the
-original shard. You should then see in the vtctld UI *Dashboard* page that shard
-*0* becomes non-serving and shard *-80* and shard *80-* are serving shards.
-Verify this for yourself: inspect the database content using following commands,
-then add messages to the guestbook page (you can use script client.sh mentioned
-[here]({% link getting-started/local-instance.md %}#run-a-client-application))
-and inspect using same commands:
-
-``` sh
-# See what's on shard test_keyspace/0
-# (no updates visible since we migrated away from it):
-vitess/examples/local$ ./lvtctl.sh ExecuteFetchAsDba test-100 "SELECT * FROM messages"
-# See what's on shard test_keyspace/-80:
-vitess/examples/local$ ./lvtctl.sh ExecuteFetchAsDba test-200 "SELECT * FROM messages"
-# See what's on shard test_keyspace/80-:
-vitess/examples/local$ ./lvtctl.sh ExecuteFetchAsDba test-300 "SELECT * FROM messages"
-```
-
-You can also checkout the *Topology* browser on vtctl UI. It shows you the
-information of the keyrange of shard and their serving status. Each shard
-should look like this
-
-[shard 0](https://cloud.githubusercontent.com/assets/23492389/24313876/072f61e6-109c-11e7-938a-23b8398958aa.png)
-
-[shard -80](https://cloud.githubusercontent.com/assets/23492389/24313813/bd11c824-109b-11e7-83d4-cca3f6093360.png)
-
-[shard 80-](https://cloud.githubusercontent.com/assets/23492389/24313743/7f9ae1c4-109b-11e7-997a-774f4f16e473.png)
-
-After you verify the result, we can remove the
-original shard since all traffic is being served from the new shards:
-
-``` sh
-vitess/examples/local$ ./vttablet-down.sh
-```
-
-Then we can delete the now-empty shard:
-
-``` sh
-vitess/examples/local$ ./lvtctl.sh DeleteShard -recursive test_keyspace/0
-```
-
-You should then see in the vtctld UI *Dashboard* page that shard *0* is gone.
-
-## Tear down and clean up
-
-Since you already cleaned up the tablets from the original unsharded example by
-running `./vttablet-down.sh`, that step has been replaced with
-`./sharded-vttablet-down.sh` to clean up the new sharded tablets.
-
-``` sh
-vitess/examples/local$ ./vtworker-down.sh
-vitess/examples/local$ ./vtgate-down.sh
-vitess/examples/local$ ./sharded-vttablet-down.sh
-vitess/examples/local$ ./vtctld-down.sh
-vitess/examples/local$ ./zk-down.sh
-```
-
-## Reference
-
-You can checkout the old version tutorial [here]({% link user-guide/horizontal-sharding.md %}).
-It walks you through the resharding process by manually executing commands.
-
-### Details in SplitClone phase
-
-*vtworker* copies data from a paused snapshot. It will pause replication on
-one rdonly (offline processing) tablet to serve as a consistent snapshot of
-the data. The app can continue without downtime, since live traffic is served
-by replica and master tablets, which are unaffected. Other batch jobs will
-also be unaffected, since they will be served only by the remaining, un-paused
-rdonly tablets.
-
-During the data copying, *vtworker* streams the data from a single source to
-multiple destinations, routing each row based on its *keyspace_id*. It can
-automatically figure out which shards to use as the destinations based on the
-key range that needs to be covered. In our example, shard 0 covers the entire
-range, so it identifies -80 and 80- as the destination shards, since they
-combine to cover the same range.
-
-### Details in WaitForFilteredReplication phase
-
-Once the copying from a paused snapshot (phase SplitClone) has finished,
-*vtworker* turns on [filtered replication]({% link user-guide/sharding.md %}#filtered-replication),
-which allows the destination shards to catch up on updates that have continued
-to flow in from the app since the time of the snapshot. After the destination
-shards are caught up, they will continue to replicate new updates.
-
-### Details in MigrateServedTypeMaster phase
-
-During the *master* migration, the original shard masters will first stop
-accepting updates. Then the process will wait for the new shard masters to
-fully catch up on filtered replication before allowing them to begin serving.
-After the master traffic is migrated, the filtered replication will be stopped.
-Data updates will be visible on the new shards, but not on the original shards.
diff --git a/doc/Messaging.md b/doc/Messaging.md
deleted file mode 100644
index f605002c49d..00000000000
--- a/doc/Messaging.md
+++ /dev/null
@@ -1,209 +0,0 @@
-# Vitess Messaging
-
-## Overview
-
-Vitess messaging gives the application an easy way to schedule and manage work
-that needs to be performed asynchronously. Under the covers, messages are
-stored in a traditional MySQL table and therefore enjoy the following
-properties:
-
-* **Scalable**: Because of vitess's sharding abilities, messages can scale to
- very large QPS or sizes.
-* **Guaranteed delivery**: A message will be indefinitely retried until a
- successful ack is received.
-* **Non-blocking**: If the sending is backlogged, new messages continue to be
- accepted for eventual delivery.
-* **Adaptive**: Messages that fail delivery are backed off exponentially.
-* **Analytics**: The retention period for messages is dictated by the
- application. One could potentially choose to never delete any messages and
- use the data for performing analytics.
-* **Transactional**: Messages can be created or acked as part of an existing
- transaction. The action will complete only if the commit succeeds.
-
-The properties of a message are chosen by the application. However, every
-message needs a uniquely identifiable key. If the messages are stored in a
-sharded table, the key must also be the primary vindex of the table.
-
-Although messages will generally be delivered in the order they're created,
-this is not an explicit guarantee of the system. The focus is more on keeping
-track of the work that needs to be done and ensuring that it was performed.
-Messages are good for:
-
-* Handing off work to another system.
-* Recording potentially time-consuming work that needs to be done
- asynchronously.
-* Scheduling for future delivery.
-* Accumulating work that could be done during off-peak hours.
-
-Messages are not a good fit for the following use cases:
-
-* Broadcasting of events to multiple subscribers.
-* Ordered delivery.
-* Real-time delivery.
-
-## Creating a message table
-
-The current implementation requires a fixed schema. This will be made more
-flexible in the future. There will also be a custom DDL syntax. For now, a
-message table must be created like this:
-
-```
-create table my_message(
- time_scheduled bigint,
- id bigint,
- time_next bigint,
- epoch bigint,
- time_created bigint,
- time_acked bigint,
- message varchar(128),
- primary key(time_scheduled, id),
- unique index id_idx(id),
- index next_idx(time_next, epoch)
-) comment 'vitess_message,vt_ack_wait=30,vt_purge_after=86400,vt_batch_size=10,vt_cache_size=10000,vt_poller_interval=30'
-```
-
-The application-related columns are as follows:
-
-* `id`: can be any type. Must be unique.
-* `message`: can be any type.
-* `time_scheduled`: must be a bigint. It will be used to store unix time in
- nanoseconds. If unspecified, the `Now` value is inserted.
-
-The above indexes are recommended for optimum performance. However, some
-variation can be allowed to achieve different performance trade-offs.
-
-The comment section specifies additional configuration parameters. The fields
-are as follows:
-
-* `vitess_message`: Indicates that this is a message table.
-* `vt_ack_wait=30`: Wait for 30s for the first message ack. If one is not
- received, resend.
-* `vt_purge_after=86400`: Purge acked messages that are older than 86400
- seconds (1 day).
-* `vt_batch_size=10`: Send up to 10 messages per RPC packet.
-* `vt_cache_size=10000`: Store up to 10000 messages in the cache. If the demand
- is higher, the rest of the items will have to wait for the next poller cycle.
-* `vt_poller_interval=30`: Poll every 30s for messages that are due to be sent.
-
-If any of the above fields are missing, vitess will fail to load the table. No
-operation will be allowed on a table that has failed to load.
-
-## Enqueuing messages
-
-The application can enqueue messages using an insert statement:
-
-```
-insert into my_message(id, message) values(1, 'hello world')
-```
-
-These inserts can be part of a regular transaction. Multiple messages can be
-inserted to different tables. Avoid accumulating too many big messages within a
-transaction as it consumes memory on the VTTablet side. At the time of commit,
-memory permitting, all messages are instantly enqueued to be sent.
-
-Messages can also be created to be sent in the future:
-
-```
-insert into my_message(id, message, time_scheduled) values(1, 'hello world', :future_time)
-```
-
-`future_time` must be the unix time expressed in nanoseconds.
-
-## Receiving messages
-
-Processes can subscribe to receive messages by sending a `MessageStream`
-request to VTGate. 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 vitess `Result`. This means that
-standard database tools that understand query results can also be message
-recipients. Currently, there is no SQL format for subscribing to messages, but
-one will be provided soon.
-
-### Subsetting
-
-It's possible that you may want to subscribe to specific shards or groups of
-shards while requesting messages. This is useful for partitioning or load
-balancing. The `MessageStream` API allows you to specify these constraints. The
-request parameters are as follows:
-
-* `Name`: Name of the message table.
-* `Keyspace`: Keyspace where the message table is present.
-* `Shard`: For unsharded keyspaces, this is usually "0". However, an empty
- shard will also work. For sharded keyspaces, a specific shard name can be
- specified.
-* `KeyRange`: If the keyspace is sharded, streaming will be performed only from
- the shards that match the range. This must be an exact match.
-
-## Acknowledging messages
-
-A received (or processed) message can be acknowledged using the `MessageAck`
-API call. This call accepts the following parameters:
-
-* `Name`: Name of the message table.
-* `Keyspace`: Keyspace where the message table is present. This field can be
- empty if the table name is unique across all keyspaces.
-* `Ids`: The list of ids that need to be acked.
-
-Once a message is successfully acked, it will never be resent.
-
-## Exponential backoff
-
-A message that was successfully sent will wait for the specified ack wait time.
-If no ack is received by then, it will be resent. The next attempt will be 2x
-the previous wait, and this delay is doubled for every attempt.
-
-## Purging
-
-Messages that have been successfully acked will be deleted after their age
-exceeds the time period specified by `vt_purge_after`.
-
-## Advanced usage
-
-The `MessageAck` functionality is currently an API call and cannot be used
-inside a transaction. However, you can ack messages using a regular DML. It
-should look like this:
-
-```
-update my_message set time_acked = :time_acked, time_next = null where id in ::ids and time_acked is null
-```
-
-You can manually change the schedule of existing messages with a statement like
-this:
-
-```
-update my_message set time_next = :time_next, epoch = :epoch where id in ::ids and time_acked is null
-```
-
-This comes in handy if a bunch of messages had chronic failures and got
-postponed to the distant future. If the root cause of the problem was fixed,
-the application could reschedule them to be delivered immediately. You can also
-optionally change the epoch. Lower epoch values increase the priority of the
-message and the back-off is less aggressive.
-
-You can also view messages using regular `select` queries.
-
-## Undocumented features
-
-These are features that were previously known limitations, but have since been supported
-and are awaiting further documentation.
-
-* Flexible columns: Allow any number of application defined columns to be in
- the message table.
-* No ACL check for receivers: To be added.
-* Monitoring support: To be added.
-* Dropped tables: The message engine does not currently detect dropped tables.
-
-## Known limitations
-
-The message feature is currently in alpha, and can be improved. Here is the
-list of possible limitations/improvements:
-
-* Proactive scheduling: Upcoming messages can be proactively scheduled for
- timely delivery instead of waiting for the next polling cycle.
-* Changed properties: Although the engine detects new message tables, it does
- not refresh properties of an existing table.
-* A `SELECT` style syntax for subscribing to messages.
-* No rate limiting.
-* Usage of partitions for efficient purging.
diff --git a/doc/Monitoring.md b/doc/Monitoring.md
deleted file mode 100644
index aa1a163d17a..00000000000
--- a/doc/Monitoring.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Vitess Monitoring
-
-This page explains the current state of Vitess metrics monitoring, and potential future work in the area.
-
-## Current state of monitoring
-
-There are currently three main ways that a Vitess cluster can be monitored. Depending on your needs, you can use any of the following methods:
-
-### 1. Vitess status pages
-
-The status HTML pages of various Vitess components can be accessed by pointing your browser to `http://:/debug/status`. The status pages will often display some basic, but useful, information for monitoring. For example, the status page of a vttablet will show the QPS graph for the past few minutes.
-
-Viewing a status page can be useful since it works out of the box, but it only provides very basic monitoring capabilities.
-
-### 2. Pull-based metrics system
-
-Vitess uses Go’s [expvar package](https://golang.org/pkg/expvar/) to expose various metrics, with the expectation that a user can configure a pull-based metrics system to ingest those metrics. Metrics are published to `http://:/debug/vars` as JSON key-value pairs, which should be easy for any metrics system to parse.
-
-Scraping Vitess variables is a good way to integrate Vitess into an existing monitoring system, and is useful for building up detailed monitoring dashboards. It is also the officially supported way for monitoring Vitess.
-
-### 3. Push-based metrics system
-
-Vitess also includes support for push-based metrics systems via plug-ins. Each Vitess component would need to be run with the `--emit_stats` flag.
-
-By default, the stats_emit_period is 60s, so each component will push stats to the selected backend every minute. This is configurable via the `--stats_emit_period` flag.
-
-Vitess has preliminary plug-ins to support OpenTSDB as a push-based metrics backend.
-
-It should be fairly straightforward to write your own plug-in, if you want to support a different backend. The plug-in package simply needs to implement the `PushBackend` interface of the `stats` package. For an example, you can see the [OpenTSDB plugin](https://github.com/vitessio/vitess/blob/master/go/stats/opentsdb/opentsdb.go).
-
-Once you’ve written the backend plug-in, you also need to register the plug-in from within all the relevant Vitess binaries. An example of how to do this can be seen in [this pull request](https://github.com/vitessio/vitess/pull/469).
-
-You can then specify that Vitess should publish stats to the backend that you’re targeting by using the `--stats_backend` flag.
-
-Connecting Vitess to a push-based metrics system can be useful if you’re already running a push-based system that you would like to integrate into. More discussion on using a push vs pull based monitoring system can be seen here: [http://www.boxever.com/push-vs-pull-for-monitoring](https://www.boxever.com/push-vs-pull-for-monitoring)
-
-## Monitoring with Kubernetes
-
-The existing methods for integrating metrics are not supported in a Kubernetes environment by the Vitess team yet, but are on the roadmap for the future. However, it should be possible to get the Prometheus backend working with Kubernetes, similar to how [Heapster for Kubernetes works](https://github.com/kubernetes/kubernetes/tree/master/cluster/addons/prometheus).
-
-In the meantime, if you run into issues or have questions, please post on our [forum](https://groups.google.com/forum/#!forum/vitess).
-
-
diff --git a/doc/MySQLServerProtocol.md b/doc/MySQLServerProtocol.md
deleted file mode 100644
index fc52b1638b4..00000000000
--- a/doc/MySQLServerProtocol.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# MySQL Binary Protocol
-
-Vitess supports MySQL binary protocol. This allows existing applications to connect to Vitess directly without any change, or without using a new driver or connector. This is now the recommended and the most popular protocol for connecting to Vitess.
-
-# Features of RPC protocol not supported by SQL protocol
-
-### Bind Variables
-The RPC protocol supports bind variables which allows Vitess to cache query plans providing much better execution times.
-
-### Event Tokens
-The RPC protocols allows you to use event tokens to get the latest binlog position. These can be used for cache invalidation.
-
-### Update Stream
-Update stream allows you to subscribe to changing rows.
-
-### Query Multiplexing
-Ability to multiplex multiple request/responses on the same TCP connection.
\ No newline at end of file
diff --git a/doc/Production.md b/doc/Production.md
deleted file mode 100644
index 1b49fca93b9..00000000000
--- a/doc/Production.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Production setup
-Setting up vitess in production will depend on many factors.
-Here are some initial considerations:
-
-* *Global Transaction IDs*: Vitess requires a version of MySQL
-that supports GTIDs.
-We currently support MariaDB 10.0 and MySQL 5.6.
-* *Firewalls*: Vitess tools and servers assume that they
-can open direct TCP connection to each other. If you have
-firewalls between your servers, you may have to add exceptions
-to allow these communications.
-* *Authentication*: If you need authentication, you
-need to setup SASL, which is supported by Vitess.
-* *Encryption:* Vitess RPC servers support SSL.
-* *MySQL permissions*: Vitess currently assumes that all
-application clients have uniform permissions.
-The connection pooler opens a number of connections under
-the same user (vt_app), and rotates them for all requests.
-Vitess management tasks use a different user name (vt_dba),
-which is assumed to have all administrative privileges.
-* *Client Language*: We currently support
-Python and Go.
-It's not too hard to add support for more languages,
-and we are open to contributions in this area.
-
-## Deploying in Kubernetes
-
-See the [Getting Started]({% link getting-started/index.md %}) guide.
-
-## Deploying on bare metal
-
-See the
-[Local Setup](https://github.com/vitessio/vitess/tree/master/examples/local)
-scripts for examples of how to bring up a Vitess cluster manually.
diff --git a/doc/ProductionPlanning.md b/doc/ProductionPlanning.md
deleted file mode 100644
index 4f0ab2d9d15..00000000000
--- a/doc/ProductionPlanning.md
+++ /dev/null
@@ -1,73 +0,0 @@
-## Provisioning
-
-### Estimating total resources
-
-Although Vitess helps you scale indefinitely, the various layers do consume CPU and memory. Currently, the cost of Vitess servers is dominated by the RPC framework which we use: gRPC (gRPC is a relatively young product). So, Vitess servers are expected to get more efficient over time as there are improvements in gRPC as well as the Go runtime. For now, you can use the following rules of thumb to budget resources for Vitess:
-
-Every MySQL instance that serves traffic requires one VTTablet, which is in turn expected to consume an equal amount of CPU. So, if MySQL consumes 8 CPUs, VTTablet is likely going to consume another 8.
-
-The memory consumed by VTTablet depends on QPS and result size, but you can start off with the rule of thumb of requesting 1 GB/CPU.
-
-As for VTGate, double the total number of CPUs you’ve allocated for VTTablet. That should be approximately how much the VTGates are expected to consume. In terms of memory, you should again budget about 1 GB/CPU (needs verification).
-
-Vitess servers will use disk space for their logs. A smoothly running server should create very little log spam. However, log files can grow big very quickly if there are too many errors. It will be wise to run a log purger daemon if you’re concerned about filling up disk.
-
-Vitess servers are also likely to add about 2 ms of round-trip latency per MySQL call. This may result in some hidden costs that may or may not be negligible. On the app side, if a significant time is spent making database calls, then you may have to run additional threads or workers to compensate for the delay, which may result in additional memory requirements.
-
-The client driver CPU usage may be different from a normal MySQL driver. That may require you to allocate more CPU per app thread.
-
-On the server side, this could result in longer running transactions, which could weigh down MySQL.
-
-With the above numbers as starting point, the next step will be to set up benchmarks that generate production representative load. If you cannot afford this luxury, you may have to go into production with some over-provisioning, just in case.
-
-### Mapping topology to hardware
-
-The different Vitess components have different resource requirements e.g. vtgate requires little disk in comparison to vttablet. Therefore, the components should be mapped to different machine classes for optimal resource usage. If you’re using a cluster manager (such as Kubernetes), the automatic scheduler will do this for you. Otherwise, you have to allocate physical machines and plan out how you’re going to map servers onto them.
-
-Machine classes needed:
-
-#### MySQL + vttablet
-
-You’ll need database-class machines that are likely to have SSDs, and enough RAM to fit the MySQL working set in buffer cache. Make sure that there will be sufficient CPU left for VTTablet to run on them.
-
-The VTTablet provisioning will be dictated by the MySQL instances they run against. However, soon after launch, it’s recommended to shard these instances to a data size of 100-300 GB. This should also typically reduce the per-MySQL CPU usage to around 2-4 CPUS depending on the load pattern.
-
-#### VTGate
-
-For VTGates, you’ll need a class of machines that would be CPU heavy, but may be light on memory usage, and should require normal hard disks, for binary and logs only.
-
-It’s advisable to run more instances than there are machines. VTGates are happiest when they’re consuming between 2-4 CPUs. So, if your total requirement was 400 CPUs, and your VTGate class machine has 48 cores each, you’ll need about 10 such machines and you’ll be running about 10 VTGates per box.
-
-You may have to add a few more app class machines to absorb any additional CPU and latency overheads.
-
-## Lock service setup
-
-The Lock Service should be running, and both the global and local instances
-should be up. See the
-[Topology Service]({% link user-guide/topology-service.md %})
-document for more information.
-
-Each lock service implementation supports a couple configuration command line
-parameters, they need to be specified for each Vitess process.
-
-For sizing purposes, the Vitess processes do not access the lock service very
-much. Each *vtgate* process keeps a few watches on a few local nodes (VSchema
-and SrvKeyspace). Each *vttablet* process will keep its own Tablet record up to
-date, but it usually doesn't change. The *vtctld* process will access it a lot
-more, but only on demand to display web pages.
-
-As mentioned previously, if the setup is only in one cell, the global and local
-instances can be combined. Just use different top-level directories.
-
-## Production testing
-
-Before running Vitess in production, please make yourself comfortable first with the different operations. We recommend to go through the following scenarios on a non-production system.
-
-Here is a short list of all the basic workflows Vitess supports:
-
-* [Failover / Reparents]({% link user-guide/reparenting.md %})
-* [Backup/Restore]({% link user-guide/backup-and-restore.md %})
-* [Schema Management]({% link user-guide/schema-management.md %}) / [Schema Swap]({% link user-guide/schema-swap.md %})
-* [Resharding]({% link user-guide/sharding.md %}) / [Horizontal Resharding Tutorial]({% link user-guide/horizontal-sharding.md %})
-* [Upgrading]({% link user-guide/upgrading.md %})
-
diff --git a/doc/ReferenceTables.md b/doc/ReferenceTables.md
deleted file mode 100644
index ea262f5d695..00000000000
--- a/doc/ReferenceTables.md
+++ /dev/null
@@ -1,153 +0,0 @@
-# Reference Tables
-
-This document describes a proposed design and implementation guidelines for
-the `Reference Tables` Vitess feature.
-
-The idea is to have a `reference keyspace` that contains a small number of
-`reference tables`, and replicate these tables to every shard of another
-keyspace, the `destination keyspace`. Any update to the reference tables will be
-propagated to the destination keyspace. The reference tables in the destination
-keyspace can then be used directly, in read-only mode (in `JOIN` queries for
-instance). This provides for much better performance than cross-keyspace joins.
-
-Since the data is replicated to every shard on the destination keyspace, the
-write QPS on the reference keyspace is also applied to every shard on the
-destination keyspace. So the change rate in the reference keyspace cannot be
-very high, and so let's also assume it is not sharded.
-
-Vitess already has all the right components to support this scenario, it's just
-a matter of plumbing it the right way. Let's explore the required changes.
-
-## Replication Setup
-
-We can copy all the data and then setup `Filtered Replication` between the
-reference keyspace and each shard of the destination keyspace. This is really
-just a corner case of the vertical splits Vitess already supports.
-
-Action items:
-
-* First, this setup probably needs to be explicitly mentioned somewhere in the
- topology, not just as SourceShard objects in the destination keyspace, so
- Vitess can know about this setup at a higher level. Let's add a `repeated
- ReferenceKeyspace` field to the Keyspace object. Each `ReferenceKeyspace`
- object contains the name of the reference keyspace, the list of tables to
- copy, and the UID of the SourceShard entry (the same UID in all shards). By
- making this a repeated field, the destination keyspace should be able to
- support multiple reference keyspaces to copy data from, if necessary.
-
-* `vtctl CopySchemaShard` can already be used to copy the schema from the
- reference keyspace to each destination shard.
-
-* A new vtworker data copy job needs to be added. `vtworker VerticalSplitClone`
- would be a good start, but the new copy has a few special requirements: the
- destination keyspace needs the data in all its shards, and the write rate
- cannot cause the destination shards to be overloaded (or lag behind on
- replication). This job would also populate an entry in the
- `\_vt/blp\_checkpoint` table in the destination shards.
-
-* Setting up Filtered Replication after the copy is easy, each destination Shard
- just needs to have a SourceShard with the proper data, and after a
- RefreshTablet, the destination masters will start the replication.
-
-All these steps can be supported by a vtctld workflow.
-
-## Supporting Horizontal Resharding in the Destination Keyspace
-
-We still need to support horizontal resharding in the Destination Keyspace while
-the Reference Tables feature is enabled.
-
-Action items:
-
-* Each step of the process would know what to do because of the
- `ReferenceKeyspace` entries in the destination keyspace.
-
-* `vtctl CopySchemaShard` needs to also copy the schema of the reference tables.
-
-* `vtworker SplitClone` needs to also copy all of the reference table data, and
- the `\_vt/blp\_checkpoint` entry for the reference keyspace. It needs to do
- that copy from the first source shard to each destination shard only once. So
- in case of a split, the source shard data is copied to each destination
- shard. In case of a merge, only the first source shard data is copied to the
- destination shard.
-
-* Enabling filtered replication on the destination shards needs to not use the
- same UID for replication as the reference keyspace entries. Right now, their
- UID are hardcoded to start at 0. But since the reserved UIDs are documented in
- the `ReferenceKeyspace` entries, it's easy.
-
-* At this point, the destination shards will also replicate from the reference
- keyspace. When the `vtctl MigrateServedType master` command is issued, it
- needs to just remove the horizontal resharding Filtered Replication entries,
- not the `ReferenceKeyspace` entries entries.
-
-## Other Use Cases
-
-Other scenarios might also need to be supported, or explicitly disabled:
-
-* Simple schema changes, or complicated Schema Swap in the reference keyspace:
- They would also need to be applied to the destination keyspace, the same way.
-
-* Vertical Split of the reference keyspace: Since it is replicated, splitting it
- will be more complicated.
-
-## Query Routing
-
-This would be handled by the vtgate and the VSchema. Once the reference tables
-are documented in the VSchema, vtgate will know to do the following:
-
-* DMLs on the reference tables are routed to the reference keyspace.
-
-* Select queries on the reference tables only are also routed to the reference
- keyspace.
-
-* JOIN queries between reference tables and destination keyspace tables can be
- routed only to the right destination keyspace (based on that keyspace sharding
- situation).
-
-Note this introduces some corner cases: for instance, if the client is asking
-for a JOIN between reference tables and destination keyspace tables, with tablet
-type `master`. Routing this to the destination keyspace would satisfy the
-critical read for the destination tables, but not for the reference
-tables. vtgate may need to perform the JOIN to both masters at this point.
-
-Action Items:
-
-* Find the right way to represent reference tables in the VSchema.
-
-* Implement corresponding query routing.
-
-## Notes
-
-### Vitess Keyspace vs MySQL Database
-
-This may force us to revisit the use of databases in our tablets. The current
-assumption is that a keyspace only has one MySQL database (with a name usually
-derived from the keyspace name with a `vt_` prefix, but that can also be
-changed):
-
-* When vttablet connects to MySQL for data queries, it uses that database name
- by default.
-
-* The VSchema also maps tables to keyspaces, so it can just send queries that
- have no keyspace to the right shard (which in turns is configured properly for
- that database).
-
-* Vitess' Filtered Replication only replicates data related to that single
- database. The database name has to be the same when we horizontally split a
- keyspace, so statements from the source shards can be applied on the
- destination shards.
-
-* Vitess' Query Service only loads the schema for that single database.
-
-Maybe it's time to change this assumption:
-
-* A keyspace could be defined as a group of databases, each having a group of
- tables.
-
-* When addressing a table, we could support the `keyspace.database.table`
- syntax.
-
-* We could support moving databases from one keyspace to another.
-
-But maybe this is too many indirections for nothing? Saying one keyspace is one
-database may be just the complexity we need.
diff --git a/doc/Reparenting.md b/doc/Reparenting.md
deleted file mode 100644
index 5f0cf0ae35a..00000000000
--- a/doc/Reparenting.md
+++ /dev/null
@@ -1,185 +0,0 @@
-**Reparenting** is the process of changing a shard's master tablet
-from one host to another or changing a slave tablet to have a
-different master. Reparenting can be initiated manually
-or it can occur automatically in response to particular database
-conditions. As examples, you might reparent a shard or tablet during
-a maintenance exercise or automatically trigger reparenting when
-a master tablet dies.
-
-This document explains the types of reparenting that Vitess supports:
-
-* *[Active reparenting](#active-reparenting)* occurs when the Vitess
- toolchain manages the entire reparenting process.
-* *[External reparenting](#external-reparenting)* occurs when another tool
- handles the reparenting process, and the Vitess toolchain just updates its
- topology server, replication graph, and serving graph to accurately reflect
- master-slave relationships.
-
-**Note:** The InitShardMaster command defines the initial
-parenting relationships within a shard. That command makes the specified
-tablet the master and makes the other tablets in the shard slaves that
-replicate from that master.
-
-## MySQL requirements
-
-### GTIDs
-Vitess requires the use of global transaction identifiers
-([GTIDs](https://dev.mysql.com/doc/refman/5.6/en/replication-gtids-concepts.html)) for its operations:
-
-* During active reparenting, Vitess uses GTIDs to initialize the
- replication process and then depends on the GTID stream to be
- correct when reparenting. (During external reparenting, Vitess
- assumes the external tool manages the replication process.)
-* During resharding, Vitess uses GTIDs for
- [filtered replication]({% link user-guide/sharding.md %}#filtered-replication),
- the process by which source tablet data is transferred to the proper
- destination tablets.
-
-### Semisynchronous replication
-
-Vitess does not depend on
-[semisynchronous replication](https://dev.mysql.com/doc/refman/5.6/en/replication-semisync.html) but does work if it is implemented.
-Larger Vitess deployments typically do implement semisynchronous replication.
-
-## Active Reparenting
-
-You can use the following [vtctl]({% link reference/vtctl.md %})
-commands to perform reparenting operations:
-
-* PlannedReparentShard
-* EmergencyReparentShard
-
-Both commands lock the Shard record in the global topology server. The two commands
-cannot run in parallel, nor can either command run in parallel with the
-InitShardMaster command.
-
-The two commands are both dependent on the global topology server being
-available, and they both insert rows in the topology server's
-\_vt.reparent\_journal table. As such, you can review
-your database's reparenting history by inspecting that table.
-
-### PlannedReparentShard: Planned reparenting
-
-The PlannedReparentShard command reparents a healthy master
-tablet to a new master. The current and new master must both be up and
-running.
-
-This command performs the following actions:
-
-1. Puts the current master tablet in read-only mode.
-1. Shuts down the current master's query service, which is the part of
- the system that handles user SQL queries. At this point, Vitess does
- not handle any user SQL queries until the new master is configured
- and can be used a few seconds later.
-1. Retrieves the current master's replication position.
-1. Instructs the master-elect tablet to wait for replication data and
- then begin functioning as the new master after that data is fully
- transferred.
-1. Ensures replication is functioning properly via the following steps:
- 1. On the master-elect tablet, insert an entry in a test table
- and then update the global Shard object's
- MasterAlias record.
- 1. In parallel on each slave, including the old master, set the new
- master and wait for the test entry to replicate to the slave tablet.
- (Slave tablets that had not been replicating before the command was
- called are left in their current state and do not start replication
- after the reparenting process.)
- 1. Start replication on the old master tablet so it catches up to the
- new master.
-
-In this scenario, the old master's tablet type transitions to
-spare. If health checking is enabled on the old master,
-it will likely rejoin the cluster as a replica on the next health
-check. To enable health checking, set the
-target\_tablet\_type parameter when starting a tablet.
-That parameter indicates what type of tablet that tablet tries to be
-when healthy. When it is not healthy, the tablet type changes to
-spare.
-
-### EmergencyReparentShard: Emergency reparenting
-
-The EmergencyReparentShard command is used to force
-a reparent to a new master when the current master is unavailable.
-The command assumes that data cannot be retrieved from the current
-master because it is dead or not working properly.
-
-As such, this command does not rely on the current master at all
-to replicate data to the new master. Instead, it makes sure that
-the master-elect is the most advanced in replication within all
-of the available slaves.
-
-**Important:** Before calling this command, you must first identify
-the slave with the most advanced replication position as that slave
-must be designated as the new master. You can use the
-[vtctl ShardReplicationPositions]({% link reference/vtctl.md %}#shardreplicationpositions)
-command to determine the current replication positions of a shard's slaves.
-
-This command performs the following actions:
-
-1. Determines the current replication position on all of the slave
- tablets and confirms that the master-elect tablet has the most
- advanced replication position.
-1. Promotes the master-elect tablet to be the new master. In addition to
- changing its tablet type to master, the master-elect
- performs any other changes that might be required for its new state.
-1. Ensures replication is functioning properly via the following steps:
- 1. On the master-elect tablet, Vitess inserts an entry in a test table
- and then updates the MasterAlias record of the global
- Shard object.
- 1. In parallel on each slave, excluding the old master, Vitess sets the
- master and waits for the test entry to replicate to the slave tablet.
- (Slave tablets that had not been replicating before the command was
- called are left in their current state and do not start replication
- after the reparenting process.)
-
-## External Reparenting
-
-External reparenting occurs when another tool handles the process
-of changing a shard's master tablet. After that occurs, the tool
-needs to call the
-[vtctl TabletExternallyReparented]({% link reference/vtctl.md %}#tabletexternallyreparented)
-command to ensure that the topology server, replication graph, and serving
-graph are updated accordingly.
-
-That command performs the following operations:
-
-1. Locks the shard in the global topology server.
-1. Reads the Shard object from the global topology server.
-1. Reads all of the tablets in the replication graph for the shard.
- Vitess does allow partial reads in this step, which means that Vitess
- will proceed even if a data center is down as long as the data center
- containing the new master is available.
-1. Ensures that the new master's state is updated correctly and that the
- new master is not a MySQL slave of another server. It runs the MySQL
- show slave status command, ultimately aiming to confirm
- that the MySQL reset slave command already executed on
- the tablet.
-1. Updates, for each slave, the topology server record and replication
- graph to reflect the new master. If the old master does not return
- successfully in this step, Vitess changes its tablet type to
- spare to ensure that it does not interfere with ongoing
- operations.
-1. Updates the Shard object to specify the new master.
-
-The TabletExternallyReparented command fails in the following
-cases:
-
-* The global topology server is not available for locking and
- modification. In that case, the operation fails completely.
-
-Active reparenting might be a dangerous practice in any system
-that depends on external reparents. You can disable active reparents
-by starting vtctld with the
---disable\_active\_reparents flag set to true.
-(You cannot set the flag after vtctld is started.)
-
-## Fixing Replication
-
-A tablet can be orphaned after a reparenting if it is unavailable
-when the reparent operation is running but then recovers later on.
-In that case, you can manually reset the tablet's master to the
-current shard master using the
-[vtctl ReparentTablet]({% link reference/vtctl.md %}#reparenttablet)
-command. You can then restart replication on the tablet if it was stopped
-by calling the [vtctl StartSlave]({% link reference/vtctl.md %}#startslave)
-command.
diff --git a/doc/RowBasedReplication.md b/doc/RowBasedReplication.md
deleted file mode 100644
index f4bba3611d2..00000000000
--- a/doc/RowBasedReplication.md
+++ /dev/null
@@ -1,168 +0,0 @@
-# Row Based Replication
-
-In Vitess 2.2, we are adding preliminary support for Row Based Replication. This
-document explains how we are managing it and how it affects various Vitess
-features.
-
-See the [Vitess and Replication]({% link user-guide/vitess-replication.md %}) document
-for an introduction on various types of replication and how it affects Vitess.
-
-## MySQL Row Based Replication
-
-With Row Based replication, a more compact binary version of the rows affected
-are sent through the replication stream, instead of the SQL statements. The
-slaves then do not spend any time parsing the SQL, or performing any complex SQL
-operations (like `where` clauses). They can just apply the new rows directly.
-
-A few binlog events are used:
-
-* Table Map event: describes a table that is affected by the next
- events. Contains the database and table name, the number of columns, and the
- Type for each column. It does not contain the individual column names, nor the
- flags for each column (so it is impossible to differentiate signed vs unsigned
- integers for instance).
-
-* Write Rows: equivalent of Insert.
-
-* Update Rows: change the values of some rows.
-
-* Delete Rows: delete the provided rows.
-
-The
-[`binlog-row-image` option](https://dev.mysql.com/doc/refman/5.7/en/replication-options-binary-log.html#sysvar_binlog_row_image) can
-be used to control which rows are used to identify the columns for the Update
-and Delete Rows events. The default setting for that option is to log all
-columns.
-
-## Vitess Use of MySQL Replication Stream
-
-Vitess uses the Replication Stream in a number of places. This part explains how
-we use RBR for these.
-
-### vttablet Replication Stream Watcher
-
-This is enabled by the `watch_replication_stream` option, and is used
-by [Update Stream]({% link user-guide/update-stream.md %}). It only cares about the
-GTIDs for the events, so it is unaffected by the use of RBR.
-
-*Note*: the current vttablet also reloads the schema when it sees a DDL in the
-stream. See below for more information on this. DDLs are however not represented
-in RBR, so this is an orthogonal issue.
-
-### Update Stream
-
-The current implementation uses comments in the original SQL (in SQR) to provide
-the primary key of the column that is being changed.
-
-We are changing this to also parse the RBR events, and extract the primary key
-value.
-
-*Note*: this means we need accurate schema information. See below.
-
-### Filtered Replication
-
-This is used during horizontal and vertical resharding, to keep source and
-destination shards up to date.
-
-We need to transform the RBR events into SQL statements, filter them based
-either on keyspace_id (horizontal resharding) or table name (vertical
-resharding), and apply them.
-
-For horizontal splits, we need to understand the VSchema to be able to find the
-primary VIndex used for sharding.
-
-*Note*: this again means we need accurate schema information. We could do one of
-two things:
-
-* Send all statements to all destination shards, and let them do the
- filtering. They can have accurate schema information if they receive and apply
- all schema changes through Filtered Replication.
-
-* Have the filtering be done on the stream server side, and assume the schema
- doesn't change in incompatible ways. As this is simpler for now, that's the
- option we're going with.
-
-## Database Schema Considerations
-
-### Interpreting RBR Events
-
-A lot of the work to interpret RBR events correctly requires knowledge of the
-table's schema. However, this introduces the possibility of inconsistencies
-during schema changes: the current schema for a table might be newer than the
-schema an older replication stream event was using.
-
-For the short term, Vitess will not deal very gracefully with this scenario: we
-will only support the case where the current schema for a table has exactly the
-same columns as all events in the binlog, plus some other optional columns that
-are then unused. That way, it is possible to add columns to tables without
-breaking anything.
-
-Note if the main use case is Filtered Replication for resharding, this
-limitation only exists while the resharding process is running. It is somewhat
-easy to not change the schema at the same time as resharding is on-going.
-
-### Applying Schema Changes
-
-When using
-RBR, [Schema Swap]({% link user-guide/vitess-replication.md %}#vitess-schema-swap)
-becomes useless, as replication between hosts with different schemas will most
-likely break. This is however an existing limitation that is already known and
-handled by MySQL DBAs.
-
-Vitess at this point does not provide an integrated way of applying involved
-schema changes through RBR. A number of external tools however already exist to
-handle this case, like [gh-ost](https://github.com/github/gh-ost).
-
-We have future plans to:
-
-* Integrate with a tool like gh-ost to provide a seamless schema change story.
-
-* Maintain a history of the schema changes that happen on all shards, so events
- can be parsed correctly in all cases.
-
-## Unsupported Features
-
-This part describes the features that are not supported for RBR in Vitess as of
-March 2017:
-
-* *Fractional timestamps for MariaDB*: not supported. This affects the objects
- of type `TIMESTAMP`, `TIME` and `DATETIME`. The way that feature is
- implemented in MariaDB, the binary logs do not contain enough information to
- be parsed, but instead MariaDB relies on the schema knowledge. This is very
- fragile. MySQL 5.6+ added new data types, and these are supported.
-
-* *JSON type in MySQL 5.7+*: the representation of these in the binlogs is a
- blob containing indexed binary data. Re-building the SQL version of the data,
- so it can be re-inserted during resharding, is not supported yet. It wouldn't
- however be a lot of work, with other libraries also supporting this, and the
- C++ MySQL code being well written and easy to read. See for instance
- https://github.com/shyiko/mysql-binlog-connector-java/pull/119
-
-* *Timezones support*: the binary logs store timestamps in UTC. When converting
- these to SQL, we print the UTC value. If the server is not in UTC, that will
- result in data corruption. *Note*: we are working on a fix for that one.
-
-## Update Stream Extensions
-
-[Update Stream]({% link user-guide/update-stream.md %}) can be changed to contain both
-old and new values of the rows being changed. Again the values will depend on
-the schema. We will also make this feature optional, so if the client is using
-this for Primary Key based cache invalidation for instance, no extra unneeded
-data is sent.
-
-This can be used to re-populate a cache with Update Stream, instead of
-invalidating it, by putting the new values directly in there.
-
-Then, using this in conjunction with `binlog-row-image` would help provide a
-feature-complete way of always getting all changes on rows. It would also help
-handle Update Stream corner cases that replay events during resharding, when
-switching traffic from old to new shards.
-
-## Vttablet Simplifications
-
-A lot of the work done by vttablet now is to find the Primary Key of the
-modified rows, to rewrite the queries in an efficient way and tag each statement
-with the Primary Key. None of this may be necessary with RBR.
-
-We plan to eventually add a `rbr_mode` flag to vttablet to disable all the
-things it can skip if RBR is used.
diff --git a/doc/ScalabilityPhilosophy.md b/doc/ScalabilityPhilosophy.md
deleted file mode 100644
index f9ad7b5a6c2..00000000000
--- a/doc/ScalabilityPhilosophy.md
+++ /dev/null
@@ -1,247 +0,0 @@
-Scalability problems can be solved using many approaches. This document describes Vitess’ approach to address these problems.
-
-## Small instances
-
-When deciding to shard or break databases up into smaller parts, it’s tempting to break them just enough that they fit in one machine. In the industry, it’s common to run only one MySQL instance per host.
-
-Vitess recommends that instances be broken up to be even smaller, and not to shy away from running multiple instances per host. The net resource usage would be about the same. But the manageability greatly improves when MySQL instances are small. There is the complication of keeping track of ports, and separating the paths for the MySQL instances. However, everything else becomes simpler once this hurdle is crossed.
-
-There are fewer lock contentions to worry about, replication is a lot happier, production impact of outages become smaller, backups and restores run faster, and a lot more secondary advantages can be realized. For example, you can shuffle instances around to get better machine or rack diversity leading to even smaller production impact on outages, and improved resource usage.
-
-### Cloud Vs Baremetal
-
-Although Vitess is designed to run in the cloud, it is entirely possible to
-run it on baremetal configs, and many users still do. If deploying in a cloud,
-the assignment of servers and ports is abstracted away from the administrator.
-On baremetal, the operator still has these responsibilities.
-
-We provide sample configs to help you [get started on Kubernetes](https://vitess.io/docs/tutorials/kubernetes/)
-since it's the most similar to Borg (the [predecessor to Kubernetes](https://kubernetes.io/blog/2015/04/borg-predecessor-to-kubernetes/)
-on which Vitess now runs in YouTube).
-If you're more familiar with alternatives like Mesos, Swarm, Nomad, or DC/OS,
-we'd welcome your contribution of sample configs for Vitess.
-
-These orchestration systems typically use [containers](https://en.wikipedia.org/wiki/Software_container)
-to isolate small instances so they can be efficiently packed onto machines
-without contention on ports, paths, or compute resources.
-Then an automated scheduler does the job of shuffling instances around for
-failure resilience and optimum utilization.
-
-## Durability through replication
-
-Traditional data storage software treated data as durable as soon as it was flushed to disk. However, this approach is impractical in today’s world of commodity hardware. Such an approach also does not address disaster scenarios.
-
-The new approach to durability is achieved by copying the data to multiple machines, and even geographical locations. This form of durability addresses the modern concerns of device failures and disasters.
-
-Many of the workflows in Vitess have been built with this approach in mind. For example, turning on semi-sync replication is highly recommended. This allows Vitess to failover to a new replica when a master goes down, with no data loss. Vitess also recommends that you avoid recovering a crashed database. Instead, create a fresh one from a recent backup and let it catch up.
-
-Relying on replication also allows you to loosen some of the disk-based durability settings. For example, you can turn off sync\_binlog, which greatly reduces the number of IOPS to the disk thereby increasing effective throughput.
-
-## Consistency model
-
-Before sharding or moving tables to different keyspaces, the application needs to be verified (or changed) such that it can tolerate the following changes:
-
-* Cross-shard reads may not be consistent with each other. Conversely, the sharding decision should also attempt to minimize such occurrences because cross-shard reads are more expensive.
-* In "best-effort mode", cross-shard transactions can fail in the middle and result in partial commits. You could instead use "2PC mode" transactions that give you distributed atomic guarantees. However, choosing this option increases the write cost by approximately 50%.
-
-Single shard transactions continue to remain ACID, just like MySQL supports it.
-
-If there are read-only code paths that can tolerate slightly stale data, the queries should be sent to REPLICA tablets for OLTP, and RDONLY tablets for OLAP workloads. This allows you to scale your read traffic more easily, and gives you the ability to distribute them geographically.
-
-This tradeoff allows for better throughput at the expense of stale or possible inconsistent reads, since the reads may be lagging behind the master, as data changes (and possibly with varying lag on different shards). To mitigate this, VTGates are capable of monitoring replica lag and can be configured to avoid serving data from instances that are lagging beyond X seconds.
-
-For true snapshot, the queries must be sent to the master within a transaction. For read-after-write consistency, reading from the master without a transaction is sufficient.
-
-To summarize, these are the various levels of consistency supported:
-
-* REPLICA/RDONLY read: Servers be scaled geographically. Local reads are fast, but can be stale depending on replica lag.
-* MASTER read: There is only one worldwide master per shard. Reads coming from remote locations will be subject to network latency and reliability, but the data will be up-to-date (read-after-write consistency). The isolation level is READ\_COMMITTED.
-* MASTER transactions: These exhibit the same properties as MASTER reads. However, you get REPEATABLE\_READ consistency and ACID writes for a single shard. Support is underway for cross-shard Atomic transactions.
-
-As for atomicity, the following levels are supported:
-
-* SINGLE: disallow multi-db transactions.
-* MULTI: multi-db transactions with best effort commit.
-* TWOPC: multi-db transactions with 2pc commit.
-
-### No multi-master
-
-Vitess doesn’t support multi-master setup. It has alternate ways of addressing most of the use cases that are typically solved by multi-master:
-
-* Scalability: There are situations where multi-master gives you a little bit of additional runway. However, since the statements have to eventually be applied to all masters, it’s not a sustainable strategy. Vitess addresses this problem through sharding, which can scale indefinitely.
-* High availability: Vitess integrates with Orchestrator, which is capable of performing a failover to a new master within seconds of failure detection. This is usually sufficient for most applications.
-* Low-latency geographically distributed writes: This is one case that is not addressed by Vitess. The current recommendation is to absorb the latency cost of long-distance round-trips for writes. If the data distribution allows, you still have the option of sharding based on geographic affinity. You can then setup masters for different shards to be in different geographic location. This way, most of the master writes can still be local.
-
-### Big data queries
-
-There are two main ways to access the data for offline data processing (as
-opposed to online web or direct access to the live data): sending queries to
-rdonly servers, or using a Map Reduce framework.
-
-#### Batch queries
-
-These are regular queries, but they can consume a lot of data. Typically, the
-streaming APIs are used, to consume large quantities of data.
-
-These queries are just sent to the *rdonly* servers (also known as *batch*
-servers). They can take as much resources as they want without affecting live
-traffic.
-
-#### MapReduce
-
-Vitess supports MapReduce access to the data. Vitess provides a Hadoop
-connector, that can also be used with Apache Spark. See the [Hadoop package
-documentation](https://github.com/vitessio/vitess/tree/master/java/hadoop/src/main/java/io/vitess/hadoop)
-for more information.
-
-With a MapReduce framework, Vitess does not support very complicated
-queries. In part because it would be difficult and not very efficient, but also
-because the MapReduce frameworks are usually very good at data processing. So
-instead of doing very complex SQL queries and have processed results, it is
-recommended to just dump the input data out of Vitess (with simple *select*
-statements), and process it with a MapReduce pipeline.
-
-## Multi-cell
-
-Vitess is meant to run in multiple data centers / regions / cells. In this part,
-we'll use *cell* as a set of servers that are very close together, and share the
-same regional availability.
-
-A cell typically contains a set of tablets, a vtgate pool, and app servers that
-use the Vitess cluster. With Vitess, all components can be configured and
-brought up as needed:
-
-* The master for a shard can be in any cell. If cross-cell master access is
- required, vtgate can be configured to do so easily (by passing the cell that
- contains the master as a cell to watch).
-* It is not uncommon to have the cells that can contain the master be more
- provisioned than read-only serving cells. These *master-capable* cells may
- need one more replica to handle a possible failover, while still maintaining
- the same replica serving capacity.
-* Failing over from one master in one cell to a master in a different cell is no
- different than a local failover. It has an implication on traffic and latency,
- but if the application traffic also gets re-directed to the new cell, the end
- result is stable.
-* It is also possible to have some shards with a master in one cell, and some
- other shards with their master in another cell. vtgate will just route the
- traffic to the right place, incurring extra latency cost only on the remote
- access. For instance, creating U.S. user records in a database with masters in
- the U.S. and European user records in a database with masters in Europe is
- easy to do. Replicas can exist in every cell anyway, and serve the replica
- traffic quickly.
-* Replica serving cells are a good compromise to reduce user-visible latency:
- they only contain *replica* servers, and master access is always done
- remotely. If the application profile is mostly reads, this works really well.
-* Not all cells need *rdonly* (or batch) instances. Only the cells that run
- batch jobs, or MapReduce jobs, really need them.
-
-Note Vitess uses local-cell data first, and is very resilient to any cell going
-down (most of our processes handle that case gracefully).
-
-## Lock server
-
-Vitess is a highly available service, and Vitess itself needs to store a small
-amount of metadata very reliably. For that purpose, Vitess needs a highly
-available and consistent data store.
-
-Lock servers were built for this exact purpose, and Vitess needs one such
-cluster to be setup to run smoothly. Vitess can be customized to utilize any
-lock server, and by default it supports Zookeeper, etcd and Consul. We call this
-component [Topology Service]({% link user-guide/topology-service.md %}).
-
-As Vitess is meant to run in multiple data centers / regions (called cells
-below), it relies on two different lock servers:
-
-* global instance: it contains global meta data, like the list of Keyspaces /
- Shards, the VSchema, ... It should be reliable and distributed across multiple
- cells. Running Vitess processes almost never access the global instance.
-* per-cell instance (local): It should be running only in the local cell. It
- contains aggregates of all the global data, plus local running tablet
- information. Running Vitess processes get most of their topology data from the
- local instance.
-
-This separation is key to higher reliability. A single cell going bad is never
-critical for Vitess, as the global instance is configured to survive it, and
-other cells can take over the production traffic. The global instance can be
-unavailable for minutes and not affect serving at all (it would affect VSchema
-changes for instance, but these are not critical, they can wait for the global
-instance to be back).
-
-If Vitess is only running in one cell, both global and local instances can share
-the same lock service instance. It is always possible to split them later when
-expanding to multiple cells.
-
-## Monitoring
-
-The most stressful part of running a production system is the situation where one is trying to troubleshoot an ongoing outage. You have to be able to get to the root cause quickly and find the correct remedy. This is one area where monitoring becomes critical and Vitess has been battle-tested. A large number of internal state variables and counters are continuously exported by Vitess through the /debug/vars and other URLs. There’s also work underway to integrate with third party monitoring tools like Prometheus.
-
-Vitess errs on the side of over-reporting, but you can be picky about which of these variables you want to monitor. It’s important and recommended to plot graphs of this data because it’s easy to spot the timing and magnitude of a change. It’s also essential to set up various threshold-based alerts that can be used to proactively prevent outages.
-
-## Development workflow
-
-Vitess provides binaries and scripts to make unit testing of the application
-code very easy. With these tools, we recommend to unit test all the application
-features if possible.
-
-A production environment for a Vitess cluster involves a topology service,
-multiple database instances, a vtgate pool and at least one vtctld process,
-possibly in multiple data centers. The vttest library uses the *vtcombo* binary
-to combine all the Vitess processes into just one. The various databases are
-also combined into a single MySQL instance (using different database names for
-each shard). The database schema is initialized at startup. The (optional)
-VSchema is also initialized at startup.
-
-A few things to consider:
-
-* Use the same database schema in tests as the production schema.
-* Use the same VSchema in tests as the production VSchema.
-* When a production keyspace is sharded, use a sharded test keyspace as
- well. Just two shards is usually enough, to minimize test startup time, while
- still re-producing the production environment.
-* *vtcombo* can also start the *vtctld* component, so the test environment is
- visible with the Vitess UI.
-* See
- [vttest.proto](https://github.com/vitessio/vitess/blob/master/proto/vttest.proto)
- for more information.
-
-## Application query patterns
-
-Although Vitess strives to minimize the app changes required to scale,
-there are some important considerations for application queries.
-
-### Commands specific to single MySQL instances
-
-Since vitess represents a combined view of all MySQL instances, there
-are some operations it cannot reasonably perform in a backward compatible
-manner. For example:
-
-* SET GLOBAL
-* SHOW
-* Binary log commands
-* Other single keyspace administrative commands
-
-However, Vitess allows you to target a single MySQL instance through
-an extended syntax of the USE statement. If so, it will
-allow you to execute some of these statements as pass-through.
-
-### Connecting to Vitess
-
-If your application previously connected to master or replica
-instances through different hosts and ports, those parts will
-have to be changed to connect to a single load-balanced IP.
-
-Instead, the database type will be specified as part of the
-db name. For example, to connect to a master, you would specify
-the dbname as db@master. For a replica, it would be
-db@replica.
-
-### Query support
-
-A sharded Vitess is not 100% backward compatible with MySQL.
-Some queries that used to work will cease to work.
-It’s important that you run all your queries on a sharded test environment -- see the [Development workflow](#development-workflow) section above -- to make sure none will fail on production.
-
-Our goal is to expand query support based on the needs of users.
-If you encounter an important construct that isn't supported,
-please create or comment on an existing feature request so we
-know how to prioritize.
diff --git a/doc/ScalingMySQL.md b/doc/ScalingMySQL.md
deleted file mode 100644
index deef192c8b3..00000000000
--- a/doc/ScalingMySQL.md
+++ /dev/null
@@ -1,143 +0,0 @@
-Traditionally, it's been difficult to scale a MySQL-based database to an arbitrary size. Since MySQL lacks the out-of-the-box multi-instance support required to really scale an application, the process can be complex and obscure.
-
-As the application grows, scripts emerge to back up data, migrate a master database, or run some offline data processing. Complexity creeps into the application layer, which increasingly needs to be aware of database details. And before we know it, any change needs a big engineering effort so we can keep scaling.
-
-Vitess grew out of YouTube's attempt to break this cycle, and YouTube decided to open source Vitess after realizing that this is a very common problem. Vitess simplifies every aspect of managing a MySQL cluster, allowing easy scaling to any size without complicating your application layer. It ensures your database can keep up when your application takes off, leaving you with a database that is flexible, secure, and easy to mine.
-
-This document talks about the process of moving from a single small database to a limitless database cluster. It explains how steps in that process influenced Vitess' design, linking to relevant parts of the Vitess documentation along the way. It concludes with tips for designing a new, highly scalable application and database schema.
-
-## Getting started
-
-Vitess sits between your application and your MySQL database. It looks at incoming queries and routes them properly. So, instead of sending a query directly from your application to your database, you send it through Vitess, which understands your database topology and constantly monitors the health of individual database instances.
-
-While Vitess is designed to manage large, multi-instance databases, it offers features that simplify database setup and management at all stages of your product's lifecycle.
-
-Starting out, our first step is getting a simple, reliable, durable database cluster in place with a master instance and a couple of replicas. In Vitess terminology, that's a single-shard, single-keyspace database. Once that building block is in place, we can focus on scaling it up.
-
-### Planning for scale
-
-We recommend a number of best practices to facilitate scaling your database as your product evolves. You might not experience the benefits of these actions immediately, but adopting these practices from day one will make it much easier for your database and product to grow:
-
-* Always keep your database schema under source control and provide unit test coverage of that schema. Also check schema changes into source control and run unit tests against the newly modified schema.
-* Think about code paths that can read from a replica vs. always choosing to read from the master. This will let you to scale your reads by just adding more replicas. Additionally, this will make it easy to expand into other data centers across the world.
-* Avoid complicated data relationships. Although RDBMS systems can handle them very well, such relationships hinder scaling in the future. When the time comes, it will be easier to shard the data.
-* Avoid pushing too much logic into the database in the form of stored procedures, foreign keys, or triggers. Such operations overly tax the database and hinder scaling.
-
-## Step 1: Setting up a database cluster
-
-At the outset, plan to create a database cluster that has a master instance and a couple of read-only replicas (or slaves). The replicas would be able to take over if the master became unavailable, and they might also handle read-only traffic. You'd also want to schedule regular data backups.
-
-It's worth noting that master management is a complex and critical challenge for data reliability. At any given time, a shard has only one master instance, and all replica instances replicate from it. Your application -- either a component in your application layer or Vitess, if you are using it -- needs to be able to easily identify the master instance for write operations, recognizing that the master might change from time to time. Similarly, your application, with or without Vitess, should be able to seamlessly adapt to new replicas coming online or old ones being unavailable.
-
-### Keep routing logic out of your application
-
-A core principle underlying Vitess' design is that your database and data management practices should always be ready to support your application's growth. So, you might not yet have an immediate need to store data in multiple data centers, shard your database, or even do regular backups. But when those needs arise, you want to be sure that you'll have an easy path to achieve them. Note that you can run Vitess in a Kubernetes cluster or on local hardware.
-
-With that in mind, you want to have a plan that allows your database to grow without complicating your application code. For example, if you reshard your database, your application code shouldn't need to change to identify the target shards for a particular query.
-
-Vitess has several components that keep this complexity out of your application:
-
-* Each MySQL instance is paired with a **vttablet** process, which provides features like connection pooling, query rewriting, and query de-duping.
-* Your application sends queries to **vtgate**, a light proxy that routes traffic to the correct vttablet(s) and then returns consolidated results to the application.
-* The **Topology Service** -- Vitess supports Zookeeper, etcd and Consul -- maintains configuration data for the database system. Vitess relies on the service to know where to route queries based on both the sharding scheme and the availability of individual MySQL instances.
-* The **vtctl** and **vtctld** tools offer command-line and web interfaces to the system.
-
-
-
-
-
-
-Setting up these components directly -- for example, writing your own topology service or your own implementation of vtgate -- would require a lot of scripting specific to a given configuration. It would also yield a system that would be difficult and costly to support. In addition, while any one of the components on its own is useful in limiting complexity, you need all of them to keep your application as simple as possible while also optimizing performance.
-
-**Optional functionality to implement**
-
-* *Recommended*. Vitess has basic support for identifying or changing a master, but it doesn't aim to fully address this feature. As such, we recommend using another program, like [Orchestrator](https://github.com/github/orchestrator), to monitor the health of your servers and to change your master database when necessary. (In a sharded database, each shard has a master.)
-
-
-* *Recommended*. You should have a way to monitor your database topology and set up alerts as needed. Vitess components facilitate this monitoring by exporting a lot of runtime variables, like QPS over the last few minutes, error rates, and query latency. The variables are exported in JSON format, and Vitess also supports a Prometheus plug-in.
-
-
-* *Optional*. Using the Kubernetes scripts as a base, you could run Vitess components with other configuration management systems (like Puppet) or frameworks (like Mesos or AWS images).
-
-**Related Vitess documentation:**
-
-* [Running Vitess on Kubernetes]({% link getting-started/index.md %})
-* [Running Vitess on a local server]({% link getting-started/local-instance.md %})
-* [Backing up data]({% link user-guide/backup-and-restore.md %})
-* [Reparenting - basic assignment of master instance in Vitess]({% link user-guide/reparenting.md %})
-
-## Step 2: Connect your application to your database
-
-Obviously, your application needs to be able to call your database. So, we'll jump straight to explaining how you'd modify your application to connect to your database through vtgate.
-
-As of Release 2.1, VTGate supports the MySQL protocol. So, the application only needs to change where it connects to. For those using Java or Go, we additionally provide libraries that can communicate to VTGate using [gRPC](https://www.grpc.io/). Using the provided libraries allow you to send queries with bind variables, which is not inherently possible through the MySQL protocol.
-
-#### Unit testing database interactions
-
-The vttest library and executables provide a unit testing environment that lets you start a fake cluster that acts as an exact replica of your production environment for testing purposes. In the fake cluster, a single DB instance hosts all of your shards.
-
-### Migrating production data to Vitess
-
-The easiest way to migrate data to your Vitess database is to take a backup of your existing data, restore it on the Vitess cluster, and go from there. However, that requires some downtime.
-
-Another, more complicated approach, is a live migration, which requires your application to support both direct MySQL access and Vitess access. In that approach, you'd enable MySQL replication from your source database to the Vitess master database. This would allow you to migrate quickly and with almost no downtime.
-
-Note that this path is highly dependent on the source setup. Thus, while Vitess provides helper tools, it does not offer a generic way to support this type of migration.
-
-The final option is to deploy Vitess directly onto the existing MySQL instances and slowly migrate the application traffic to move over to using Vitess.
-
-**Related Vitess documentation:**
-
-* [Schema Management]({% link user-guide/schema-management.md %})
-* [Transport Security Model]({% link user-guide/transport-security-model.md %})
-
-## Step 3: Vertical sharding (scaling to multiple keyspaces)
-
-Typically, the first step in scaling up is vertical sharding, in which you identify groups of tables that belong together and move them to separate keyspaces. A keyspace is a distributed database, and, usually, the databases are unsharded at this point. That said, it's possible that you'll need to horizontally shard your data (step 4) before scaling to multiple keyspaces.
-
-The benefit of splitting tables into multiple keyspaces is to parallelize access to the data (increased performance), and to prepare each smaller keyspace for horizontal sharding. And, in separating data into multiple keyspaces, you should aim to reach a point where:
-
-* All tables inside a keyspace share a common key. This will make it more convenient to horizontally shard in the future as described in step 4.
-* Joins are primarily within keyspaces. (Joins between keyspaces are costly.)
-* Transactions involving data in multiple keyspaces, which are also expensive, are uncommon.
-
-### Scaling keyspaces with Vitess
-
-Several vtctl functions -- vtctl is Vitess' command-line tool for managing your database topology -- support features for vertically splitting a keyspace. In this process, a set of tables can be moved from an existing keyspace to a new keyspace with no read downtime and write downtime of just a few seconds.
-
-**Related Vitess documentation:**
-
-* [vtctl Reference guide]({% link reference/vtctl.md %})
-
-## Step 4: Horizontal sharding (partitioning your data)
-
-The next step in scaling your data is horizontal sharding, the process of partitioning your data to improve scalability and performance. A shard is a horizontal partition of the data within a keyspace. Each shard has a master instance and replica instances, but data does not overlap between shards.
-
-In order to perform horizontal sharding, you need to identify the column that will be used to decide the target shard for each table. This is known as the Primary Vindex, which is similar to a NoSQL sharding key, but provides additional flexibility. The decision on such primary vindexes and other sharding metadata is stored in the VSchema.
-
-Vitess offers robust resharding support, which involves updating the sharding scheme for a keyspace and dynamically reorganizing data to match the new scheme. During resharding, Vitess copies, verifies, and keeps data up-to-date on new shards while existing shards continue serving live read and write traffic. When you're ready to switch over, the migration occurs with just a few seconds of read-only downtime.
-
-**Related Vitess documentation:**
-
-* [VSchema Reference guide]({% link user-guide/vschema.md %})
-* [Sharding]({% link user-guide/sharding.md %})
-* [Horizontal sharding (Codelab)]({% link user-guide/horizontal-sharding.md %})
-* [Sharding in Kubernetes (Codelab)]({% link user-guide/sharding-kubernetes.md %})
-
-## Related tasks
-
-In addition to the four steps discussed above, you might also want to do some or all of the following as your application matures.
-
-### Data processing input / output
-
-Hadoop is a framework that enables distributed processing of large data sets across clusters of computers using simple programming models.
-
-Vitess provides a Hadoop InputSource that can be used for any Hadoop MapReduce job or even connected to Spark. The Vitess InputSource takes a simple SQL query, splits that query into small chunks, and parallelizes data reading as much as possible across database instances, shards, etc.
-
-### Query log analysis
-
-Database query logs can help you to monitor and improve your application's performance.
-
-To that end, each vttablet instance provides runtime stats, which can be accessed through the tablet’s web page, for the queries the tablet is running. These stats make it easy to detect slow queries, which are usually hampered by a missing or mismatched table index. Reviewing these queries regularly helps maintain the overall health of your large database installation.
-
-Each vttablet instance can also provide a stream of all the queries it is running. If the Vitess cluster is colocated with a log cluster, you can dump this data in real time and then run more advanced query analysis.
diff --git a/doc/SchemaManagement.md b/doc/SchemaManagement.md
deleted file mode 100644
index 701bc603658..00000000000
--- a/doc/SchemaManagement.md
+++ /dev/null
@@ -1,190 +0,0 @@
-Using Vitess requires you to work with two different types of schemas:
-
-1. The MySQL database schema. This is the schema of the individual MySQL instances.
-2. The [VSchema]({% link user-guide/vschema.md %}), which describes all the keyspaces and how they're sharded.
-
-The workflow for the VSchema is as follows:
-
-1. Apply the VSchema for each keyspace using the ApplyVschema command. This saves the VSchemas in the global topo server.
-2. Execute RebuildVSchemaGraph for each cell (or all cells). This command propagates a denormalized version of the combined VSchema to all the specified cells. The main purpose for this propagation is to minimize the dependency of each cell from the global topology. The ability to push a change to only specific cells allows you to canary the change to make sure that it's good before deploying it everywhere.
-
-This document describes the [vtctl]({% link reference/vtctl.md %})
-commands that you can use to [review](#reviewing-your-schema) or
-[update](#changing-your-schema) your schema in Vitess.
-
-Note that this functionality is not recommended for long-running schema changes. In such cases, we recommend to do a [schema swap]({% link user-guide/schema-swap.md %}) instead.
-
-## Reviewing your schema
-
-This section describes the following vtctl commands, which let you look at the schema and validate its consistency across tablets or shards:
-
-* [GetSchema](#getschema)
-* [ValidateSchemaShard](#validateschemashard)
-* [ValidateSchemaKeyspace](#validateschemakeyspace)
-* [GetVSchema](#getvschema)
-* [GetSrvVSchema](#getsrvvschema)
-
-### GetSchema
-
-The [GetSchema]({% link reference/vtctl.md %}#getschema) command
-displays the full schema for a tablet or a subset of the tablet's tables.
-When you call GetSchema, you specify the tablet alias that
-uniquely identifies the tablet. The \
-argument value has the format \-\.
-
-**Note:** You can use the
-[vtctl ListAllTablets]({% link reference/vtctl.md %}#listalltablets)
-command to retrieve a list of tablets in a cell and their unique IDs.
-
-The following example retrieves the schema for the tablet with the
-unique ID test-000000100:
-
-```
-GetSchema test-000000100
-```
-
-### ValidateSchemaShard
-
-The
-[ValidateSchemaShard]({% link reference/vtctl.md %}#validateschemashard)
-command confirms that for a given keyspace, all of the slave tablets
-in a specified shard have the same schema as the master tablet in that
-shard. When you call ValidateSchemaShard, you specify both
-the keyspace and the shard that you are validating.
-
-The following command confirms that the master and slave tablets in
-shard 0 all have the same schema for the user
-keyspace:
-
-```
-ValidateSchemaShard user/0
-```
-
-### ValidateSchemaKeyspace
-
-The [ValidateSchemaKeyspace]({% link reference/vtctl.md %}#validateschemakeyspace)
-command confirms that all of the tablets in a given keyspace have
-the same schema as the master tablet on shard 0
-in that keyspace. Thus, whereas the ValidateSchemaShard
-command confirms the consistency of the schema on tablets within a shard
-for a given keyspace, ValidateSchemaKeyspace confirms the
-consistency across all tablets in all shards for that keyspace.
-
-The following command confirms that all tablets in all shards have the
-same schema as the master tablet in shard 0 for the
-user keyspace:
-
-```
-ValidateSchemaKeyspace user
-```
-
-### GetVSchema
-
-The [GetVSchema]({% link reference/vtctl.md %}#getvschema)
-command displays the global VSchema for the specified keyspace.
-
-### GetSrvVSchema
-
-The [GetSrvVSchema]({% link reference/vtctl.md %}#getsrvvschema)
-command displays the combined VSchema for a given cell.
-
-## Changing your schema
-
-This section describes the following commands:
-
-* [ApplySchema](#applyschema)
-* [ApplyVSchema](#applyvschema)
-* [RebuildVSchemaGraph](#rebuildvschemagraph)
-
-### ApplySchema
-
-Vitess' schema modification functionality is designed the following goals in mind:
-
-* Enable simple updates that propagate to your entire fleet of servers.
-* Require minimal human interaction.
-* Minimize errors by testing changes against a temporary database.
-* Guarantee very little downtime (or no downtime) for most schema updates.
-* Do not store permanent schema data in the topology server.
-
-Note that, at this time, Vitess only supports
-[data definition statements](https://dev.mysql.com/doc/refman/5.6/en/sql-syntax-data-definition.html)
-that create, modify, or delete database tables.
-For instance, ApplySchema does not affect stored procedures
-or grants.
-
-The [ApplySchema]({% link reference/vtctl.md %}#applyschema)
-command applies a schema change to the specified keyspace on every
-master tablet, running in parallel on all shards. Changes are then
-propagated to slaves via replication. The command format is:
-```
-ApplySchema {-sql= || -sql_file=}
-```
-
-When the ApplySchema action actually applies a schema
-change to the specified keyspace, it performs the following steps:
-
-1. It finds shards that belong to the keyspace, including newly added
- shards if a [resharding event]({% link user-guide/sharding.md %}#resharding)
- has taken place.
-1. It validates the SQL syntax and determines the impact of the schema
- change. If the scope of the change is too large, Vitess rejects it.
- See the [permitted schema changes](#permitted-schema-changes) section
- for more detail.
-1. It employs a pre-flight check to ensure that a schema update will
- succeed before the change is actually applied to the live database.
- In this stage, Vitess copies the current schema into a temporary
- database, applies the change there to validate it, and retrieves
- the resulting schema. By doing so, Vitess verifies that the change
- succeeds without actually touching live database tables.
-1. It applies the SQL command on the master tablet in each shard.
-
-The following sample command applies the SQL in the **user_table.sql**
-file to the **user** keyspace:
-
-```
-ApplySchema -sql_file=user_table.sql user
-```
-
-#### Permitted schema changes
-
-The ApplySchema command supports a limited set of DDL
-statements. In addition, Vitess rejects some schema changes because
-large changes can slow replication and may reduce the availability
-of your overall system.
-
-The following list identifies types of DDL statements that Vitess
-supports:
-
-* CREATE TABLE
-* CREATE INDEX
-* CREATE VIEW
-* ALTER TABLE
-* ALTER VIEW
-* RENAME TABLE
-* DROP TABLE
-* DROP INDEX
-* DROP VIEW
-
-In addition, Vitess applies the following rules when assessing the
-impact of a potential change:
-
-* DROP statements are always allowed, regardless of the
- table's size.
-* ALTER statements are only allowed if the table on the
- shard's master tablet has 100,000 rows or less.
-* For all other statements, the table on the shard's master tablet
- must have 2 million rows or less.
-
-If a schema change gets rejected because it affects too many rows, you can specify the flag `-allow_long_unavailability` to tell `ApplySchema` to skip this check.
-However, we do not recommend this. Instead, you should apply large schema changes by following the [schema swap process]({% link user-guide/schema-swap.md %}).
-
-### ApplyVSchema
-
-The [ApplyVSchema]({% link reference/vtctl.md %}#applyvschema)
-command applies the specified VSchema to the keyspace. The VSchema can be specified
-as a string or in a file.
-
-### RebuildVSchemaGraph
-
-The [RebuildVSchemaGraph]({% link reference/vtctl.md %}#rebuildvschemagraph)
-command propagates the global VSchema to a specific cell or the list of specified cells.
diff --git a/doc/SchemaSwap.md b/doc/SchemaSwap.md
deleted file mode 100644
index a893761464d..00000000000
--- a/doc/SchemaSwap.md
+++ /dev/null
@@ -1,87 +0,0 @@
-# Schema Swap: A Tutorial
-
-This page describes how to apply long-running schema changes in Vitess/MySQL
-without disrupting ongoing operations. Examples for long-running changes on
-large databases are `ALTER TABLE` (for example to add a column), `OPTIMIZE
-TABLE` or large-scale data changes (e.g. populating a column or clearing out
-values).
-
-If a schema change is not long-running, please use the simpler [vtctl
-ApplySchema]({% link user-guide/schema-management.md %}) instead.
-
-## Overview
-
-One solution to realize such long-running schema changes is to use a temporary
-table and keep it in sync with triggers as [originally proposed by
-Shlomi](https://code.openark.org/blog/mysql/online-alter-table-now-available-in-openark-kit)
-and further refined by others ([Percona's
-pt-online-schema-change](https://www.percona.com/doc/percona-toolkit/2.2/pt-online-schema-change.html),
-[Square's Shift](https://github.com/square/shift)).
-
-Here we describe an alternative solution which uses a combination of MySQL's
-statement based replication and backups to apply the changes to all tablets.
-Since the long-running schema changes are applied to an offline tablet, ongoing
-operations are not affected. We called this process **schema swap** due to the
-way it's done, and therefore we refer to it by this name throughout the
-document.
-
-This tutorial outlines the necessary steps for a schema swap and is based on the
-[Vitess Kubernetes Getting Started Guide]({% link getting-started/index.md %}).
-
-**At the high level, a schema swap comprises the following phases:**
-
-1. Apply the schema changes to an offline tablet.
-1. Let the tablet catch up and then create a backup of it.
-1. Restore all remaining tablets (excluding the master) from the backup.
-1. Failover the master to a replica tablet which has the new schema. Restore
- the old master from the backup.
-1. At this point, all tablets have the new schema and you can start using it.
-
-**You may be wondering: Why does this work?**
-
-The key here is that the new schema is backward compatible with respect to
-statements sent by the app. The replication stream remains backward compatible
-as well because we use statement based replication. As a consequence, the new
-schema must not be used until it has been changed on all tablets. If the schema
-would have been used e.g. when an insert uses a new column, replication would
-break on tablets which have the old schema. Swapping schema on all tablets first
-ensures this doesn't happen.
-
-Also note that the changes are applied to only one tablet and then all other
-tablets are restored from the backup. This is more efficient than applying the
-long-running changes on every single tablet.
-
-Now let's carry out an actual schema swap based on our Guestbook example schema.
-We'll add a column to it.
-
-## Prerequisites
-
-We assume that you have followed the [Vitess Kubernetes Getting Started
-Guide]({% link getting-started/index.md %}) up to and including the step "9.
-Create a table".
-
-## Schema Swap Steps
-
-1. Got to the Workflows section of vtctld UI (it will be at
- http://localhost:8001/api/v1/proxy/namespaces/default/services/vtctld:web/app2/workflows
- if you followed the Getting Started Guide as is) and press the "+" button in
- the top right corner. You will be presented with "Create a new Workflow"
- dialog.
-1. In the "Factory Name" list select "Schema Swap".
-1. In the field "Keyspace" enter "test_keyspace" (without quotes).
-1. In the field "SQL" enter the statement representing the schema change you
- want to execute. As an example we want to execute statement "ALTER TABLE
- messages ADD views BIGINT(20) UNSIGNED NULL".
-1. Click "Create" button at the bottom of the dialog.
-
-Another way to start the schema swap is to execute vtctlclient command:
-
-``` sh
-vitess/examples/local$ ./lvtctl.sh WorkflowCreate schema_swap -keyspace=test_keyspace -sql='SQL statement'
-```
-
-From this point on all you need to do is watch how the schema swap process is
-progressing. Try expanding the displayed nodes in vtctld UI and look at the logs
-of all the actions that process is doing. Once the UI shows "Schema swap is
-finished" you can start using the new schema, it will be propagated to all
-tablets.
diff --git a/doc/ServerConfiguration.md b/doc/ServerConfiguration.md
deleted file mode 100644
index 737757ae726..00000000000
--- a/doc/ServerConfiguration.md
+++ /dev/null
@@ -1,684 +0,0 @@
-## MySQL
-
-Vitess has some requirements on how MySQL should be configured. These will be detailed below.
-
-As a reminder, semi-sync replication is highly recommended. It offers a much better durability story than relying on a disk. This will also let you relax the disk-based durability settings.
-
-### Versions
-
-MySQL versions supported are: MariaDB 10.0, MySQL 5.6 and MySQL 5.7. A number of custom versions based on these exist (Percona, …), Vitess most likely supports them if the version they are based on is supported.
-
-### Config files
-
-#### my.cnf
-
-The main `my.cnf` file is generated by
-[mysqlctl init](https://github.com/vitessio/vitess/blob/312064b96ac0070d9f8990e57af6f2c0a76a45a9/examples/local/vttablet-up.sh#L66)
-based primarily on
-[$VTROOT/config/mycnf/default.cnf](https://github.com/vitessio/vitess/blob/master/config/mycnf/default.cnf).
-Additional files will be appended to the generated `my.cnf` as specified in
-a colon-separated list of absolute paths in the `EXTRA_MY_CNF` environment
-variable. For example, this is typically used to include [flavor-specific
-config files](https://github.com/vitessio/vitess/blob/312064b96ac0070d9f8990e57af6f2c0a76a45a9/examples/local/vttablet-up.sh#L41).
-
-To customize the `my.cnf`, you can either add overrides in an additional
-`EXTRA_MY_CNF` file, or modify the files in `$VTROOT/config/mycnf` before
-distributing to your servers. In Kubernetes, you can use a
-[ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) to overwrite
-the entire `$VTROOT/config/mycnf` directory with your custom versions,
-rather than baking them into a custom container image.
-
-#### init_db.sql
-
-When a new instance is initialized with `mysqlctl init` (as opposed to
-restarting in a previously initialized data dir with `mysqlctl start`),
-the [init_db.sql](https://github.com/vitessio/vitess/blob/master/config/init_db.sql)
-file is applied to the server immediately after executing `mysql_install_db`.
-By default, this file contains the equivalent of running
-[mysql_secure_installation](https://dev.mysql.com/doc/refman/5.7/en/mysql-secure-installation.html),
-as well as the necessary tables and grants for Vitess.
-
-If you are running Vitess on top of an existing MySQL instance,
-rather than using mysqlctl, you can use this file as a sample of what
-grants need to be applied to enable Vitess.
-
-Note that changes to this file will not be reflected in shards that have
-already been initialized and had at least one backup taken.
-New instances in such shards will automatically restore the latest backup
-upon vttablet startup, overwriting the data dir created by mysqlctl.
-
-### Statement-based replication (SBR)
-
-Vitess relies on adding comments to DMLs, which are later parsed on the other end of replication for various post-processing work. The critical ones are:
-
-* Redirect DMLs to the correct shard during resharding workflow.
-* Identify which rows have changed for notifying downstream services that wish to subscribe to changes in vitess.
-* Workflows that allow you to apply schema changes to replicas first, and rotate the masters, which improves uptime.
-
-In order to achieve this, Vitess also rewrites all your DMLs to be primary-key based. In a way, this also makes statement based replication almost as efficient as row-based replication (RBR). So, there should be no major loss of performance if you switched to SBR in Vitess.
-
-In Vitess 2.2 preliminary support for Row Based Replication (RBR) was added. See [this document]({% link user-guide/row-based-replication.md %}) for more information.
-
-### Data types
-
-Vitess supports all data types including newer data types like spatial and JSON. Additionally, the TIMESTAMP data type should not be used in a primary key or sharding column. Otherwise, Vitess cannot predict those values correctly and this may result in data corruption.
-
-### No side effects
-
-Vitess cannot guarantee data consistency if the schema contains constructs with side effects. These are triggers, stored procedures and foreign keys. This is because the resharding workflow and update stream cannot correctly detect what has changed by looking at a statement.
-
-This rule is not strictly enforced. You are allowed to add these things, but at your own risk. As long as you’ve ensured that a certain side-effect will not break Vitess, you can add it to the schema.
-
-Similar guidelines should be used when deciding to bypass Vitess to send statements directly to MySQL.
-
-Vitess also requires you to turn on STRICT_TRANS_TABLES or STRICT_ALL_TABLES mode. Otherwise, it cannot accurately predict what will be written to the database.
-
-It’s safe to apply backward compatible DDLs directly to MySQL. VTTablets can be configured to periodically check the schema for changes.
-
-There is also work in progress to actively watch the binlog for schema changes. This will likely happen around release 2.1.
-
-### Autocommit
-
-MySQL autocommit needs to be turned on.
-
-VTTablet uses connection pools to MySQL. If autocommit was turned off, MySQL will start an implicit transaction (with a point in time snapshot) for each connection and will work very hard at keeping the current view unchanged, which would be counter-productive.
-
-### Safe startup
-
-We recommend to enable `read-only` and `skip-slave-start` at startup.
-The first ensures that writes will not be accepted accidentally,
-which could cause split brain or alternate futures.
-The second ensures that slaves do not connect to the master before
-settings like semisync are initialized by vttablet according to
-Vitess-specific logic.
-
-
-### Binary logging
-
-By default, we enable binary logging everywhere (`log-bin`),
-including on slaves (`log-slave-updates`).
-On *replica* type tablets, this is important to make sure they have the
-necessary binlogs in case they are promoted to master.
-The slave binlogs are also used to implement Vitess features like
-filtered replication (during resharding) and the upcoming update stream
-and online schema swap.
-
-### Global Transaction ID (GTID)
-
-Many features of Vitess require a fully GTID-based MySQL replication
-topology, including master management, resharding, update stream,
-and online schema swap.
-
-For MySQL 5.6+, that means you must use `gtid_mode=ON` on all servers.
-We also strongly encourage `enforce_gtid_consistency`.
-
-Similarly, for MariaDB, you should use `gtid_strict_mode` to ensure that
-master management operations will fail rather than risk causing data loss
-if slaves diverge from the master due to external interference.
-
-### Monitoring
-
-In addition to monitoring the Vitess processes, we recommend to monitor MySQL as well. Here is a list of MySQL metrics you should monitor:
-
-* QPS
-* Bytes sent/received
-* Replication lag
-* Threads running
-* Innodb buffer cache hit rate
-* CPU, memory and disk usage. For disk, break into bytes read/written, latencies and IOPS.
-
-### Recap
-
-* 2-4 cores
-* 100-300GB data size
-* Statement based replication (required)
-* Semi-sync replication
- * rpl_semi_sync_master_timeout is huge (essentially never; there's no way to actually specify never)
- * rpl_semi_sync_master_wait_no_slave = 1
- * sync_binlog=0
- * innodb_flush_log_at_trx_commit=2
-* STRICT_TRANS_TABLES
-* auto-commit ON (required)
-* Additional parameters as mentioned in above sections.
-
-## Vitess servers
-
-Vitess servers are written in Go. There are a few Vitess-specific knobs that apply to all servers.
-
-### Go version
-
-Go, being a young language, tends to add major improvements over each version.
-So, the latest Go version is almost always recommended.
-Note that the latest Go version may be higher than the minimum version we require for compiling the binaries (see ["Prerequisites" section in the Getting Started guide](https://github.com/vitessio/website/blob/master/content/docs/tutorials/kubernetes.md#prerequisites)).
-
-### GOMAXPROCS
-
-You typically don’t have to set this environment variable. The default Go runtime will try to use as much CPU as necessary. However, if you want to force a Go server to not exceed a certain CPU limit, setting GOMAXPROCS to that value will work in most situations.
-
-### GOGC
-
-The default value for this variable is 100. Which means that garbage is collected every time memory doubles from the baseline (100% growth). You typically don’t have to change this value either. However, if you care about tail latency, increasing this value will help you in that area, but at the cost of increased memory usage.
-
-### Logging
-
-Vitess servers write to log files, and they are rotated when they reach a maximum size. It’s recommended that you run at INFO level logging. The information printed in the log files come in handy for troubleshooting. You can limit the disk usage by running cron jobs that periodically purge or archive them.
-
-### gRPC
-
-Vitess uses gRPC for communication between client and Vitess, and between Vitess
-servers. By default, Vitess does not use SSL.
-
-Also, even without using SSL, we allow the use of an application-provided
-CallerID object. It allows unsecure but easy to use authorization using Table
-ACLs.
-
-See the
-[Transport Security Model document]({% link user-guide/transport-security-model.md %})
-for more information on how to setup both of these features, and what command
-line parameters exist.
-
-## Topology Service configuration
-
-Vttablet, vtgate, vtctld need the right command line parameters to find the
-Topology Server. First the *topo\_implementation* flag needs to be set to one of
-*zk2*, *etcd2*, or *consul*. Then they're all configured as follows:
-
-* The *topo_global_server_address* contains the server address / addresses of
- the global topology server.
-* The *topo_global_root* contains the directory / path to use.
-
-Note that the local cell for the tablet must exist and be configured properly in
-the Topology Service for vttablet to start. Local cells are configured inside
-the topo server, by using the `vtctl AddCellInfo` command. See
-the [Topology Service]({% link user-guide/topology-service.md %}) documentation for more
-information.
-
-## VTTablet
-
-
-
-VTTablet has a large number of command line options. Some important ones will be covered here. In terms of provisioning these are the recommended values
-
-* 2-4 cores (in proportion to MySQL cores)
-* 2-4 GB RAM
-
-### Directory Configuration
-
-vttablet supports a number of command line options and environment variables
-to facilitate its setup.
-
-The **VTDATAROOT** environment variable specifies the toplevel directory for all
-data files. If not set, it defaults to `/vt`.
-
-By default, a vttablet will use a subdirectory in **VTDATAROOT** named
-`vt_NNNNNNNNNN` where `NNNNNNNNNN` is the tablet id. The **tablet_dir**
-command-line parameter allows overriding this relative path. This is useful in
-containers where the filesystem only contains one vttablet, in order to have a
-fixed root directory.
-
-When starting up and using `mysqlctl` to manage MySQL, the MySQL files will be
-in subdirectories of the tablet root. For instance, `bin-logs` for the binary
-logs, `data` for the data files, and `relay-logs` for the relay logs.
-
-It is possible to host different parts of a MySQL server files on different
-partitions. For instance, the data file may reside in flash, while the bin logs
-and relay logs are on spindle. To achieve this, create a symlink from
-`$VTDATAROOT/` to the proper location on disk. When MySQL is
-configured by mysqlctl, it will realize this directory exists, and use it for the
-files it would otherwise have put in the tablet directory. For instance, to host
-the binlogs in `/mnt/bin-logs`:
-
-* Create a symlink from `$VTDATAROOT/bin-logs` to `/mnt/bin-logs`.
-
-* When starting up a tablet:
-
- * `/mnt/bin-logs/vt_NNNNNNNNNN` will be created.
-
- * `$VTDATAROOT/vt_NNNNNNNNNN/bin-logs` will be a symlink to
- `/mnt/bin-logs/vt_NNNNNNNNNN`
-
-### Initialization
-
-* Init_keyspace, init_shard, init_tablet_type: These parameters should be set at startup with the keyspace / shard / tablet type to start the tablet as. Note ‘master’ is not allowed here, instead use ‘replica’, as the tablet when starting will figure out if it is the master (this way, all replica tablets start with the same command line parameters, independently of which one is the master).
-
-### Query server parameters
-
-
-
-* **queryserver-config-pool-size**: This value should typically be set to the max number of simultaneous queries you want MySQL to run. This should typically be around 2-3x the number of allocated CPUs. Around 4-16. There is not much harm in going higher with this value, but you may see no additional benefits.
-* **queryserver-config-stream-pool-size**: This value is relevant only if you plan to run streaming queries against the database. It’s recommended that you use rdonly instances for such streaming queries. This value depends on how many simultaneous streaming queries you plan to run. Typical values are in the low 100s.
-* **queryserver-config-transaction-cap**: This value should be set to how many concurrent transactions you wish to allow. This should be a function of transaction QPS and transaction length. Typical values are in the low 100s.
-* **queryserver-config-query-timeout**: This value should be set to the upper limit you’re willing to allow a query to run before it’s deemed too expensive or detrimental to the rest of the system. VTTablet will kill any query that exceeds this timeout. This value is usually around 15-30s.
-* **queryserver-config-transaction-timeout**: This value is meant to protect the situation where a client has crashed without completing a transaction. Typical value for this timeout is 30s.
-* **queryserver-config-max-result-size**: This parameter prevents the OLTP application from accidentally requesting too many rows. If the result exceeds the specified number of rows, VTTablet returns an error. The default value is 10,000.
-
-### DB config parameters
-
-VTTablet requires multiple user credentials to perform its tasks. Since it's required to run on the same machine as MySQL, it’s most beneficial to use the more efficient unix socket connections.
-
-**connection** parameters
-
-* **db\_socket**: The unix socket to connect on. If this is specified, host and port will not be used.
-* **db\_host**: The host name for the tcp connection.
-* **db\_port**: The tcp port to be used with the db\_host.
-* **db\_charset**: Character set. Only utf8 or latin1 based character sets are supported.
-* **db\_flags**: Flag values as defined by MySQL.
-* **db\ssl\_ca, db\_ssl\_ca\_path, db\_ssl\_cert, db\_ssl\_key**: SSL flags.
-
-
-**app** credentials are for serving app queries:
-
-* **db\_app\_user**: App username.
-* **db\_app\_password**: Password for the app username. If you need a more secure way of managing and supplying passwords, VTTablet does allow you to plug into a "password server" that can securely supply and refresh usernames and passwords. Please contact the Vitess team for help if you’d like to write such a custom plugin.
-* **db\_app\_use\_ssl**: Set this flag to false if you don't want to use SSL for this connection. This will allow you to turn off SSL for all users except for `repl`, which may have to be turned on for replication that goes over open networks.
-
-**appdebug** credentials are for the appdebug user:
-
-* **db\_appdebug\_user**
-* **db\_appdebug\_password**
-* **db\_appdebug\_use\_ssl**
-
-**dba** credentials will be used for housekeeping work like loading the schema or killing runaway queries:
-
-* **db\_dba\_user**
-* **db\_dba\_password**
-* **db\_dba\_use\_ssl**
-
-**repl** credentials are for managing replication.
-
-* **db\_repl\_user**
-* **db\_repl\_password**
-* **db\_repl\_use\_ssl**
-
-**filtered** credentials are for performing resharding:
-
-* **db\_filtered\_user**
-* **db\_filtered\_password**
-* **db\_filtered\_use\_ssl**
-
-### Monitoring
-
-VTTablet exports a wealth of real-time information about itself. This section will explain the essential ones:
-
-#### /debug/status
-
-This page has a variety of human-readable information about the current VTTablet. You can look at this page to get a general overview of what’s going on. It also has links to various other diagnostic URLs below.
-
-#### /debug/vars
-
-This is the most important source of information for monitoring. There are other URLs below that can be used to further drill down.
-
-##### Queries (as described in /debug/vars section)
-
-Vitess has a structured way of exporting certain performance stats. The most common one is the Histogram structure, which is used by Queries:
-
-```
- "Queries": {
- "Histograms": {
- "PASS_SELECT": {
- "1000000": 1138196,
- "10000000": 1138313,
- "100000000": 1138342,
- "1000000000": 1138342,
- "10000000000": 1138342,
- "500000": 1133195,
- "5000000": 1138277,
- "50000000": 1138342,
- "500000000": 1138342,
- "5000000000": 1138342,
- "Count": 1138342,
- "Time": 387710449887,
- "inf": 1138342
- }
- },
- "TotalCount": 1138342,
- "TotalTime": 387710449887
- },
-```
-
-The histograms are broken out into query categories. In the above case, "PASS_SELECT" is the only category. An entry like `"500000": 1133195` means that `1133195` queries took under `500000` nanoseconds to execute.
-
-Queries.Histograms.PASS_SELECT.Count is the total count in the PASS_SELECT category.
-
-Queries.Histograms.PASS_SELECT.Time is the total time in the PASS_SELECT category.
-
-Queries.TotalCount is the total count across all categories.
-
-Queries.TotalTime is the total time across all categories.
-
-There are other Histogram variables described below, and they will always have the same structure.
-
-Use this variable to track:
-
-* QPS
-* Latency
-* Per-category QPS. For replicas, the only category will be PASS_SELECT, but there will be more for masters.
-* Per-category latency
-* Per-category tail latency
-
-##### Results
-
-```
- "Results": {
- "0": 0,
- "1": 0,
- "10": 1138326,
- "100": 1138326,
- "1000": 1138342,
- "10000": 1138342,
- "5": 1138326,
- "50": 1138326,
- "500": 1138342,
- "5000": 1138342,
- "Count": 1138342,
- "Total": 1140438,
- "inf": 1138342
- }
-```
-
-Results is a simple histogram with no timing info. It gives you a histogram view of the number of rows returned per query.
-
-##### Mysql
-
-Mysql is a histogram variable like Queries, except that it reports MySQL execution times. The categories are "Exec" and “ExecStream”.
-
-In the past, the exec time difference between VTTablet and MySQL used to be substantial. With the newer versions of Go, the VTTablet exec time has been predominantly been equal to the mysql exec time, conn pool wait time and consolidations waits. In other words, this variable has not shown much value recently. However, it’s good to track this variable initially, until it’s determined that there are no other factors causing a big difference between MySQL performance and VTTablet performance.
-
-##### Transactions
-
-Transactions is a histogram variable that tracks transactions. The categories are "Completed" and “Aborted”.
-
-##### Waits
-
-Waits is a histogram variable that tracks various waits in the system. Right now, the only category is "Consolidations". A consolidation happens when one query waits for the results of an identical query already executing, thereby saving the database from performing duplicate work.
-
-This variable used to report connection pool waits, but a refactor moved those variables out into the pool related vars.
-
-##### Errors
-
-```
- "Errors": {
- "Deadlock": 0,
- "Fail": 1,
- "NotInTx": 0,
- "TxPoolFull": 0
- },
-```
-
-Errors are reported under different categories. It’s beneficial to track each category separately as it will be more helpful for troubleshooting. Right now, there are four categories. The category list may vary as Vitess evolves.
-
-Plotting errors/query can sometimes be useful for troubleshooting.
-
-VTTablet also exports an InfoErrors variable that tracks inconsequential errors that don’t signify any kind of problem with the system. For example, a dup key on insert is considered normal because apps tend to use that error to instead update an existing row. So, no monitoring is needed for that variable.
-
-##### InternalErrors
-
-```
- "InternalErrors": {
- "HungQuery": 0,
- "Invalidation": 0,
- "MemcacheStats": 0,
- "Mismatch": 0,
- "Panic": 0,
- "Schema": 0,
- "StrayTransactions": 0,
- "Task": 0
- },
-```
-
-An internal error is an unexpected situation in code that may possibly point to a bug. Such errors may not cause outages, but even a single error needs be escalated for root cause analysis.
-
-##### Kills
-
-```
- "Kills": {
- "Queries": 2,
- "Transactions": 0
- },
-```
-
-Kills reports the queries and transactions killed by VTTablet due to timeout. It’s a very important variable to look at during outages.
-
-##### TransactionPool*
-
-There are a few variables with the above prefix:
-
-```
- "TransactionPoolAvailable": 300,
- "TransactionPoolCapacity": 300,
- "TransactionPoolIdleTimeout": 600000000000,
- "TransactionPoolMaxCap": 300,
- "TransactionPoolTimeout": 30000000000,
- "TransactionPoolWaitCount": 0,
- "TransactionPoolWaitTime": 0,
-```
-
-* WaitCount will give you how often the transaction pool gets full that causes new transactions to wait.
-* WaitTime/WaitCount will tell you the average wait time.
-* Available is a gauge that tells you the number of available connections in the pool in real-time. Capacity-Available is the number of connections in use. Note that this number could be misleading if the traffic is spiky.
-
-##### Other Pool variables
-
-Just like TransactionPool, there are variables for other pools:
-
-* ConnPool: This is the pool used for read traffic.
-* StreamConnPool: This is the pool used for streaming queries.
-
-There are other internal pools used by VTTablet that are not very consequential.
-
-##### TableACLAllowed, TableACLDenied, TableACLPseudoDenied
-
-The above three variables table acl stats broken out by table, plan and user.
-
-##### QueryPlanCacheSize
-
-If the application does not make good use of bind variables, this value would reach the QueryCacheCapacity. If so, inspecting the current query cache will give you a clue about where the misuse is happening.
-
-##### QueryCounts, QueryErrorCounts, QueryRowCounts, QueryTimesNs
-
-These variables are another multi-dimensional view of Queries. They have a lot more data than Queries because they’re broken out into tables as well as plan. This is a priceless source of information when it comes to troubleshooting. If an outage is related to rogue queries, the graphs plotted from these vars will immediately show the table on which such queries are run. After that, a quick look at the detailed query stats will most likely identify the culprit.
-
-##### UserTableQueryCount, UserTableQueryTimesNs, UserTransactionCount, UserTransactionTimesNs
-
-These variables are yet another view of Queries, but broken out by user, table and plan. If you have well-compartmentalized app users, this is another priceless way of identifying a rogue "user app" that could be misbehaving.
-
-##### DataFree, DataLength, IndexLength, TableRows
-
-These variables are updated periodically from information_schema.tables. They represent statistical information as reported by MySQL about each table. They can be used for planning purposes, or to track unusual changes in table stats.
-
-* DataFree represents data_free
-* DataLength represents data_length
-* IndexLength represents index_length
-* TableRows represents table_rows
-
-#### /debug/health
-
-This URL prints out a simple "ok" or “not ok” string that can be used to check if the server is healthy. The health check makes sure mysqld connections work, and replication is configured (though not necessarily running) if not master.
-
-#### /queryz, /debug/query_stats, /debug/query_plans, /streamqueryz
-
-* /debug/query_stats is a JSON view of the per-query stats. This information is pulled in real-time from the query cache. The per-table stats in /debug/vars are a roll-up of this information.
-* /queryz is a human-readable version of /debug/query_stats. If a graph shows a table as a possible source of problems, this is the next place to look at to see if a specific query is the root cause.
-* /debug/query_plans is a more static view of the query cache. It just shows how VTTablet will process or rewrite the input query.
-* /streamqueryz lists the currently running streaming queries. You have the option to kill any of them from this page.
-
-#### /querylogz, /debug/querylog, /txlogz, /debug/txlog
-
-* /debug/querylog is a never-ending stream of currently executing queries with verbose information about each query. This URL can generate a lot of data because it streams every query processed by VTTablet. The details are as per this function: [https://github.com/vitessio/vitess/tree/master/go/vt/vttablet/tabletserver/tabletenv/logstats.go#L202](https://github.com/vitessio/vitess/tree/master/go/vt/vttablet/tabletserver/tabletenv/logstats.go#L202)
-* /querylogz is a limited human readable version of /debug/querylog. It prints the next 300 queries by default. The limit can be specified with a limit=N parameter on the URL.
-* /txlogz is like /querylogz, but for transactions.
-* /debug/txlog is the JSON counterpart to /txlogz.
-
-#### /consolidations
-
-This URL has an MRU list of consolidations. This is a way of identifying if multiple clients are spamming the same query to a server.
-
-#### /schemaz, /debug/schema
-
-* /schemaz shows the schema info loaded by VTTablet.
-* /debug/schema is the JSON version of /schemaz.
-
-#### /debug/query_rules
-
-This URL displays the currently active query blacklist rules.
-
-### Alerting
-
-Alerting is built on top of the variables you monitor. Before setting up alerts, you should get some baseline stats and variance, and then you can build meaningful alerting rules. You can use the following list as a guideline to build your own:
-
-* Query latency among all vttablets
-* Per keyspace latency
-* Errors/query
-* Memory usage
-* Unhealthy for too long
-* Too many vttablets down
-* Health has been flapping
-* Transaction pool full error rate
-* Any internal error
-* Traffic out of balance among replicas
-* Qps/core too high
-
-## VTGate
-
-A typical VTGate should be provisioned as follows.
-
-* 2-4 cores
-* 2-4 GB RAM
-
-Since VTGate is stateless, you can scale it linearly by just adding more servers as needed. Beyond the recommended values, it’s better to add more VTGates than giving more resources to existing servers, as recommended in the philosophy section.
-
-Load-balancer in front of vtgate to scale up (not covered by Vitess). Stateless, can use the health URL for health check.
-
-### Parameters
-
-* **cells_to_watch**: which cell vtgate is in and will monitor tablets from. Cross-cell master access needs multiple cells here.
-* **keyspaces_to_watch**: Specifies that a vtgate will only be able to perform queries against or view the topology of these keyspaces
-* **tablet_types_to_wait**: VTGate waits for at least one serving tablet per tablet type specified here during startup, before listening to the serving port. So VTGate does not serve error. It should match the available tablet types VTGate connects to (master, replica, rdonly).
-* **discovery_low_replication_lag**: when replication lags of all VTTablet in a particular shard and tablet type are less than or equal the flag (in seconds), VTGate does not filter them by replication lag and uses all to balance traffic.
-* **degraded_threshold (30s)**: a tablet will publish itself as degraded if replication lag exceeds this threshold. This will cause VTGates to choose more up-to-date servers over this one. If all servers are degraded, VTGate resorts to serving from all of them.
-* **unhealthy_threshold (2h)**: a tablet will publish itself as unhealthy if replication lag exceeds this threshold.
-* **transaction_mode (multi)**: `single`: disallow multi-db transactions, `multi`: allow multi-db transactions with best effort commit, `twopc`: allow multi-db transactions with 2pc commit.
-* **normalize_queries (false)**: Turning this flag on will cause vtgate to rewrite queries with bind vars. This is beneficial if the app doesn't itself send normalized queries.
-
-### Monitoring
-
-#### /debug/status
-
-This is the landing page for a VTGate, which can gives you a status on how a particular server is doing. Of particular interest there is the list of tablets this vtgate process is connected to, as this is the list of tablets that can potentially serve queries.
-
-#### /debug/vars
-
-##### VTGateApi
-
-This is the main histogram variable to track for vtgates. It gives you a break up of all queries by command, keyspace, and type.
-
-##### HealthcheckConnections
-
-It shows the number of tablet connections for query/healthcheck per keyspace, shard, and tablet type.
-
-#### /debug/query_plans
-
-This URL gives you all the query plans for queries going through VTGate.
-
-#### /debug/vschema
-
-This URL shows the vschema as loaded by VTGate.
-
-### Alerting
-
-For VTGate, here’s a list of possible variables to alert on:
-
-* Error rate
-* Error/query rate
-* Error/query/tablet-type rate
-* VTGate serving graph is stale by x minutes (lock server is down)
-* Qps/core
-* Latency
-
-
-
-## External processes
-
-Things that need to be configured:
-
-### Periodic backup configuration
-
-We recommend to take backups regularly e.g. you should set up a cron job for it. See our recommendations at [{% link user-guide/backup-and-restore.md %}#backup-frequency]({% link user-guide/backup-and-restore.md %}#backup-frequency).
-
-### Logs archiver/purger
-
-You will need to run some cron jobs to archive or purge log files periodically.
-
-### Orchestrator
-
-[Orchestrator](https://github.com/github/orchestrator) is a tool for
-managing MySQL replication topologies, including automated failover.
-It can detect master failure and initiate a recovery in a matter of seconds.
-
-For the most part, Vitess is agnostic to the actions of Orchestrator,
-which operates below Vitess at the MySQL level. That means you can
-pretty much
-[set up Orchestrator](https://github.com/github/orchestrator/wiki/Orchestrator-Manual)
-in the normal way, with just a few additions as described below.
-
-For the [Kubernetes example](https://github.com/vitessio/website/blob/master/content/docs/tutorials/kubernetes.md), we provide a
-[sample script](https://github.com/vitessio/vitess/blob/master/examples/kubernetes/orchestrator-up.sh)
-to launch Orchestrator for you with these settings applied.
-
-#### Orchestrator configuration
-
-Orchestrator needs to know some things from the Vitess side,
-like the tablet aliases and whether semisync is enforced
-(with async fallback disabled).
-We pass this information by telling Orchestrator to execute certain
-queries that return local metadata from a non-replicated table,
-as seen in our sample
-[orchestrator.conf.json](https://github.com/vitessio/vitess/blob/master/docker/orchestrator/orchestrator.conf.json):
-
-```json
- "DetectClusterAliasQuery": "SELECT value FROM _vt.local_metadata WHERE name='ClusterAlias'",
- "DetectInstanceAliasQuery": "SELECT value FROM _vt.local_metadata WHERE name='Alias'",
- "DetectPromotionRuleQuery": "SELECT value FROM _vt.local_metadata WHERE name='PromotionRule'",
- "DetectSemiSyncEnforcedQuery": "SELECT @@global.rpl_semi_sync_master_wait_no_slave AND @@global.rpl_semi_sync_master_timeout > 1000000",
-```
-
-There is also one thing that Vitess needs to know from Orchestrator,
-which is the identity of the master for each shard, if a failover occurs.
-
-From our experience at YouTube, we believe that this signal is too critical
-for data integrity to rely on bottom-up detection such as asking each MySQL
-if it thinks it's the master. Instead, we rely on Orchestrator to be the
-source of truth, and expect it to send a top-down signal to Vitess.
-
-This signal is sent by ensuring the Orchestrator server has access to
-`vtctlclient`, which it then uses to send an RPC to vtctld, informing
-Vitess of the change in mastership via the
-[TabletExternallyReparented]({% link reference/vtctl.md %}#tabletexternallyreparented)
-command.
-
-```json
- "PostMasterFailoverProcesses": [
- "echo 'Recovered from {failureType} on {failureCluster}. Failed: {failedHost}:{failedPort}; Promoted: {successorHost}:{successorPort}' >> /tmp/recovery.log",
- "vtctlclient -server vtctld:15999 TabletExternallyReparented {successorAlias}"
- ],
-```
-
-#### VTTablet configuration
-
-Normally, you need to seed Orchestrator by giving it the addresses of
-MySQL instances in each shard. If you have lots of shards, this could
-be tedious or error-prone.
-
-Luckily, Vitess already knows everything about all the MySQL instances
-that comprise your cluster. So we provide a mechanism for tablets to
-self-register with the Orchestrator API, configured by the following
-vttablet parameters:
-
-* **orc_api_url**: Address of Orchestrator's HTTP API (e.g. http://host:port/api/). Leave empty to disable Orchestrator integration.
-* **orc_discover_interval**: How often (e.g. 60s) to ping Orchestrator's HTTP API endpoint to tell it we exist. 0 means never.
-
-Not only does this relieve you from the initial seeding of addresses into
-Orchestrator, it also means new instances will be discovered immediately,
-and the topology will automatically repopulate even if Orchestrator's
-backing store is wiped out. Note that Orchestrator will forget stale
-instances after a configurable timeout.
diff --git a/doc/Sharding.md b/doc/Sharding.md
deleted file mode 100644
index 1ab77855db7..00000000000
--- a/doc/Sharding.md
+++ /dev/null
@@ -1,187 +0,0 @@
-Sharding is a method of horizontally partitioning a database to store
-data across two or more database servers. This document explains how
-sharding works in Vitess and the types of sharding that Vitess supports.
-
-## Overview
-
-A keyspace in Vitess can be sharded or unsharded. An unsharded keyspace
-maps directly to a MySQL database. If sharded, the rows of the keyspace
-are partitioned into different databases of identical schema.
-
-For example, if an application's "user" keyspace is split into two
-shards, each shard contains records for approximately half of the
-application's users. Similarly, each user's information is stored
-in only one shard.
-
-Note that sharding is orthogonal to (MySQL) replication.
-A Vitess shard typically contains one MySQL master and many MySQL
-slaves. The master handles write operations, while slaves handle
-read-only traffic, batch processing operations, and other tasks.
-Each MySQL instance within the shard should have the same data,
-excepting some replication lag.
-
-### Supported Operations
-
-Vitess supports the following types of sharding operations:
-
-* **Horizontal sharding:** Splitting or merging shards in a sharded keyspace
-* **Vertical sharding:** Moving tables from an unsharded keyspace to
- a different keyspace.
-
-With these features, you can start with a single keyspace that contains
-all of your data (in multiple tables). As your database grows, you can
-move tables to different keyspaces (vertical split) and shard some or
-all of those keyspaces (horizontal split) without any real downtime
-for your application.
-
-## Sharding scheme
-
-Vitess allows you to choose the type of sharding scheme by the choice of
-your Primary Vindex for the tables of a shard. Once you have chosen
-the Primary Vindex, you can choose the partitions depending on how the
-resulting keyspace IDs are distributed.
-
-Vitess calculates the sharding key or keys for each query and then
-routes that query to the appropriate shards. For example, a query
-that updates information about a particular user might be directed to
-a single shard in the application's "user" keyspace. On the other hand,
-a query that retrieves information about several products might be
-directed to one or more shards in the application's "product" keyspace.
-
-### Key Ranges and Partitions
-
-Vitess uses key ranges to determine which shards should handle any
-particular query.
-
-* A **key range** is a series of consecutive keyspace ID values. It
- has starting and ending values. A key falls inside the range if
- it is equal to or greater than the start value and strictly less
- than the end value.
-* A **partition** represents a set of key ranges that covers the entire
- space.
-
-When building the serving graph for a sharded keyspace,
-Vitess ensures that each shard is valid and that the shards
-collectively constitute a full partition. In each keyspace, one shard
-must have a key range with an empty start value and one shard, which
-could be the same shard, must have a key range with an empty end value.
-
-* An empty start value represents the lowest value, and all values are
- greater than it.
-* An empty end value represents a value larger than the highest possible
- value, and all values are strictly lower than it.
-
-Vitess always converts sharding keys to a left-justified binary string for
-computing a shard. This left-justification makes the right-most zeroes
-insignificant and optional. Therefore, the value 0x80 is
-always the middle value for sharding keys.
-So, in a keyspace with two shards, sharding keys that have a binary
-value lower than 0x80 are assigned to one shard. Keys with a binary
-value equal to or higher than 0x80 are assigned to the other shard.
-
-Several sample key ranges are shown below:
-
-``` sh
-Start=[], End=[]: Full Key Range
-Start=[], End=[0x80]: Lower half of the Key Range.
-Start=[0x80], End=[]: Upper half of the Key Range.
-Start=[0x40], End=[0x80]: Second quarter of the Key Range.
-Start=[0xFF00], End=[0xFF80]: Second to last 1/512th of the Key Range.
-```
-
-Two key ranges are consecutive if the end value of one range equals the
-start value of the other range.
-
-### Shard Names
-
-A shard's name identifies the start
-and end of the shard's key range, printed in hexadecimal and separated
-by a hyphen. For instance, if a shard's key range is the array of bytes
-beginning with [ 0x80 ] and ending, noninclusively, with [ 0xc0], then
-the shard's name is 80-c0.
-
-Using this naming convention, the following four shards would be a valid
-full partition:
-
-* -40
-* 40-80
-* 80-c0
-* c0-
-
-Shards do not need to handle the same size portion of the key space. For example, the following five shards would also be a valid full partition, possibly with a highly uneven distribution of keys.
-
-* -80
-* 80-c0
-* c0-dc00
-* dc00-dc80
-* dc80-
-
-## Resharding
-
-Resharding describes the process of updating the sharding
-scheme for a keyspace and dynamically reorganizing data to match the
-new scheme. During resharding, Vitess copies, verifies, and keeps
-data up-to-date on new shards while the existing shards continue to
-serve live read and write traffic. When you're ready to switch over,
-the migration occurs with only a few seconds of read-only downtime.
-During that time, existing data can be read, but new data cannot be
-written.
-
-The table below lists the sharding (or resharding) processes that you
-would typically perform for different types of requirements:
-
-Requirement | Action
------------ | ------
-Uniformly increase read capacity | Add replicas or split shards
-Uniformly increase write capacity | Split shards
-Reclaim overprovisioned resources | Merge shards and/or keyspaces
-Increase geo-diversity | Add new cells and replicas
-Cool a hot tablet | For read access, add replicas or split shards. For write access, split shards.
-
-### Filtered Replication
-
-The cornerstone of resharding is replicating the right data. Vitess
-implements the following functions to support filtered replication,
-the process that ensures that the correct source tablet data is
-transferred to the proper destination tablets.
-
-#### Statement-based Replication
-
-If you've configured the MySQL servers to use Statement-based Replication (SBR),
-then Vitess must be able to identify the destination for such statements during
-the filtered replication process. This performed the following way:
-
-1. The source tablet tags transactions with comments so that MySQL binlogs
- contain the filtering data needed during the resharding process. The
- comments describe the scope of each transaction (its keyspace ID,
- table, etc.).
-1. A server process uses the comments to filter the MySQL binlogs and
- stream the correct data to the destination tablet.
-1. A client process on the destination tablet applies the filtered logs,
- which are just regular SQL statements at this point.
-
-#### Row-based Replication
-
-If MySQL is configured to use Row-based Replication (RBR), the filtered replication
-is performed the following way:
-
-1. The server process uses the primary vindex to compute the keyspace ID for every
- row coming throug the replication stream, and sends that row to the corresponding
- target shard.
-1. The target shard converts the row into the corresponding DML (Data Manipulation Language)
- and applies the statement.
-
-If using RBR, it's generally required that you have full image turned on. However, if your
-Primary Vindex is also part of the Primary key, it's not required, because every RBR event
-will always contain the full primary key of its affected row.
-
-### Additional Tools and Processes
-
-Vitess provides the following tools to help manage range-based shards:
-
-* The [vtctl]({% link reference/vtctl.md %}) command-line tool supports
- functions for managing keyspaces, shards, tablets, and more.
-* Client APIs account for sharding operations.
-* The [MapReduce framework](https://github.com/vitessio/vitess/tree/master/java/hadoop/src/main/java/io/vitess/hadoop)
- fully utilizes key ranges to read data as quickly as possible,
- concurrently from all shards and all replicas.
diff --git a/doc/ShardingKubernetes.md b/doc/ShardingKubernetes.md
deleted file mode 100644
index 2181b2e004c..00000000000
--- a/doc/ShardingKubernetes.md
+++ /dev/null
@@ -1,286 +0,0 @@
-This guide walks you through the process of sharding an existing unsharded
-Vitess [keyspace]({% link overview/concepts.md %}#keyspace) in
-[Kubernetes](https://kubernetes.io/).
-
-## Prerequisites
-
-We begin by assuming you've completed the
-[Getting Started on Kubernetes]({% link getting-started/index.md %}) guide, and
-have left the cluster running.
-
-## Overview
-
-We will follow a process similar to the one in the general
-[Horizontal Sharding]({% link user-guide/horizontal-sharding.md %})
-guide, except that here we'll give the commands you'll need to do it for
-the example Vitess cluster in Kubernetes.
-
-Since Vitess makes [sharding]({% link user-guide/sharding.md %})
-transparent to the app layer, the
-[Guestbook](https://github.com/vitessio/vitess/tree/master/examples/kubernetes/guestbook)
-sample app will stay live throughout the
-[resharding]({% link user-guide/sharding.md %}#resharding) process,
-confirming that the Vitess cluster continues to serve without downtime.
-
-## Configure sharding information
-
-The first step is to tell Vitess how we want to partition the data.
-We do this by providing a VSchema definition as follows:
-
-``` json
-{
- "sharded": true,
- "vindexes": {
- "hash": {
- "type": "hash"
- }
- },
- "tables": {
- "messages": {
- "column_vindexes": [
- {
- "column": "page",
- "name": "hash"
- }
- ]
- }
- }
-}
-```
-
-This says that we want to shard the data by a hash of the `page` column.
-In other words, keep each page's messages together, but spread pages around
-the shards randomly.
-
-We can load this VSchema into Vitess like this:
-
-``` sh
-vitess/examples/kubernetes$ ./kvtctl.sh ApplyVSchema -vschema "$(cat vschema.json)" test_keyspace
-```
-
-## Bring up tablets for new shards
-
-In the unsharded example, you started tablets for a shard
-named *0* in *test_keyspace*, written as *test_keyspace/0*.
-Now you'll start tablets for two additional shards,
-named *test_keyspace/-80* and *test_keyspace/80-*:
-
-``` sh
-vitess/examples/kubernetes$ ./sharded-vttablet-up.sh
-### example output:
-# Creating test_keyspace.shard--80 pods in cell test...
-# ...
-# Creating test_keyspace.shard-80- pods in cell test...
-# ...
-```
-
-Since the sharding key in the Guestbook app is the page number,
-this will result in half the pages going to each shard,
-since *0x80* is the midpoint of the
-[sharding key range]({% link user-guide/sharding.md %}#key-ranges-and-partitions).
-
-These new shards will run in parallel with the original shard during the
-transition, but actual traffic will be served only by the original shard
-until we tell it to switch over.
-
-Check the `vtctld` web UI, or the output of `kvtctl.sh ListAllTablets test`,
-to see when the tablets are ready. There should be 5 tablets in each shard.
-
-Once the tablets are ready, initialize replication by electing the first master
-for each of the new shards:
-
-``` sh
-vitess/examples/kubernetes$ ./kvtctl.sh InitShardMaster -force test_keyspace/-80 test-0000000200
-vitess/examples/kubernetes$ ./kvtctl.sh InitShardMaster -force test_keyspace/80- test-0000000300
-```
-
-Now there should be a total of 15 tablets, with one master for each shard:
-
-``` sh
-vitess/examples/kubernetes$ ./kvtctl.sh ListAllTablets test
-### example output:
-# test-0000000100 test_keyspace 0 master 10.64.3.4:15002 10.64.3.4:3306 []
-# ...
-# test-0000000200 test_keyspace -80 master 10.64.0.7:15002 10.64.0.7:3306 []
-# ...
-# test-0000000300 test_keyspace 80- master 10.64.0.9:15002 10.64.0.9:3306 []
-# ...
-```
-
-## Copy data from original shard
-
-The new tablets start out empty, so we need to copy everything from the
-original shard to the two new ones, starting with the schema:
-
-``` sh
-vitess/examples/kubernetes$ ./kvtctl.sh CopySchemaShard test_keyspace/0 test_keyspace/-80
-vitess/examples/kubernetes$ ./kvtctl.sh CopySchemaShard test_keyspace/0 test_keyspace/80-
-```
-
-Next we copy the data. Since the amount of data to copy can be very large,
-we use a special batch process called *vtworker* to stream the data from a
-single source to multiple destinations, routing each row based on its
-*keyspace_id*:
-
-``` sh
-vitess/examples/kubernetes$ ./sharded-vtworker.sh SplitClone test_keyspace/0
-### example output:
-# Creating vtworker pod in cell test...
-# pods/vtworker
-# Following vtworker logs until termination...
-# I0416 02:08:59.952805 9 instance.go:115] Starting worker...
-# ...
-# State: done
-# Success:
-# messages: copy done, copied 11 rows
-# Deleting vtworker pod...
-# pods/vtworker
-```
-
-Notice that we've only specified the source shard, *test_keyspace/0*.
-The *SplitClone* process will automatically figure out which shards to use
-as the destinations based on the key range that needs to be covered.
-In this case, shard *0* covers the entire range, so it identifies
-*-80* and *80-* as the destination shards, since they combine to cover the
-same range.
-
-Next, it will pause replication on one *rdonly* (offline processing) tablet
-to serve as a consistent snapshot of the data. The app can continue without
-downtime, since live traffic is served by *replica* and *master* tablets,
-which are unaffected. Other batch jobs will also be unaffected, since they
-will be served only by the remaining, un-paused *rdonly* tablets.
-
-## Check filtered replication
-
-Once the copy from the paused snapshot finishes, *vtworker* turns on
-[filtered replication]({% link user-guide/sharding.md %}#filtered-replication)
-from the source shard to each destination shard. This allows the destination
-shards to catch up on updates that have continued to flow in from the app since
-the time of the snapshot.
-
-When the destination shards are caught up, they will continue to replicate
-new updates. You can see this by looking at the contents of each shard as
-you add new messages to various pages in the Guestbook app. Shard *0* will
-see all the messages, while the new shards will only see messages for pages
-that live on that shard.
-
-``` sh
-# See what's on shard test_keyspace/0:
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-0000000100 "SELECT * FROM messages"
-# See what's on shard test_keyspace/-80:
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-0000000200 "SELECT * FROM messages"
-# See what's on shard test_keyspace/80-:
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-0000000300 "SELECT * FROM messages"
-```
-
-Add some messages on various pages of the Guestbook to see how they get routed.
-
-## Check copied data integrity
-
-The *vtworker* batch process has another mode that will compare the source
-and destination to ensure all the data is present and correct.
-The following commands will run a diff for each destination shard:
-
-``` sh
-vitess/examples/kubernetes$ ./sharded-vtworker.sh SplitDiff test_keyspace/-80
-vitess/examples/kubernetes$ ./sharded-vtworker.sh SplitDiff test_keyspace/80-
-```
-
-If any discrepancies are found, they will be printed.
-If everything is good, you should see something like this:
-
-```
-I0416 02:10:56.927313 10 split_diff.go:496] Table messages checks out (4 rows processed, 1072961 qps)
-```
-
-## Switch over to new shards
-
-Now we're ready to switch over to serving from the new shards.
-The [MigrateServedTypes]({% link reference/vtctl.md %}#migrateservedtypes)
-command lets you do this one
-[tablet type]({% link overview/concepts.md %}#tablet) at a time,
-and even one [cell]({% link overview/concepts.md %}#cell-data-center)
-at a time. The process can be rolled back at any point *until* the master is
-switched over.
-
-``` sh
-vitess/examples/kubernetes$ ./kvtctl.sh MigrateServedTypes test_keyspace/0 rdonly
-vitess/examples/kubernetes$ ./kvtctl.sh MigrateServedTypes test_keyspace/0 replica
-vitess/examples/kubernetes$ ./kvtctl.sh MigrateServedTypes test_keyspace/0 master
-```
-
-During the *master* migration, the original shard master will first stop
-accepting updates. Then the process will wait for the new shard masters to
-fully catch up on filtered replication before allowing them to begin serving.
-Since filtered replication has been following along with live updates, there
-should only be a few seconds of master unavailability.
-
-When the master traffic is migrated, the filtered replication will be stopped.
-Data updates will be visible on the new shards, but not on the original shard.
-See it for yourself: Add a message to the guestbook page and then inspect
-the database content:
-
-``` sh
-# See what's on shard test_keyspace/0
-# (no updates visible since we migrated away from it):
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-0000000100 "SELECT * FROM messages"
-# See what's on shard test_keyspace/-80:
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-0000000200 "SELECT * FROM messages"
-# See what's on shard test_keyspace/80-:
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-0000000300 "SELECT * FROM messages"
-```
-
-## Remove original shard
-
-Now that all traffic is being served from the new shards, we can remove the
-original one. To do that, we use the `vttablet-down.sh` script from the
-unsharded example:
-
-``` sh
-vitess/examples/kubernetes$ ./vttablet-down.sh
-### example output:
-# Deleting pod for tablet test-0000000100...
-# pods/vttablet-100
-# ...
-```
-
-Then we can delete the now-empty shard:
-
-``` sh
-vitess/examples/kubernetes$ ./kvtctl.sh DeleteShard -recursive test_keyspace/0
-```
-
-You should then see in the vtctld **Topology** page, or in the output of
-`kvtctl.sh ListAllTablets test` that the tablets for shard *0* are gone.
-
-## Tear down and clean up
-
-Before stopping the Container Engine cluster, you should tear down the Vitess
-services. Kubernetes will then take care of cleaning up any entities it created
-for those services, like external load balancers.
-
-Since you already cleaned up the tablets from the original unsharded example by
-running `./vttablet-down.sh`, that step has been replaced with
-`./sharded-vttablet-down.sh` to clean up the new sharded tablets.
-
-``` sh
-vitess/examples/kubernetes$ ./guestbook-down.sh
-vitess/examples/kubernetes$ ./vtgate-down.sh
-vitess/examples/kubernetes$ ./sharded-vttablet-down.sh
-vitess/examples/kubernetes$ ./vtctld-down.sh
-vitess/examples/kubernetes$ ./etcd-down.sh
-```
-
-Then tear down the Container Engine cluster itself, which will stop the virtual
-machines running on Compute Engine:
-
-``` sh
-$ gcloud container clusters delete example
-```
-
-It's also a good idea to remove the firewall rules you created, unless you plan
-to use them again soon:
-
-``` sh
-$ gcloud compute firewall-rules delete vtctld guestbook
-```
diff --git a/doc/ShardingKubernetesWorkflow.md b/doc/ShardingKubernetesWorkflow.md
deleted file mode 100644
index a428861c9ef..00000000000
--- a/doc/ShardingKubernetesWorkflow.md
+++ /dev/null
@@ -1,222 +0,0 @@
-This guide shows you an example about how to apply range-based sharding
-process in an existing unsharded Vitess [keyspace]({% link overview/concepts.md %}#keyspace)
-in [Kubernetes](https://kubernetes.io/) using the horizontal resharding workflow.
-In this example, we will reshard from 1 shard "0" into 2 shards "-80" and "80-".
-We will follow a process similar to the general
-[Horizontal Sharding guide]({% link user-guide/horizontal-sharding-workflow.md %})
-except that here we'll give you the commands you'll need in the kubernetes
-environment.
-
-## Overview
-
-The horizontal resharding process overview can be found
-[here]({% link user-guide/horizontal-sharding-workflow.md %}#overview)
-
-## Prerequisites
-
-You should complete the [Getting Started on Kubernetes]({% link getting-started/index.md %})
-guide (please finish all the steps before Try Vitess resharding) and have left
-the cluster running. Then, please follow these steps before running the
-resharding process:
-
-1. Configure sharding information. By running the command below, we tell
- Vitess to shard the data using the page column through the provided VSchema.
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh ApplyVSchema -vschema "$(cat vschema.json)" test_keyspace
- ```
-
-1. Bring up tablets for 2 additional shards: *test_keyspace/-80* and
- *test_keyspace/80-* (you can learn more about sharding key range
- [here]({% link user-guide/sharding.md %}#key-ranges-and-partitions)):
-
- ``` sh
- vitess/examples/kubernetes$ ./sharded-vttablet-up.sh
- ```
-
- Initialize replication by electing the first master for each of the new shards:
-
- ``` sh
- vitess/examples/kubernetes$ ./kvtctl.sh InitShardMaster -force test_keyspace/-80 test-200
- vitess/examples/kubernetes$ ./kvtctl.sh InitShardMaster -force test_keyspace/80- test-300
- ```
-
- After this set up, you should see the shards on Dashboard page of vtctld UI
- (http://localhost:8001/api/v1/proxy/namespaces/default/services/vtctld:web).
- There should be 1 serving shard named "0" and 2 non-serving shards named
- "-80" and "80-". Click the shard node, you can inspect all its tablets
- information.
-
-1. Bring up a *vtworker* process (a pod in kubernetes) and a *vtworker* service
- which is used by the workflow to connect with the *vtworker* pod. (The
- number of *vtworker* should be the same of original shards, we start one
- vtworker process here since we have only one original shard in this example.)
-
- ``` sh
- vitess/examples/kubernetes$ ./vtworker-up.sh
- ```
-
- You can check out the external IP for the vtworker service (please take note
- of this external IP, it will be used for the vtworker address in creating
- the resharding workflow):
-
- ``` sh
- $ kubectl get service vtworker
- ```
-
- You can verify this *vtworker* process set up through http://:15032/Debugging.
- It should be pinged successfully. After you ping the vtworker, please click
- "Reset Job". Otherwise, the vtworker is not ready for executing other tasks.
-
-## Horizontal Resharding Workflow
-
-### Create the Workflow
-
-Using the web vtctld UI to create the workflow is the same with [steps in local
-environment]({% link user-guide/horizontal-sharding-workflow.md %}#create-the-workflow)
-except for filling the "vtworker Addresses" slot. You need to get the external
-IP for vtworker service (mentioned in
-[Prerequisites](#prerequisites)) and use
-\:15033 as the vtworker addresses.
-
-Another way to start the workflow is through the vtctlclient command:
-
-``` sh
-vitess/examples/kubernetes$ ./kvtctl.sh WorkflowCreate -skip_start=false horizontal_resharding -keyspace=test_keyspace -vtworkers=:15033 -enable_approvals=true
-```
-
-### Approvals of Tasks Execution (Canary feature)
-
-Please check the content in general
-[Horizontal Sharding guide]({% link user-guide/horizontal-sharding-workflow.md %}#approvals-of-tasks-execution-canary-feature)
-
-### Retry
-
-Please check the content in general
-[Horizontal Sharding guide]({% link user-guide/horizontal-sharding-workflow.md %}#retry)
-
-### Checkpoint and Recovery
-
-Please check the content in general
-[Horizontal Sharding guide]({% link user-guide/horizontal-sharding-workflow.md %}#checkpoint-and-recovery)
-
-## Verify Results and Clean up
-
-After the resharding process, data in the original shard is identically copied
-to new shards. Data updates will be visible on the new shards, but not on the
-original shard. You should then see in the vtctld UI *Dashboard* page that shard
-*0* becomes non-serving and shard *-80* and shard *80-* are serving shards.
-Verify this for yourself: inspect the database content,
-then add messages to the guestbook page and inspect again. You can use
-http://\ (EXTERNAL-IP refers to the external IP of the guest book
-service) to visit the guestbook webpage in your browser and choose any random
-page for inserting information. Details can be found
-[here]({% link getting-started/index.md %}#test-your-cluster-with-a-client-app))
-You can inspect the database content using the following commands:
-
-``` sh
-# See what's on shard test_keyspace/0
-# (no updates visible since we migrated away from it):
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-100 "SELECT * FROM messages"
-# See what's on shard test_keyspace/-80:
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-200 "SELECT * FROM messages"
-# See what's on shard test_keyspace/80-:
-vitess/examples/kubernetes$ ./kvtctl.sh ExecuteFetchAsDba test-300 "SELECT * FROM messages"
-```
-
-You can also checkout the *Topology* browser on vtctl UI. It shows you the
-information of the keyrange of shard and their serving status. Each shard
-should look like this
-
-[shard 0](https://cloud.githubusercontent.com/assets/23492389/24313876/072f61e6-109c-11e7-938a-23b8398958aa.png)
-
-[shard -80](https://cloud.githubusercontent.com/assets/23492389/24313813/bd11c824-109b-11e7-83d4-cca3f6093360.png)
-
-[shard 80-](https://cloud.githubusercontent.com/assets/23492389/24313743/7f9ae1c4-109b-11e7-997a-774f4f16e473.png)
-
-After you verify the result, we can remove the
-original shard since all traffic is being served from the new shards:
-
-``` sh
-vitess/examples/kubernetes$ ./vttablet-down.sh
-```
-
-Then we can delete the now-empty shard:
-
-``` sh
-vitess/examples/local$ ./kvtctl.sh DeleteShard -recursive test_keyspace/0
-```
-
-You should then see in the vtctld UI *Dashboard* page that shard *0* is gone.
-
-## Tear down and Clean up
-
-Since you already cleaned up the tablets from the original unsharded example by
-running `./vttablet-down.sh`, that step has been replaced with
-`./sharded-vttablet-down.sh` to clean up the new sharded tablets.
-
-``` sh
-vitess/examples/kubernetes$ ./guestbook-down.sh
-vitess/examples/kubernetes$ ./vtworker-down.sh
-vitess/examples/kubernetes$ ./vtgate-down.sh
-vitess/examples/kubernetes$ ./sharded-vttablet-down.sh
-vitess/examples/kubernetes$ ./vtctld-down.sh
-vitess/examples/kubernetes$ ./etcd-down.sh
-```
-
-Then tear down the Container Engine cluster itself, which will stop the virtual machines running on Compute Engine:
-
-``` sh
-$ gcloud container clusters delete example
-```
-
-It's also a good idea to remove the firewall rules you created, unless you plan to use them again soon:
-
-``` sh
-$ gcloud compute firewall-rules delete vtctld guestbook
-```
-
-## Reference
-
-You can checkout the old version tutorial [here]({% link user-guide/sharding-kubernetes.md %}).
-It walks you through the resharding process by manually executing commands.
-
-For the kubectl command line interface, which helps you interact with the
-kubernetes cluster, you can check out more information
-[here](https://kubernetes.io/docs/user-guide/kubectl-overview).
-
-## Troubleshooting
-
-### Checking status of your setup.
-
-To get status of pods and services you've setup, you can use the commands
-(all pods should be in Running status, guestbook and vtworker services
-should have assign external IP):
-
-``` sh
-$ kubectl get pods
-$ kubectl get services
-```
-
-### Debugging pods.
-
-If you find out a component (e.g. vttablet, vtgate) doesn't respond as
-expected, you can surface the log using this command (the pod name can be
-found out using the command mentioned above):
-
-``` sh
-$ kubectl logs [-c ]
-### example
-# $ kubectl logs vtworker
-# $ kubectl logs vttablet-XXXX -c vttablet
-```
-
-### Debugging pending external IP issue.
-
-If you found that your service has a pending external IP for long time, it
-maybe because you've reached the limitation of networking resource. Please
-go to your project console on gcloud (cloud.google.com), then go to *Load
-balancing* page (you can search "Load balancing" in the search bar to get
-to the page) under Networking section. Then, click "advanced menu" for
-editing load balancing resources. Check the forwarding rules you have and
-delete the unused ones if there are too many.
diff --git a/doc/TestingOnARamDisk.md b/doc/TestingOnARamDisk.md
deleted file mode 100644
index 1adb82cf273..00000000000
--- a/doc/TestingOnARamDisk.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Testing On A Ramdisk
-
-The `integration_test` testsuite contains tests that may time-out if run against a slow disk. If your workspace lives on hard disk (as opposed to [SSD](https://en.wikipedia.org/wiki/Solid-state_drive)), it is recommended that you run tests using a [ramdisk](https://en.wikipedia.org/wiki/RAM_drive).
-
-# Setup
-
-First, set up a normal vitess development environment by running `bootstrap.sh` and sourcing `dev.env` (see [GettingStarted](GettingStarted.md)). Then overwrite the testing temporary directories and make a 4GiB (smaller sizes may work, if you're constrained on RAM) ramdisk at the location of your choice (this example uses `/tmp/vt`):
-
-```sh
-export VT_TEST_TMPDIR=/tmp/vt
-
-mkdir ${VT_TEST_TMPDIR}
-sudo mount -t tmpfs -o size=4g tmpfs ${VT_TEST_TMPDIR}
-
-export VTDATAROOT=${VT_TEST_TMPDIR}
-export TEST_UNDECLARED_OUTPUTS_DIR=${VT_TEST_TMPDIR}
-```
-
-You can now run tests (either individually or as part of `make test`) normally.
-
-# Teardown
-
-When you are done testing, you can remove the ramdisk by unmounting it and then removing the directory:
-
-```sh
-sudo umount ${VT_TEST_TMPDIR}
-rmdir ${VT_TEST_TMPDIR}
-```
diff --git a/doc/TopologyService.md b/doc/TopologyService.md
deleted file mode 100644
index d4c63348d6a..00000000000
--- a/doc/TopologyService.md
+++ /dev/null
@@ -1,586 +0,0 @@
-# Topology Service
-
-This document describes the Topology Service, a key part of the Vitess
-architecture. This service is exposed to all Vitess processes, and is used to
-store small pieces of configuration data about the Vitess cluster, and provide
-cluster-wide locks. It also supports watches, and master election.
-
-Concretely, the Topology Service features are implemented by
-a [Lock Server](https://en.wikipedia.org/wiki/Distributed_lock_manager), referred
-to as Topology Server in the rest of this document. We use a plug-in
-implementation and we support multiple Lock Servers (Zookeeper, etcd, Consul, …)
-as backends for the service.
-
-## Requirements and usage
-
-The Topology Service is used to store information about the Keyspaces, the
-Shards, the Tablets, the Replication Graph, and the Serving Graph. We store
-small data structures (a few hundred bytes) per object.
-
-The main contract for the Topology Server is to be very highly available and
-consistent. It is understood it will come at a higher latency cost and very low
-throughput.
-
-We never use the Topology Server as an RPC mechanism, nor as a storage system
-for logs. We never depend on the Topology Server being responsive and fast to
-serve every query.
-
-The Topology Server must also support a Watch interface, to signal when certain
-conditions occur on a node. This is used for instance to know when keyspaces
-topology changes (for resharding for instance).
-
-### Global vs local
-
-We differentiate two instances of the Topology Server: the Global instance, and
-the per-cell Local instance:
-
-* The Global instance is used to store global data about the topology that
- doesn’t change very often, for instance information about Keyspaces and
- Shards. The data is independent of individual instances and cells, and needs
- to survive a cell going down entirely.
-* There is one Local instance per cell, that contains cell-specific information,
- and also rolled-up data from the global + local cell to make it easier for
- clients to find the data. The Vitess local processes should not use the Global
- topology instance, but instead the rolled-up data in the Local topology
- server as much as possible.
-
-The Global instance can go down for a while and not impact the local cells (an
-exception to that is if a reparent needs to be processed, it might not work). If
-a Local instance goes down, it only affects the local tablets in that instance
-(and then the cell is usually in bad shape, and should not be used).
-
-Furthermore, the Vitess processes will not use the Global nor the Local Topology
-Server to serve individual queries. They only use the Topology Server to get the
-topology information at startup and in the background, but never to directly
-serve queries.
-
-### Recovery
-
-If a local Topology Server dies and is not recoverable, it can be wiped out. All
-the tablets in that cell then need to be restarted so they re-initialize their
-topology records (but they won’t lose any MySQL data).
-
-If the global Topology Server dies and is not recoverable, this is more of a
-problem. All the Keyspace / Shard objects have to be re-created. Then the cells
-should recover.
-
-## Global data
-
-This section describes the data structures stored in the global instance of the
-topology server.
-
-### Keyspace
-
-The Keyspace object contains various information, mostly about sharding: how is
-this Keyspace sharded, what is the name of the sharding key column, is this
-Keyspace serving data yet, how to split incoming queries, …
-
-An entire Keyspace can be locked. We use this during resharding for instance,
-when we change which Shard is serving what inside a Keyspace. That way we
-guarantee only one operation changes the keyspace data concurrently.
-
-### Shard
-
-A Shard contains a subset of the data for a Keyspace. The Shard record in the
-global topology contains:
-
-* the Master tablet alias for this shard (that has the MySQL master).
-* the sharding key range covered by this Shard inside the Keyspace.
-* the tablet types this Shard is serving (master, replica, batch, …), per cell
- if necessary.
-* if during filtered replication, the source shards this shard is replicating
- from.
-* the list of cells that have tablets in this shard.
-* shard-global tablet controls, like blacklisted tables no tablet should serve
- in this shard.
-
-A Shard can be locked. We use this during operations that affect either the
-Shard record, or multiple tablets within a Shard (like reparenting), so multiple
-jobs don’t concurrently alter the data.
-
-### VSchema data
-
-The VSchema data contains sharding and routing information for
-the [VTGate V3](https://github.com/vitessio/vitess/blob/master/doc/VTGateV3Features.md) API.
-
-## Local data
-
-This section describes the data structures stored in the local instance (per
-cell) of the topology server.
-
-### Tablets
-
-The Tablet record has a lot of information about a single vttablet process
-running inside a tablet (along with the MySQL process):
-
-* the Tablet Alias (cell+unique id) that uniquely identifies the Tablet.
-* the Hostname, IP address and port map of the Tablet.
-* the current Tablet type (master, replica, batch, spare, …).
-* which Keyspace / Shard the tablet is part of.
-* the sharding Key Range served by this Tablet.
-* user-specified tag map (to store per installation data for instance).
-
-A Tablet record is created before a tablet can be running (either by `vtctl
-InitTablet` or by passing the `init_*` parameters to the vttablet process).
-The only way a Tablet record will be updated is one of:
-
-* The vttablet process itself owns the record while it is running, and can
- change it.
-* At init time, before the tablet starts.
-* After shutdown, when the tablet gets deleted.
-* If a tablet becomes unresponsive, it may be forced to spare to make it
- unhealthy when it restarts.
-
-### Replication graph
-
-The Replication Graph allows us to find Tablets in a given Cell / Keyspace /
-Shard. It used to contain information about which Tablet is replicating from
-which other Tablet, but that was too complicated to maintain. Now it is just a
-list of Tablets.
-
-### Serving graph
-
-The Serving Graph is what the clients use to find the per-cell topology of a
-Keyspace. It is a roll-up of global data (Keyspace + Shard). vtgates only open a
-small number of these objects and get all they need quickly.
-
-#### SrvKeyspace
-
-It is the local representation of a Keyspace. It contains information on what
-shard to use for getting to the data (but not information about each individual
-shard):
-
-* the partitions map is keyed by the tablet type (master, replica, batch, …) and
- the values are list of shards to use for serving.
-* it also contains the global Keyspace fields, copied for fast access.
-
-It can be rebuilt by running `vtctl RebuildKeyspaceGraph`. It is
-automatically rebuilt when a tablet starts up in a cell and the SrvKeyspace
-for that cell / keyspace doesn't exist yet. It will also be changed
-during horizontal and vertical splits.
-
-#### SrvVSchema
-
-It is the local roll-up for the VSchema. It contains the VSchema for all
-keyspaces in a single object.
-
-It can be rebuilt by running `vtctl RebuildVSchemaGraph`. It is automatically
-rebuilt when using `vtctl ApplyVSchema` (unless prevented by flags).
-
-## Workflows involving the Topology Server
-
-The Topology Server is involved in many Vitess workflows.
-
-When a Tablet is initialized, we create the Tablet record, and add the Tablet to
-the Replication Graph. If it is the master for a Shard, we update the global
-Shard record as well.
-
-Administration tools need to find the tablets for a given Keyspace / Shard:
-first we get the list of Cells that have Tablets for the Shard (global topology
-Shard record has these) then we use the Replication Graph for that Cell /
-Keyspace / Shard to find all the tablets then we can read each tablet record.
-
-When a Shard is reparented, we need to update the global Shard record with the
-new master alias.
-
-Finding a tablet to serve the data is done in two stages: vtgate maintains a
-health check connection to all possible tablets, and they report which keyspace
-/ shard / tablet type they serve. vtgate also reads the SrvKeyspace object, to
-find out the shard map. With these two pieces of information, vtgate can route
-the query to the right vttablet.
-
-During resharding events, we also change the topology a lot. An horizontal split
-will change the global Shard records, and the local SrvKeyspace records. A
-vertical split will change the global Keyspace records, and the local
-SrvKeyspace records.
-
-## Exploring the data in a Topology Server
-
-We store the proto3 binary data for each object.
-
-We use the following paths for the data, in all implementations:
-
-*Global Cell*:
-
-* CellInfo path: `cells//CellInfo`
-* Keyspace: `keyspaces//Keyspace`
-* Shard: `keyspaces//shards//Shard`
-* VSchema: `keyspaces//VSchema`
-
-*Local Cell*:
-
-* Tablet: `tablets/-/Tablet`
-* Replication Graph: `keyspaces//shards//ShardReplication`
-* SrvKeyspace: `keyspaces//SrvKeyspace`
-* SrvVSchema: `SvrVSchema`
-
-The `vtctl TopoCat` utility can decode these files when using the
-`-decode_proto` option:
-
-``` sh
-TOPOLOGY="-topo_implementation zk2 -topo_global_server_address global_server1,global_server2 -topo_global_root /vitess/global"
-
-$ vtctl $TOPOLOGY TopoCat -decode_proto -long /keyspaces/*/Keyspace
-path=/keyspaces/ks1/Keyspace version=53
-sharding_column_name: "col1"
-path=/keyspaces/ks2/Keyspace version=55
-sharding_column_name: "col2"
-```
-
-The `vtctld` web tool also contains a topology browser (use the `Topology`
-tab on the left side). It will display the various proto files, decoded.
-
-## Implementations
-
-The Topology Server interfaces are defined in our code in `go/vt/topo/`,
-specific implementations are in `go/vt/topo/`, and we also have
-a set of unit tests for it in `go/vt/topo/test`.
-
-This part describes the implementations we have, and their specific
-behavior.
-
-If starting from scratch, please use the `zk2`, `etcd2` or `consul`
-implementations. We deprecated the old `zookeeper` and `etcd`
-implementations. See the migration section below if you want to migrate.
-
-### Zookeeper `zk2` implementation
-
-This is the current implementation when using Zookeeper. (The old `zookeeper`
-implementation is deprecated).
-
-The global cell typically has around 5 servers, distributed one in each
-cell. The local cells typically have 3 or 5 servers, in different server racks /
-sub-networks for higher resilience. For our integration tests, we use a single
-ZK server that serves both global and local cells.
-
-We provide the `zk` utility for easy access to the topology data in
-Zookeeper. It can list, read and write files inside any Zoopeeker server. Just
-specify the `-server` parameter to point to the Zookeeper servers. Note the
-vtctld UI can also be used to see the contents of the topology data.
-
-To configure a Zookeeper installation, let's start with the global cell
-service. It is described by the addresses of the servers (comma separated list),
-and by the root directory to put the Vitess data in. For instance, assuming we
-want to use servers `global_server1,global_server2` in path `/vitess/global`:
-
-``` sh
-# The root directory in the global server will be created
-# automatically, same as when running this command:
-# zk -server global_server1,global_server2 touch -p /vitess/global
-
-# Set the following flags to let Vitess use this global server:
-# -topo_implementation zk2
-# -topo_global_server_address global_server1,global_server2
-# -topo_global_root /vitess/global
-```
-
-Then to add a cell whose local topology servers `cell1_server1,cell1_server2`
-will store their data under the directory `/vitess/cell1`:
-
-``` sh
-TOPOLOGY="-topo_implementation zk2 -topo_global_server_address global_server1,global_server2 -topo_global_root /vitess/global"
-
-# Reference cell1 in the global topology service:
-vtctl $TOPOLOGY AddCellInfo \
- -server_address cell1_server1,cell1_server2 \
- -root /vitess/cell1 \
- cell1
-```
-
-If only one cell is used, the same Zookeeper instance can be used for both
-global and local data. A local cell record still needs to be created, just use
-the same server address, and very importantly a *different* root directory.
-
-[Zookeeper
-Observers](https://zookeeper.apache.org/doc/trunk/zookeeperObservers.html) can
-also be used to limit the load on the global Zookeeper. They are configured by
-specifying the addresses of the observers in the server address, after a `|`,
-for instance:
-`global_server1:p1,global_server2:p2|observer1:po1,observer2:po2`.
-
-#### Implementation details
-
-We use the following paths for Zookeeper specific data, in addition to the
-regular files:
-
-* Locks sub-directory: `locks/` (for instance:
- `keyspaces//Keyspace/locks/` for a keyspace)
-* Master election path: `elections/`
-
-Both locks and master election are implemented using ephemeral, sequential files
-which are stored in their respective directory.
-
-### etcd `etcd2` implementation (new version of `etcd`)
-
-This topology service plugin is meant to use etcd clusters as storage backend
-for the topology data. This topology service supports version 3 and up of the
-etcd server.
-
-This implementation is named `etcd2` because it supersedes our previous
-implementation `etcd`. Note that the storage format has been changed with the
-`etcd2` implementation, i.e. existing data created by the previous `etcd`
-implementation must be migrated manually (See migration section below).
-
-To configure an `etcd2` installation, let's start with the global cell
-service. It is described by the addresses of the servers (comma separated list),
-and by the root directory to put the Vitess data in. For instance, assuming we
-want to use servers `http://global_server1,http://global_server2` in path
-`/vitess/global`:
-
-``` sh
-# Set the following flags to let Vitess use this global server,
-# and simplify the example below:
-# -topo_implementation etcd2
-# -topo_global_server_address http://global_server1,http://global_server2
-# -topo_global_root /vitess/global
-TOPOLOGY="-topo_implementation etcd2 -topo_global_server_address http://global_server1,http://global_server2 -topo_global_root /vitess/global
-```
-
-Then to add a cell whose local topology servers
-`http://cell1_server1,http://cell1_server2` will store their data under the
-directory `/vitess/cell1`:
-
-``` sh
-# Reference cell1 in the global topology service:
-# (the TOPOLOGY variable is defined in the previous section)
-vtctl $TOPOLOGY AddCellInfo \
- -server_address http://cell1_server1,http://cell1_server2 \
- -root /vitess/cell1 \
- cell1
-```
-
-If only one cell is used, the same etcd instances can be used for both
-global and local data. A local cell record still needs to be created, just use
-the same server address and, very importantly, a *different* root directory.
-
-#### Implementation details
-
-For locks, we use a subdirectory named `locks` in the directory to lock, and an
-ephemeral file in that subdirectory (it is associated with a lease, whose TTL
-can be set with the `-topo_etcd_lease_duration` flag, defaults to 30
-seconds). The ephemeral file with the lowest ModRevision has the lock, the
-others wait for files with older ModRevisions to disappear.
-
-Master 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 binary data).
-
-### Consul `consul` implementation
-
-This topology service plugin is meant to use Consul clusters as storage backend
-for the topology data.
-
-To configure a `consul` installation, let's start with the global cell
-service. It is described by the address of a server,
-and by the root node path to put the Vitess data in (it cannot start with `/`). For instance, assuming we
-want to use servers `global_server:global_port` with node path
-`vitess/global`:
-
-``` sh
-# Set the following flags to let Vitess use this global server,
-# and simplify the example below:
-# -topo_implementation consul
-# -topo_global_server_address global_server:global_port
-# -topo_global_root vitess/global
-TOPOLOGY="-topo_implementation consul -topo_global_server_address global_server:global_port -topo_global_root vitess/global
-```
-
-Then to add a cell whose local topology server
-`cell1_server1:cell1_port` will store their data under the
-directory `vitess/cell1`:
-
-``` sh
-# Reference cell1 in the global topology service:
-# (the TOPOLOGY variable is defined in the previous section)
-vtctl $TOPOLOGY AddCellInfo \
- -server_address cell1_server1:cell1_port \
- -root vitess/cell1 \
- cell1
-```
-
-If only one cell is used, the same consul instances can be used for both
-global and local data. A local cell record still needs to be created, just use
-the same server address and, very importantly, a *different* root node path.
-
-#### Implementation details
-
-For locks, we use a file named `Lock` in the directory to lock, and the regular
-Consul Lock API.
-
-Master elections use a single lock file (the Election path) and the regular
-Consul Lock API. The contents of the lock file is the ID of the current master.
-
-Watches use the Consul long polling Get call. They cannot be interrupted, so we
-use a long poll whose duration is set by the
-`-topo_consul_watch_poll_duration` flag. Canceling a watch may have to
-wait until the end of a polling cycle with that duration before returning.
-
-## Running in only one cell
-
-The topology service is meant to be distributed across multiple cells, and
-survive single cell outages. However, one common usage is to run a Vitess
-cluster in only one cell / region. This part explains how to do this, and later
-on upgrade to multiple cells / regions.
-
-If running in a single cell, the same topology service can be used for both
-global and local data. A local cell record still needs to be created, just use
-the same server address and, very importantly, a *different* root node path.
-
-In that case, just running 3 servers for topology service quorum is probably
-sufficient. For instance, 3 etcd servers. And use their address for the local
-cell as well. Let's use a short cell name, like `local`, as the local data in
-that topology server will later on be moved to a different topology service,
-which will have the real cell name.
-
-### Extending to more cells
-
-To then run in multiple cells, the current topology service needs to be split
-into a global instance and one local instance per cell. Whereas, the initial
-setup had 3 topology servers (used for global and local data), we recommend to
-run 5 global servers across all cells (for global topology data) and 3 local
-servers per cell (for per-cell topology data).
-
-To migrate to such a setup, start by adding the 3 local servers in the second
-cell and run `vtctl AddCellinfo` as was done for the first cell. Tablets and
-vtgates can now be started in the second cell, and used normally.
-
-vtgate can then be configured with a list of cells to watch for tablets using
-the `-cells_to_watch` command line parameter. It can then use all tablets in
-all cells to route traffic. Note this is necessary to access the master in
-another cell.
-
-After the extension to two cells, the original topo service contains both the
-global topology data, and the first cell topology data. The more symmetrical
-configuration we're after would be to split that original service into two: a
-global one that only contains the global data (spread across both cells), and a
-local one to the original cells. To achieve that split:
-
-* Start up a new local topology service in that original cell (3 more local
- servers in that cell).
-* Pick a name for that cell, different from `local`.
-* Use `vtctl AddCellInfo` to configure it.
-* Make sure all vtgates can see that new local cell (again, using
- `-cells_to_watch`).
-* Restart all vttablets to be in that new cell, instead of the `local` cell name
- used before.
-* Use `vtctl RemoveKeyspaceCell` to remove all mentions of the `local` cell in
- all keyspaces.
-* Use `vtctl RemoveCellInfo` to remove the global configurations for that
- `local` cell.
-* Remove all remaining data in the global topology service that are in the old
- local server root.
-
-After this split, the configuration is completely symmetrical:
-
-* a global topology service, with servers in all cells. Only contains global
- topology data about Keyspaces, Shards and VSchema. Typically it has 5 servers
- across all cells.
-* a local topology service to each cell, with servers only in that cell. Only
- contains local topology data about Tablets, and roll-ups of global data for
- efficient access. Typically, it has 3 servers in each cell.
-
-## Migration between implementations
-
-We provide the `topo2topo` binary file to migrate between one implementation
-and another of the topology service.
-
-The process to follow in that case is:
-
-* Start from a stable topology, where no resharding or reparenting is on-going.
-* Configure the new topology service so it has at least all the cells of the
- source topology service. Make sure it is running.
-* Run the `topo2topo` program with the right flags. `-from_implementation`,
- `-from_root`, `-from_server` describe the source (old) topology
- service. `-to_implementation`, `-to_root`, `-to_server` describe the
- destination (new) topology service.
-* Run `vtctl RebuildKeyspaceGraph` for each keyspace using the new topology
- service flags.
-* Run `vtctl RebuildVSchemaGraph` using the new topology service flags.
-* Restart all `vtgate` using the new topology service flags. They will see the
- same keyspaces / shards / tablets / vschema as before, as the topology was
- copied over.
-* Restart all `vttablet` using the new topology service flags. They may use the
- same ports or not, but they will update the new topology when they start up,
- and be visible from vtgate.
-* Restart all `vtctld` processes using the new topology service flags. So that
- the UI also shows the new data.
-
-Sample commands to migrate from deprecated `zookeeper` to `zk2`
-topology would be:
-
-``` sh
-# Let's assume the zookeeper client config file is already
-# exported in $ZK_CLIENT_CONFIG, and it contains a global record
-# pointing to: global_server1,global_server2
-# an a local cell cell1 pointing to cell1_server1,cell1_server2
-#
-# The existing directories created by Vitess are:
-# /zk/global/vt/...
-# /zk/cell1/vt/...
-#
-# The new zk2 implementation can use any root, so we will use:
-# /vitess/global in the global topology service, and:
-# /vitess/cell1 in the local topology service.
-
-# Create the new topology service roots in global and local cell.
-zk -server global_server1,global_server2 touch -p /vitess/global
-zk -server cell1_server1,cell1_server2 touch -p /vitess/cell1
-
-# Store the flags in a shell variable to simplify the example below.
-TOPOLOGY="-topo_implementation zk2 -topo_global_server_address global_server1,global_server2 -topo_global_root /vitess/global"
-
-# Reference cell1 in the global topology service:
-vtctl $TOPOLOGY AddCellInfo \
- -server_address cell1_server1,cell1_server2 \
- -root /vitess/cell1 \
- cell1
-
-# Now copy the topology. Note the old zookeeper implementation doesn't need
-# any server or root parameter, as it reads ZK_CLIENT_CONFIG.
-topo2topo \
- -from_implementation zookeeper \
- -to_implementation zk2 \
- -to_server global_server1,global_server2 \
- -to_root /vitess/global \
-
-# Rebuild SvrKeyspace objects in new service, for each keyspace.
-vtctl $TOPOLOGY RebuildKeyspaceGraph keyspace1
-vtctl $TOPOLOGY RebuildKeyspaceGraph keyspace2
-
-# Rebuild SrvVSchema objects in new service.
-vtctl $TOPOLOGY RebuildVSchemaGraph
-
-# Now restart all vtgate, vttablet, vtctld processes replacing:
-# -topo_implementation zookeeper
-# With:
-# -topo_implementation zk2
-# -topo_global_server_address global_server1,global_server2
-# -topo_global_root /vitess/global
-#
-# After this, the ZK_CLIENT_CONF file and environment variables are not needed
-# any more.
-```
-
-### Migration using the `Tee` implementation
-
-If your migration is more complex, or has special requirements, we also support
-a 'tee' implementation of the topo service interface. It is defined in
-`go/vt/topo/helpers/tee.go`. It allows communicating to two topo services,
-and the migration uses multiple phases:
-
-* Start with the old topo service implementation we want to replace.
-* Bring up the new topo service, with the same cells.
-* Use `topo2topo` to copy the current data from the old to the new topo.
-* Configure a Tee topo implementation to maintain both services.
- * Note we don't expose a plugin for this, so a small code change is necessary.
- * all updates will go to both services.
- * the `primary` topo service is the one we will get errors from, if any.
- * the `secondary` topo service is just kept in sync.
- * at first, use the old topo service as `primary`, and the new one as
- `secondary`.
- * then, change the configuration to use the new one as `primary`, and the
- old one as `secondary`. Reverse the lock order here.
- * then rollout a configuration to just use the new service.
-
-
diff --git a/doc/Troubleshooting.md b/doc/Troubleshooting.md
deleted file mode 100644
index a7b4b0541c2..00000000000
--- a/doc/Troubleshooting.md
+++ /dev/null
@@ -1,47 +0,0 @@
-If there is a problem in the system, one or many alerts would typically fire. If a problem was found through means other than an alert, then the alert system needs to be iterated upon.
-
-When an alert fires, you have the following sources of information to perform your investigation:
-
-* Alert values
-* Graphs
-* Diagnostic URLs
-* Log files
-
-Below are a few possible scenarios.
-
-### Elevated query latency on master
-
-Diagnosis 1: Inspect the graphs to see if QPS has gone up. If yes, drill down on the more detailed QPS graphs to see which table, or user caused the increase. If a table is identified, look at /debug/queryz for queries on that table.
-
-Action: Inform engineer about toxic query. If it’s a specific user, you can stop their job or throttle them to keep the load manageable. As a last resort, blacklist query to allow the rest of the system to stay healthy.
-
-Diagnosis 2: QPS did not go up, only latency did. Inspect the per-table latency graphs. If it’s a specific table, then it’s most likely a long-running low QPS query that’s skewing the numbers. Identify the culprit query and take necessary steps to get it optimized. Such queries usually do not cause outage. So, there may not be a need to take extreme measures.
-
-Diagnosis 3: Latency seems to be up across the board. Inspect transaction latency. If this has gone up, then something is causing MySQL to run too many concurrent transactions which causes slow-down. See if there are any tx pool full errors. If there is an increase, the INFO logs will dump info about all transactions. From there, you should be able to if a specific sequence of statements is causing the problem. Once that is identified, find out the root cause. It could be network issues, or it could be a recent change in app behavior.
-
-Diagnosis 4: No particular transaction seems to be the culprit. Nothing seems to have changed in any of the requests. Look at system variables to see if there are hardware faults. Is the disk latency too high? Are there memory parity errors? If so, you may have to failover to a new machine.
-
-### Master starts up read-only
-
-To prevent accidentally accepting writes, our default `my.cnf` settings
-tell MySQL to always start up read-only. If the master MySQL gets restarted,
-it will thus come back read-only until you intervene to confirm that it should
-accept writes. You can use the [SetReadWrite]({% link reference/vtctl.md %}#setreadwrite)
-command to do that.
-
-However, usually if something unexpected happens to the master, it's better to
-reparent to a different replica with [EmergencyReparentShard]({% link reference/vtctl.md %}#emergencyreparentshard). If you need to do planned maintenance on the master,
-it's best to first reparent to another replica with [PlannedReparentShard]({% link reference/vtctl.md %}#plannedreparentshard).
-
-### Vitess sees the wrong tablet as master
-
-If you do a failover manually (not through Vitess), you'll need to tell
-Vitess which tablet corresponds to the new master MySQL. Until then,
-writes will fail since they'll be routed to a read-only replica
-(the old master). Use the [TabletExternallyReparented]({% link reference/vtctl.md %}#tabletexternallyreparented)
-command to tell Vitess the new master tablet for a shard.
-
-Tools like [Orchestrator](https://github.com/github/orchestrator)
-can be configured to call this automatically when a failover occurs.
-See our sample [orchestrator.conf.json](https://github.com/vitessio/vitess/blob/1129d69282bb738c94b8af661b984b6377a759f7/docker/orchestrator/orchestrator.conf.json#L131)
-for an example of this.
diff --git a/doc/TwoPhaseCommitGuide.md b/doc/TwoPhaseCommitGuide.md
deleted file mode 100644
index dccdb196eac..00000000000
--- a/doc/TwoPhaseCommitGuide.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# 2PC User guide
-
-# Overview
-
-Vitess 2PC allows you to perform atomic distributed commits. The feature is implemented using traditional MySQL transactions, and hence inherits the same guarantees. With this addition, Vitess can be configured to support the following three levels of atomicity:
-
-1. **Single database**: At this level, only single database transactions are allowed. Any transaction that tries to go beyond a single database will be failed.
-2. **Multi database**: A transaction can span multiple databases, but the commit will be best effort. Partial commits are possible.
-3. **2PC**: This is the same as Multi-database, but the commit will be atomic.
-
-2PC commits are more expensive than multi-database because the system has to save away the statements before starting the commit process, and also clean them up after a successful commit. This is the reason why it's a separate option instead of being always on.
-
-## Isolation
-
-2PC transactions guarantee atomicity: either the whole transaction commits, or it's rolled back entirely. It does not guarantee Isolation (in the ACID sense). This means that a third party that performs cross-database reads can observe partial commits while a 2PC transaction is in progress.
-
-Guaranteeing ACID Isolation is very contentious and has high costs. Providing it by default would have made vitess impractical for the most common use cases.
-
-
-# Configuring VTGate
-
-The atomicity policy is controlled by the `transaction_mode` flag. The default value is `multi`, and will set it in multi-database mode. This is the same as the previous legacy behavior.
-
-To enforce single-database transactions, the VTGates can be started by specifying `transaction_mode=single`.
-
-To enable 2PC, the VTGates need to be started with `transaction_mode=twopc`. The VTTablets will require a few more flags, which will be explained below.
-
-The VTGate `transaction_mode` flag decides what to allow. The application can independently request a specific atomicity for each transaction. The request will be honored by VTGate only if it does not exceed what is allowed by the `transaction_mode`. For example, `transaction_mode=single` will only allow single-db transactions. On the other hand, `transaction_mode=twopc` will allow all three levels of atomicity.
-
-# Driver APIs
-
-The way to request atomicity from the application is driver-specific.
-
-## Go driver
-
-For the Go driver, you request the atomicity by adding it to the context using the `WithAtomicity` function. For more details, please refer to the respective GoDocs.
-
-## Python driver
-
-For Python, the `begin` function of the cursor has an optional `single_db` flag. If the flag is `True`, then the request is for a single-db transaction. If `False` (or unspecified), then the following `commit` call's `twopc` flag decides if the commit is 2PC or Best Effort (`multi`).
-
-## Java & PHP (TODO)
-
-## Adding support in a new driver
-
-The VTGate RPC API extends the `Begin` and `Commit` functions to specify atomicity. The API mimics the Python driver: The `BeginRequest` message provides a `single_db` flag and the `CommitRequest` message provides an `atomic` flag which is synonymous to `twopc`.
-
-# Configuring VTTablet
-
-The following flags need to be set to enable 2PC support in VTTablet:
-
-* **twopc_enable**: This flag needs to be turned on.
-* **twopc_coordinator_address**: This should specify the address (or VIP) of the VTGate that VTTablet will use to resolve abandoned transactions.
-* **twopc_abandon_age**: This is the time in seconds that specifies how long to wait before asking a VTGate to resolve an abandoned transaction.
-
-With the above flags specified, every master VTTablet also turns into a watchdog. If any 2PC transaction is left lingering for longer than `twopc_abandon_age` seconds, then VTTablet invokes VTGate and requests it to resolve it. Typically, the `abandon_age` needs to be substantially longer than the time it takes for a typical 2PC commit to complete (10s of seconds).
-
-# Configuring MySQL
-
-The usual default values of MySQL are sufficient. However, it's important to verify that `wait_timeout` (28800) has not been changed. If this value was changed to be too short, then MySQL could prematurely kill a prepared transaction causing data loss.
-
-# Monitoring
-
-A few additional variables have been added to `/debug/vars`. Failures described below should be rare. But these variables are present so you can build an alert mechanism if anything were to go wrong.
-
-## Critical failures
-
-The following errors are not expected to happen. If they do, it means that 2PC transactions have failed to commit atomically:
-
-* **InternalErrors.TwopcCommit**: This is a counter that shows the number of times a prepared transaction failed to fulfil a commit request.
-* **InternalErrors.TwopcResurrection**: This counter is incremented if a new master failed to resurrect a previously prepared (and unresolved) transaction.
-
-## Alertable failures
-
-The following failures are not urgent, but require someone to investigate:
-
-* **InternalErrors.WatchdogFail**: This counter is incremented if there are failures in the watchdog thread of VTTablet. This means that the watch dog is not able to alert VTGate of abandoned transactions.
-* **Unresolved.Prepares**: This is a gauge that is set based on the number of lingering Prepared transactions that have been alive for longer than 5x the abandon age. This usually means that a distributed transaction has repeatedly failed to resolve. A more serious condition is when the metadata for a distributed transaction has been lost and this Prepare is now permanently orphaned.
-
-# Repairs
-
-If any of the alerts fire, it's time to investigate. Once you identify the `dtid` or the VTTablet that originated the alert, you can navigate to the `/twopcz` URL. This will display three lists:
-
-1. **Failed Transactions**: A transaction reaches this state if it failed to commit. The only action allowed for such transactions is that you can discard it. However, you can record the DMLs that were involved and have someone come up with a plan to repair the partial commit.
-2. **Prepared Transactions**: Prepared transactions can be rolled back or committed. Prepared transactions must be remedied only if their root Distributed Transaction has been lost or resolved.
-3. **Distributed Transactions**: Distributed transactions can only be Concluded (marked as resolved).
diff --git a/doc/UpdateStream.md b/doc/UpdateStream.md
deleted file mode 100644
index 8891fb11cd9..00000000000
--- a/doc/UpdateStream.md
+++ /dev/null
@@ -1,498 +0,0 @@
-# Update Stream
-
-Update Stream is a Vitess service that provides a change stream for any keyspace.
-The use cases for this service include:
-
-* Providing an *invalidation stream*, that an application can use to maintain a cache.
-
-* Maintain an external copy of the data in another system, that is only updated
- when the data changes.
-
-* Maintain a change record of all the transactions that have been applied to the data.
-
-A good understanding
-of [Vitess Replication]({% link user-guide/vitess-replication.md %}) is required to
-understand this document better. We will go through the use cases in a bit more
-details, then introduce the EventToken notion, and finally explain the service.
-
-## Use Cases
-
-### Maintaining Cache Consistency
-
-The first use case we’re trying to address is to maintain a consistent cache of
-the data. The problem here has two parts:
-
-* When data changes, we need to invalidate the cache.
-
-* When we want to re-populate the cache after an invalidation, we need to make
- sure we get data that is more recent than the data change. For instance, we
- can’t just re-query any replica, as it might be behind on replication.
-
-This process can be somewhat resilient to some stream anomalies. For instance,
-invalidating the same record twice in some corner cases is fine, as long as we
-don’t poison the cache with an old value.
-
-Note the location / ownership of the cache is not set in stone:
-
-* Application-layer cache: the app servers maintain the cache. It’s very early
- in the serving chain, so in case of a cache hit, it’s lower latency. However,
- an invalidation process needs to run and is probably also owned by the
- application layer, which is somewhat annoying.
-
-* vtgate-layer cache: it would be a row cache accessed by vtgate, transparent to
- the app. It requires vtgate to do a lot of extra heavy-lifting, depending on
- what we want to support. Cache invalidation is still required, at a row level.
-
-* vttablet-layer cache: this is the old rowcache. Since the cache is not shared
- across instances, and the app still needs a cache, we abandoned this one.
-
-Since the vtgate-layer cache is much harder to work on (because of the query
-implications), and will probably require similar components as the app-layer
-cache, we decided to work on the app-layer cache for now, with possibly an
-invalidation process that is somewhat tied to the app.
-
-The *composite object cache* is an interesting use case: if the application is
-in charge of the cache, it would seem possible to put in the cache higher level
-composite objects, that are built from multiple table records. They would be
-invalidated any time one of the composing table record is changed. They need to
-be addressed by a part of the primary key, so they’re easy to find.
-
-### Change Log
-
-A Change Log provides a stream of all data changes, so an external application
-can either record these changes, or keep an external database up to date with
-the latest data.
-
-Unlike the Cache Invalidation use case, this is not as forgiving. If we have
-duplicate updates, they will need to be handled.
-
-## Design Considerations
-
-### Single Shard Update Stream
-
-This has been supported in Vitess for a while, but not exposed. It works as follows:
-
-* vttablet adds an SQL comment to every DML, that contains the Primary Key of
- the modified row.
-
-* vttablet provides a streaming service that can connect to the local MySQL
- replication stream, extract the comment, and stream events to the client.
-
-* Use the GTID as the start / restart position. It is sent back with each
- update, and an Update Stream can be started from it.
-
-Note Vitess supports both the MariaDB GTIDs (domain:server:sequence) and the
-MySQL 5.6 GTID Sets (encoded in SID blocks).
-
-### Surviving Resharding: Problem
-
-The Vitess tools are supposed to provide transparent sharding for the user’s
-data. Most of the trouble we run into is surviving resharding events, when we
-hop over from one set of shards to another set of shards.
-
-Two strategies then come to mind:
-
-* Provide a per-shard update stream. Let the user handle the hop when resharding
- happens. If we were to do this for the Cache use case, we would also need to
- provide some way of preventing bad corner cases, like a full cache flush, or
- no cache update for a while, or lost cache invalidations. Simple for us, but
- the app can be a lot more complicated. And the Change Log use case is also
- hard to do.
-
-* Provide a per-keyrange update stream. Vtgate would connect to the right
- shards, and resolve all conflicts. We can add the restriction that the client
- only asks for keyranges that are exactly matching to one or more shards. For
- instance, if a keyspace is sharded four ways, -40, 40-80, 80-c0, c0-, we can
- support clients asking for -40, -80, -, but not for 60-a0 for instance.
-
-As a reminder, the resharding process is somewhat simple:
-
-* Let’s say we want to split a shard 20-40 into two shards, 20-30 and 30-40. At
- first, only 20-40 exists and has a GTID stream.
-
-* We create 20-30 and 30-40, each has its own GTID stream. We copy the schema,
- and the data.
-
-* Filtered replication is enabled. A transaction in 20-40 is replayed on both
- 20-30 and 30-40, with an extra blp_checkpoint statement, that saves the 20-40
- GTID.
-
-* At some point, we migrate the read-only traffic from 20-40 replicas to 20-30
- and 30-40 replicas. (Note: this is probably when we want to migrate any
- invalidation process as well).
-
-* Then as a final step, the writes are migrated from 20-40 to 20-30 and 30-40.
-
-So we have a window of time when both streams are available simultaneously. For
-the resharding process to be operationally better, that window should be as
-small as possible (so we don't run with two copies of the data for too long). So
-we will make sure an Update Stream can hop from the source shards to the
-destination shards quickly.
-
-### Surviving Resharding: First Try
-
-To solve the shard hop problem during resharding, we tried to explore adding
-good timing information to the replication stream. However:
-
-* Since the time is added by vttablet, not MySQL, it is not accurate, not
- monotonic, and provides no guarantees.
-
-* Which such loose guarantees, it is no better than the second-accurate
- timestamp added by MySQL to each transaction.
-
-So this idea was abandoned.
-
-The GTID stream maintained by MySQL is the only true source of IDs for
-changes. It’s the only one we can trivially seek on, and get binlogs. The main
-issue with it is that it’s not maintained across shards when resharding.
-
-However, it is worth noting that a transaction replicated by the binlog streamer
-using Filtered Replication also saves the original GTID and the source
-transaction timestamp in the blp_checkpoint table. So we could extract the
-original GTID and timestamp from at least that statement (and if not, from an
-added comment).
-
-### Change Log and SBR
-
-If all we have is Statement Based Replication (SBR), we cannot get an accurate
-Change Log. SBR only provides the SQL statements, there is no easy way for us to
-parse them to get the final values of the columns (OK, there is, it’s just too
-complicated). And we cannot just query MySQL, as it may have already applied
-more transactions related to that record. So for Change Log, we need Row Based
-Replication (or a more advanced replication system).
-
-Note we can use the following setup:
-
-* Master and replicas use SBR.
-
-* Rdonly use SBR to connect to master, but log RBR logs locally.
-
-* We get the replication stream from rdonly servers.
-
-This is a bit awkward, and the main question is: what happens if a rdonly server
-is the only server that has replicated and semi-sync-acked a transaction, while
-the master is dying? Then to get that change, the other servers would get the
-RBR version of the change.
-
-Vitess support for RBR is coming. We will then explore these use cases further.
-
-## Detailed Design
-
-In the rest of this document, we’ll explore using the GTID when tracking a
-single shard, and revert to the timestamp when we hop across shards.
-
-As we do not want the application layer to understand / parse / compare the
-GTIDs, we’ll use an opaque token, and just pass it around the various
-layers. Vtgate / vttablet will understand it. The invalidation process should
-not have to, but will as there is no better solution.
-
-This approach can be made to work for the cache invalidation use case, but it
-might be difficult to provide an exact point in time for recovery / switching
-over to a different set of shards during resharding.
-
-For the Change Log, we’ll see what we can provide.
-
-### Event Token
-
-We define an Event Token structure that contains:
-
-* a MySQL replication timestamp (int64, seconds since Epoch).
-
-* a shard name
-
-* A GTIDSet position.
-
-It basically describes a position in a replication stream.
-
-An Event Token is always constructed from reading a transaction from the
-binlogs. If filtered replication is running, we use the source shard timestamp.
-
-Event Token comparison:
-
-* First, if the timestamps are different, just use that.
-
-* Then, if both use the same shard name, compare the GTIDs.
-
-* Otherwise we do not know for sure. It will depend on the usage to figure out
- what we do.
-
-*Possible Extension*: when filtered replication is running, we also update
-blp_checkpoint with the source GTID. We could add that information to the Event
-Token. Let’s try to go without in the first version, to remain simple. More on
-this later in the ‘Data Dump, Keeping it up to Date’ section.
-
-### Vttablet Changes
-
-#### Watching the Replication Stream
-
-Replicas are changed to add a background routine that reads the binlogs
-(controlled by the `watch_replication_stream` flag). When a tablet’s type is set
-to `replica`, the routine starts. It stops when the tablet is not `replica` any
-more (goes to `master`, `worker`, …).
-
-The routine starts reading the binlog from the current position. It then remembers:
-
-* The Event Token of the last seen transaction.
-
-* *Possible Optimization*: A map of the first time a timestamp is seen to the
- corresponding GTID position and filename / position. This would be a value per
- second. Let’s age these out: we keep the values for the last N seconds, then
- we keep a value for every minute for the last M hours. We forget values older
- than 3 days (or whatever the binlog retention time is).
-
-#### `include_event_token` Option
-
-We added an option to the Query Service API for Execute calls, called
-`include_event_token`. If set, vttablet will get the last seen Event Token right
-before issuing the query to MySQL, and include it in the response. This
-essentially represents the last known replication position that we’re sure the
-data we’re returning is fresher than.
-
-#### `compare_event_token` Option
-
-We added an option to the Query Service API for Execute calls, called
-`compare_event_token`. The provided event token is sent along with the call, and
-vttablet compares that token with the one its current replication stream watcher
-has. It returns the result of the comparison in ResultExtras.
-
-#### Update Stream API Change
-
-The Update Stream API in vttablet right now can only start from a GTID. We added a
-new API that can start from a timestamp as well. It will look for the right
-binlog file to start with, and start streaming events, discarding events until
-it finds the provided timestamp. *Optimization*: It can also look in the map to
-find the closest value it can start with, and then read from the binlogs until
-it finds the first timestamp. If it doesn’t have old enough values in its map,
-it errors out (the goal is to have vtgate then try another tablet to start
-from). For each event, we will also return the corresponding Event Token.
-
-*Optimization*: if an Update Stream client is caught up to the current binlog
-reading thread, we can just tee the binlog stream to that client. We won’t do
-that in the first version, as we don’t expect that many clients.
-
-Note that when filtered replication is running, we need to have the timestamp of
-the source transaction on the source shard, not the local timestamp of the
-applied transaction. Which also means that timestamps will not be always
-linearly increasing in the stream, in the case of a shard merge (although they
-will be linearly increasing for a given keyspace_id).
-
-### Vtgate Changes
-
-We added a new Update Stream service to vtgate. It takes as input a keyspace and
-an optional KeyRange (for sharded keyspaces). As a starting point, it takes a
-timestamp.
-
-*Caveat*: As previously mentioned, at first, we can add the restriction that the
-client only asks for KeyRanges that are exactly matching to one or more
-shards. For instance, if a keyspace is sharded four ways, -40, 40-80, 80-c0,
-c0-, we can support clients asking for -40, -80, -, but not for 60-a0 for
-instance. Lifting that restriction is somewhat easy, we’d just have to filter
-the returned keyspace_ids by KeyRange, but that’s extra work for not much gain
-in the short term (and we don’t parse keyspace_id in Binlog Streamer right now,
-just the PK).
-
-After using the partition map in SrvKeyspace, vtgate will have a list of shards
-to query. It will need to create a connection for every shard that overlaps with
-the input KeyRange. For every shard, it will pick an up-to-date replica and use
-the Update Stream API mentioned above. If the vttablet cannot provide the
-stream, it will failover to another one. It will then start an Update Stream on
-all sources, and just merge and stream the results back to the source. For each
-Event Token that is read from a source, vtgate will also send the smallest
-timestamp of all Events it’s seen in all sources. That way the client has a
-value to start back from in case it needs to restart.
-
-In case of resharding event, the list of shards to connect to may change. Vtgate
-will build a map of overlapping shards, to know which source shards are mapped
-to which destination shards. It will then stop reading from all the source
-shards, find the minimum timestamp of the last event it got from each source,
-and use that to restart the stream on the destination shards.
-
-*Alternate Simpler Solution*: when vtgate notices a SrvKeyspace change in the
-serving shards, it just aborts the invalidation stream. The client is
-responsible for reconnecting with the last timestamp it’s seen. The client will
-need to handle this error case anyway (when vtgates get upgraded at least).
-
-*Caveat*: this will produce duplicate Event Tokens, with the same timestamp but
-with GTID positions from two different streams. More on this later, but for a
-Cache Invalidation scenario, no issue, and for a Change Log application, we’ll
-see how we can deal with it.
-
-We also add the same `include_event_token` flag to vtgate query service. It just
-passes it along to the underlying vttablet. It’s only supported for
-single-keyspace_id queries. The resulting EventToken is just returned back as
-is.
-
-## Use Cases How To
-
-Let's revisit our use cases and see how this addresses them.
-
-### Cache Invalidation
-
-The idea is to use the Event Token coming from both the Execute results and the
-Update Stream to maintain cache consistency.
-
-The cache contains entries with both:
-
-* An Event Token. It describes either the invalidation, or the last population.
-
-* An optional value.
-
-The invalidation process works as follows:
-
-* It asks vtgate for an Update Stream for a provided keyspace / KeyRange,
- starting at the current timestamp (or from a few seconds/minutes/hours in the
- past, or from the last checkpointed timestamp it had saved).
-
-* Vtgate resolves the keyrange into shards. It starts an invalidation stream
- with a healthy replica in each shard from the provided timestamp.
-
-* Vtgate sends back all Event Tokens it collects, with all of timestamp, shard
- name and GTID.
-
-* For each change it gets, the invalidation process reads the cache record. Two cases:
-
- * No entry in the cache: it stores the Event Token (to indicate the cache
- should not be populated unless the value is greater) with no value.
-
- * An entry in the cache exists, with an Event Token:
-
- * If the cached Event Token is strictly older, update it with the new Event
- Token, clear the value.
-
- * If the cached Event Token is strictly more recent, discard the new Event.
-
- * If we don’t know which Event Token is the most recent (meaning they have
- the same timestamp, and are read from different invalidation stream), we
- need to do the safest thing: invalidate the cache with the current Event
- Token. This is the safest because we’re guaranteed to get duplicate
- events, and not miss events.
-
- * In any case the invalidation process only updates the cache if it still
- contains the value it read (CAS). Otherwise it rereads and tries again
- (means an appserver or another invalidator somehow also updated the cache).
-
-A regular appserver will query the cache for the value it wants. It will get either:
-
-* No entry: asks vtgate for the Event Token when querying the database, use a
- CAS operation to set the value the returned Event Token + Value.
-
-* An entry with both an Event Token and a Value: Just use the value.
-
-* An entry with just an Event Token and no Value:
-
- * Send the Event Token along with the query to vtgate as
- `compare_event_token`, and also asking for Event Token using `include_event_token`.
-
- * Vtgate will query vttablet as usual, but also passing both flags.
-
- * Vttablet will then compare the provided Event Token with the one that was
- included. It will include in the response the knowledge of the Event Token
- comparison as a boolean, only set if the data read is `fresher`.
-
- * Depending on the `fresher` boolean flag, the app will:
-
- * Data read is more recent: Update the cache with new Event Token / Value.
-
- * Data read is not more recent (or we don't know for sure): don’t update the cache.
-
-*Constraints*:
-
-* When restarting the invalidation process, we start from a point back in time,
- let’s say N seconds behind now. Since we can ask destination shards at this
- point for events that are N seconds old, filtered replication has to have been
- running for at least N seconds. (Alternatively, the invalidators can
- checkpoint their current position from time to time, and restart from that
- when starting up, and revert back to N seconds behind now).
-
-* As mentioned before, the shard range queried by the invalidation process
- should cover a round number of actual shards.
-
-* The invalidation process needs to know how to compare tokens. This is a
- bummer, I don’t see any way around it. We could simplify and only do the
- timestamp comparison part, but that would mean the cache is unused for up to
- an entire second upon changes. The appserver doesn’t need to compare, it gives
- the value to vtgate and let it do the work.
-
-To see a sample use of the Update Stream feature, look at
-the
-[cache_invalidation.py](https://github.com/vitessio/vitess/blob/master/test/cache_invalidation.py) integration
-test. It shows how to do the invalidaiton in python, and the application
-component.
-
-### Extension: Removing Duplicate Events
-
-In the previous section, we use timestamps to easily seek on replication
-streams. If we added the ability to seek on any source GTID that appears in the
-destination stream, we should be able to precisely seek at the right spot. That
-would make exact transitions from one stream to the next possible. Again, as
-long as the destination shard in a resharding event has been running filtered
-replication for as long as we want to go back.
-
-However, describing a position on a replication stream becomes tricky: it needs
-one Event Token per replication stream. When resharding the Event Tokens would
-jump around. When restarting a stream from an Event Token list, we may need to
-restart earlier in some cases and skip some items.
-
-*Bottom Line*:
-
-* This would require a bunch of non-trivial code.
-
-* This requires that filtered replication would be running for at least as long
- as we want to go back in time for the starting point.
-
-If there is no use case for it, let’s not do it.
-
-### Extension: Adding Update Data to the Stream, Towards Change Log
-
-Let’s add a flag to the streaming query, that, if specified, asks for the
-changed columns as well as the PK.
-
-* If using SBR, and the flag is present, vttablet can just query the row at the
- time we get the event, and send it along. As already mentioned, the data may
- not be exactly up to date. It is however guaranteed to be newer than the Event
- Token, which might be good enough to put in a cache for instance.
-
-* If using RBR, we just get the data for free, just send it along.
-
-*Bottom Line*: Let’s try to go without this extension and see how it goes. We
-can implement the additional data when we fully support RBR.
-
-### Extension: Data Dump, Keeping It Up To Date
-
-*Use Case*: keep a secondary database (like a HBase database) up to date.
-*Requirements*: RBR replication, plus Data included in the Stream (previous extension).
-
-It’s simple:
-
-* The external database has the same schema as MySQL. Each row is indexed by
- PK. It also has an extra field, for the last Event Token.
-
-* Remember start time of the process, let’s call it StartTime
-
-* Dump the data to other database. Using Map/Reduce, whatever. Do not populate
- the Event Tokens.
-
-* Start an invalidation process, asking for changes from StartTime. When getting
- updates, read the current external database row and its Event Token:
-
- * If there is no existing row / no Event token, save the new value.
-
- * If there is an existing row with a strictly more recent Event Token, ignore
- the event.
-
- * Otherwise (when the existing Event Token is older or we don’t know), store
- the new Value / Event Token.
-
-Note this again means the dumping process needs to be able to compare Event
-Tokens, as the invalidator does.
-
-*Caveat*: As described, the values in the secondary storage will converge, but
-they may go back in time for a bit, as we will process duplicate events during
-resharding, and we may not know how to compare them.
-
-*Extension*: if we also add the source GTID in Event Tokens read from a
-destination shard during filtered replication, we can break the tie easily on
-duplicate events, and guarantee we only move forward. This seems like the
-easiest solution, and we can then use only timestamps as starting times for
-restarting the sync process.
-
diff --git a/doc/Upgrading.md b/doc/Upgrading.md
deleted file mode 100644
index 04723da9ded..00000000000
--- a/doc/Upgrading.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Upgrading a Vitess Installation
-
-This document highlights things to look after when upgrading a Vitess production installation to a newer Vitess release.
-
-Generally speaking, upgrading Vitess is a safe and easy process because it is explicitly designed for it. This is because in YouTube we follow the practice of releasing new versions often (usually from the tip of the Git master branch).
-
-## Compatibility
-
-Our versioning strategy is based on [Semantic Versioning](https://semver.org/).
-
-Vitess version numbers follow the format `MAJOR.MINOR.PATCH`.
-We guarantee compatibility when upgrading to a newer **patch** or **minor** version.
-Upgrades to a higher **major** version may require manual configuration changes.
-
-In general, always **read the 'Upgrading' section of the release notes**.
-It will mention any incompatible changes and necessary manual steps.
-
-## Upgrade Order
-
-We recommend to upgrade components in a bottom-to-top order such that "old" clients will talk to "new" servers during the transition.
-
-Please use this upgrade order (unless otherwise noted in the release notes):
-
-- vtctld
-- vttablet
-- vtgate
-- application code which links client libraries
-
-*vtctld* is listed first to make sure that you can still administrate Vitess - or if not find out as soon as possible.
-
-## Canary Testing
-
-Within the vtgate and vttablet components, we recommend to [canary](https://martinfowler.com/bliki/CanaryRelease.html) single instances, keyspaces and cells. Upgraded canary instances can "bake" for several hours or days to verify that the upgrade did not introduce a regression. Eventually, you can upgrade the remaining instances.
-
-## Rolling Upgrades
-
-We recommend to automate the upgrade process with a configuration management software. It will reduce the possibility of human errors and simplify the process of managing all instances.
-
-As of June 2016 we do not have templates for any major open-source configuration management software because our internal upgrade process is based on a proprietary software. Therefore, we invite open-source users to contribute such templates.
-
-Any upgrade should be a rolling release i.e. usually one tablet at a time within a shard. This ensures that the remaining tablets continue serving live traffic and there is no interruption.
-
-## Upgrading the Master Tablet
-
-The *master* tablet of each shard should always be updated last in the following manner:
-
-- verify that all *replica* tablets in the shard have been upgraded
-- reparent away from the current *master* to a *replica* tablet
-- upgrade old *master* tablet
diff --git a/doc/UserGuideIntroduction.md b/doc/UserGuideIntroduction.md
deleted file mode 100644
index 261abfa46ef..00000000000
--- a/doc/UserGuideIntroduction.md
+++ /dev/null
@@ -1,83 +0,0 @@
-## Platform support
-
-We continuously test against Ubuntu 14.04 (Trusty) and Debian 8 (Jessie).
-Other Linux distributions should work as well.
-
-## Database support
-
-Vitess supports [MySQL 5.6](https://dev.mysql.com/doc/refman/5.6/en/),
-[MariaDB 10.0](https://downloads.mariadb.org/mariadb/10.0.21/), and any
-newer versions like MySQL 5.7, etc. Vitess also supports Percona's
-variations of these versions.
-
-### Relational capabilities
-
-Vitess attempts to leverage the capabilities of the underlying MySQL
-instances to the fullest extent. In this respect, any query that can
-be passed through to a single keyspace, shard or set of shards will
-be sent to the MySQL servers as is.
-
-This approach allows you to exploit the full capabilities of MySQL
-as long as the relationships and constraints are within one shard (or
-unsharded keyspace).
-
-For relationships that go beyond shards, Vitess provides
-support through the [VSchema]({% link user-guide/vschema.md %}).
-
-### Schema management
-
-Vitess supports several functions for looking at your schema and
-validating its consistency across tablets in a shard or across all
-shards in a keyspace.
-
-In addition, Vitess supports
-[data definition statements](https://dev.mysql.com/doc/refman/5.6/en/sql-syntax-data-definition.html)
-that create, modify, or delete database tables. Vitess executes
-schema changes on the master tablet within each shard, and those
-changes then propagate to slave tablets via replication. Vitess does
-not support other types of DDL statements, such as those that affect
-stored procedures or grants.
-
-Before executing a schema change, Vitess validates the SQL syntax
-and determines the impact of the change. It also does a pre-flight
-check to ensure that the update can be applied to your schema. In
-addition, to avoid reducing the availability of your entire system,
-Vitess rejects changes that exceed a certain scope.
-
-See the [Schema Management]({% link user-guide/schema-management.md %})
-section of this guide for more information.
-
-## Supported clients
-
-The VTGate server is the main entry point that applications use
-to connect to Vitess.
-
-VTGate understands the MySQL binary protocol. So, any client that
-can directly talk to MySQL can also use Vitess.
-
-Additionally, VTGate exposes its functionality through a
-[gRPC](https://www.grpc.io/) API which has support for multiple languages.
-
-Accessing Vitess through gRPC has some minor advantages over the MySQL
-protocol:
-
-* You can send requests with bind variables, which is slightly more
- efficient and secure than building the full text query.
-* You can exploit the statelessness of connections. For example, you
- can start a transaction using one VTGate server, and complete it
- using another.
-
-Vitess currently provides gRPC based connectors for Java (JDBC) and Go
-(database/sql). All others can use the native MySQL drivers instead. The
-native MySQL drivers for Java and Go should also work.
-
-## Backups
-
-Vitess supports data backups to either a network mount (e.g. NFS) or to a blob store.
-Backup storage is implemented through a pluggable interface,
-and we currently have plugins available for Google Cloud Storage, Amazon S3,
-and Ceph.
-
-See the [Backing Up Data]({% link user-guide/backup-and-restore.md %}) section
-of this guide for more information about creating and restoring data
-backups with Vitess.
diff --git a/doc/VSchema.md b/doc/VSchema.md
deleted file mode 100644
index 83c207badd7..00000000000
--- a/doc/VSchema.md
+++ /dev/null
@@ -1,340 +0,0 @@
-# VSchema User Guide
-
-VSchema stands for Vitess Schema. In contrast to a traditional database schema that contains metadata about tables, a VSchema contains metadata about how tables are organized across keyspaces and shards. Simply put, it contains the information needed to make Vitess look like a single database server.
-
-For example, the VSchema will contain the information about the sharding key for a sharded table. When the application issues a query with a WHERE clause that references the key, the VSchema information will be used to route the query to the appropriate shard.
-
-## Sharding Model
-
-In Vitess, a `keyspace` is sharded by `keyspace ID` ranges. Each row is assigned a keyspace ID, which acts like a street address, and it determines the shard where the row lives. In some respect, one could say that the `keyspace ID` is the equivalent of a NoSQL sharding key. However, there are some differences:
-
-1. The `keyspace ID` is a concept that is internal to Vitess. The application does not need to know anything about it.
-2. There is no physical column that stores the actual `keyspace ID`. This value is computed as needed.
-
-This difference is significant enough that we do not refer to the keyspace ID as the sharding key. we will later introduce the concept of a Primary Vindex which more closely resembles the NoSQL sharding key.
-
-Mapping to a `keyspace ID`, and then to a shard, gives us the flexibility to reshard the data with minimal disruption because the `keyspace ID` of each row remains unchanged through the process.
-
-## Vindex
-
-The Sharding Key is a concept that was introduced by NoSQL datastores. It is based on the fact that there is only one access path to the data, which is the Key. However, relational databases are more versatile about the data and their relationships. So, sharding a database by only designating a sharding key is often insufficient.
-
-If one were to draw an analogy, the indexes in a database would be the equivalent of the key in a NoSQL datastore, except that databases allow you to define multiple indexes per table, and there are many types of indexes. Extending this analogy to a sharded database results in different types of cross-shard indexes. In Vitess, these are called Vindexes.
-
-Simplistically stated, a Vindex provides a way to map a column value to a `keyspace ID`. This mapping can be used to identify the location of a row. A variety of vindexes are available to choose from with different trade-offs, and you can choose one that best suits your needs.
-
-Vindexes offer many flexibilities:
-
-* A table can have multiple Vindexes.
-* Vindexes could be NonUnique, which allows a column value to yield multiple keyspace IDs.
-* They could be a simple function or be based on a lookup table.
-* They could be shared across multiple tables.
-* Custom Vindexes can be plugged in, and Vitess will still know how to reshard using such Vindexes.
-
-### The Primary Vindex
-
-The Primary Vindex is analogous to a database primary key. Every sharded table must have one defined. A Primary Vindex must be unique: given an input value, it must produce a single keyspace ID. This unique mapping will be used at the time of insert to decide the target shard for a row. Conceptually, this is also equivalent to the NoSQL Sharding Key, and we often refer to the Primary Vindex as the Sharding Key.
-
-Uniqueness for a Primary Vindex does not mean that the column has to be a primary key or unique in the MySQL schema. You can have multiple rows that map to the same keyspace ID. The Vindex uniqueness constraint is only used to make sure that all rows for a keyspace ID live in the same shard.
-
-However, there is a subtle difference: NoSQL datastores let you choose the Sharding Key, but the Sharding Scheme is generally hardcoded in the engine. In Vitess, the choice of Vindex lets you control how a column value maps to a keyspace ID. In other words, a Primary Vindex in Vitess not only defines the Sharding Key, it also decides the Sharding Scheme.
-
-Vindexes come in many varieties. Some of them can be used as Primary Vindex, and others have different purposes. The following sections will describe their properties.
-
-### Secondary Vindexes
-
-Secondary Vindexes are additional vindexes you can define against other columns of a table offering you optimizations for WHERE clauses that do not use the Primary Vindex. Secondary Vindexes return a single or a limited set of `keyspace IDs` which will allow VTGate to only target shards where the relevant data is present. In the absence of a Secondary Vindex, VTGate would have to send the query to all shards.
-
-Secondary Vindexes are also commonly known as cross-shard indexes. It is important to note that Secondary Vindexes are only for making routing decisions. The underlying database shards will most likely need traditional indexes on those same columns.
-
-### Unique and NonUnique Vindex
-
-A Unique Vindex is one that yields at most one keyspace ID for a given input. Knowing that a Vindex is Unique is useful because VTGate can push down some complex queries into VTTablet if it knows that the scope of that query cannot exceed a shard. Uniqueness is also a prerequisite for a Vindex to be used as Primary Vindex.
-
-A NonUnique Vindex is analogous to a database non-unique index. It is a secondary index for searching by an alternate WHERE clause. An input value could yield multiple keyspace IDs, and rows could be matched from multiple shards. For example, if a table has a `name` column that allows duplicates, you can define a cross-shard NonUnique Vindex for it, and this will let you efficiently search for users that match a certain `name`.
-
-### Functional and Lookup Vindex
-
-A Functional Vindex is one where the column value to keyspace ID mapping is pre-established, typically through an algorithmic function. In contrast, a Lookup Vindex is one that gives you the ability to create an association between a value and a keyspace ID, and recall it later when needed.
-
-Typically, the Primary Vindex is Functional. In some cases, it is the identity function where the input value yields itself as the kesypace id. However, one could also choose other algorithms like hashing or mod functions.
-
-A Lookup Vindex is usually backed by a lookup table. This is analogous to the traditional database index, except that it is cross-shard. At the time of insert, the computed keyspace ID of the row is stored in the lookup table against the column value.
-
-### Shared Vindexes
-
-Relational databases encourage normalization, which lets you split data into different tables to avoid duplication in the case of one-to-many relationships. In such cases, a key is shared between the two tables to indicate that the rows are related, aka `Foreign Key`.
-
-In a sharded environment, it is often beneficial to keep those rows in the same shard. If a Lookup Vindex was created on the foreign key column of each of those tables, you would find that the backing tables would actually be identical. In such cases, Vitess lets you share a single Lookup Vindex for multiple tables. Of these, one of them is designated as the owner, which is responsible for creating and deleting these associations. The other tables just reuse these associations.
-
-Caveat: If you delete a row from the owner table, Vitess will not perform cascading deletes. This is mainly for efficiency reasons; The application is likely capable of doing this more efficiently.
-
-Functional Vindexes can be also be shared. However, there is no concept of ownership because the column to keyspace ID mapping is pre-established.
-
-### Orthogonality
-
-The previously described properties are mostly orthogonal. Combining them gives rise to the following valid categories:
-
-* **Functional Unique**: This is the most popular category because it is the one best suited to be a Primary Vindex.
-* **Functional NonUnique**: There are currently no use cases that need this category.
-* **Lookup Unique Owned**: This gets used for optimizing high QPS queries that do not use the Primary Vindex columns in their WHERE clause. There is a price to pay: You incur an extra write to the lookup table for insert and delete operations, and an extra lookup for read operations. However, it is worth it if you do not want these high QPS queries to be sent to all shards.
-* **Lookup Unique Unowned**: This category is used as an optimization as described in the Shared Vindexes section.
-* **Lookup NonUnique Owned**: This gets used for high QPS queries on columns that are non-unique.
-* **Lookup NonUnique Unowned**: You would rarely have to use this category because it is unlikely that you will be using a column as foreign key that is not unique within a shard. But it is theoretically possible.
-
-Of the above categories, `Functional Unique` and `Lookup Unique Unowned` Vindexes can be Primary. This is because those are the only ones that are unique and have the column to keyspace ID mapping pre-established. This is required because the Primary Vindex is responsible for assigning the keyspace ID for a row when it is created.
-
-However, it is generally not recommended to use a Lookup vindex as Primary because it is too slow for resharding. If absolutely unavoidable, you can use a Lookup Vindex as Primary. In such cases, it is recommended that you add a `keyspace ID` column to such tables. While resharding, Vitess can use that column to efficiently compute the target shard. You can even configure Vitess to auto-populate that column on inserts. This is done using the reverse map feature explained below.
-
-### How vindexes are used
-
-#### Cost
-
-Vindexes have costs. For routing a query, the Vindex with the lowest cost is chosen. The current costs are:
-
-Vindex Type | Cost
------------ | ----
-Indentity | 0
-Functional | 1
-Lookup Unique | 10
-Lookup NonUnique | 20
-
-#### Select
-
-In the case of a simple select, Vitess scans the WHERE clause to match references to Vindex columns and chooses the best one to use. If there is no match and the query is simple without complex constructs like aggregates, etc, it is sent to all shards.
-
-Vitess can handle more complex queries. For now, you can refer to the [design doc](https://github.com/vitessio/vitess/blob/master/doc/V3HighLevelDesign.md) on how it handles them.
-
-#### Insert
-
-* The Primary Vindex is used to generate a keyspace ID.
-* The keyspace ID is validated against the rest of the Vindexes on the table. There must exist a mapping from the column value to the keyspace ID.
-* If a column value was not provided for a Vindex and the Vindex is capable of reverse mapping a keyspace ID to an input value, that function is used to auto-fill the column. If there is no reverse map, it is an error.
-
-#### Update
-
-The WHERE clause is used to route the update. Updating the value of a Vindex column is supported, but with a restriction: the change in the column value should not result in the row being moved from one shard to another. A workaround is to perform a delete followed by insert, which works as expected.
-
-#### Delete
-
-If the table owns lookup vindexes, then the rows to be deleted are first read and the associated Vindex entries are deleted. Following this, the query is routed according to the WHERE clause.
-
-### Predefined Vindexes
-
-Vitess provides the following predefined Vindexes:
-
-Name | Type | Description | Primary | Reversible | Cost
----- | ---- | ----------- | ------- | ---------- | ----
-binary | Functional Unique | Identity | Yes | Yes | 0
-binary_md5 | Functional Unique | md5 hash | Yes | No | 1
-hash | Functional Unique | 3DES null-key hash | Yes | Yes | 1
-lookup | Lookup NonUnique | Lookup table non-unique values | No | Yes | 20
-lookup_unique | Lookup Unique | Lookup table unique values | If unowned | Yes | 10
-numeric | Functional Unique | Identity | Yes | Yes | 0
-numeric_static_map | Functional Unique | A JSON file that maps input values to keyspace IDs | Yes | No | 1
-unicode_loose_md5 | Functional Unique | Case-insensitive (UCA level 1) md5 hash | Yes | No | 1
-reverse_bits | Functional Unique | Bit Reversal | Yes | Yes | 1
-
-Custom vindexes can also be plugged in as needed.
-
-## Sequences
-
-Auto-increment columns do not work very well for sharded tables. [Vitess sequences]({% link user-guide/vitess-sequences.md %}) solve this problem. Sequence tables must be specified in the VSchema, and then tied to table columns. At the time of insert, if no value is specified for such a column, VTGate will generate a number for it using the sequence table.
-
-## VSchema
-
-As mentioned in the beginning of the document, a VSchema is needed to tie together all the databases that Vitess manages. For a very trivial setup where there is only one unsharded keyspace, there is no need to specify a VSchema because Vitess will know that there is no other place to route a query.
-
-If you have multiple unsharded keyspaces, you can still avoid defining a VSchema in one of two ways:
-
-1. Connect to a keyspace and all queries are sent to it.
-2. Connect to Vitess without specifying a keyspace, but use qualified names for tables, like `keyspace.table` in your queries.
-
-However, once the setup exceeds the above complexity, VSchemas become a necessity. Vitess has a [working demo](https://github.com/vitessio/vitess/tree/master/examples/demo) of VSchemas. This section documents the various features highlighted with snippets pulled from the demo.
-
-### Unsharded Table
-
-The following snippets show the necessary configs for creating a table in an unsharded keyspace:
-
-Schema:
-
-``` sql
-# lookup keyspace
-create table name_user_idx(name varchar(128), user_id bigint, primary key(name, user_id));
-```
-
-VSchema:
-
-``` json
-// lookup keyspace
-{
- "sharded": false,
- "tables": {
- "name_user_idx": {}
- }
-}
-```
-
-For a normal unsharded table, the VSchema only needs to know the table name. No additional metadata is needed.
-
-### Sharded Table With Simple Primary Vindex
-
-To create a sharded table with a simple Primary Vindex, the VSchema requires more information:
-
-Schema:
-
-``` sql
-# user keyspace
-create table user(user_id bigint, name varchar(128), primary key(user_id));
-```
-
-VSchema:
-
-``` json
-// user keyspace
-{
- "sharded": true,
- "vindexes": {
- "hash": {
- "type": "hash"
- },
- "tables": {
- "user": {
- "column_vindexes": [
- {
- "column": "user_id",
- "name": "hash"
- }
- ]
- }
- }
-}
-```
-
-Because Vindexes can be shared, the JSON requires them to be specified in a separate `vindexes` section, and then referenced by name from the `tables` section. The VSchema above simply states that `user_id` uses `hash` as Primary Vindex. The first Vindex of every table must be the Primary Vindex.
-
-### Specifying A Sequence
-
-Since user is a sharded table, it will be beneficial to tie it to a Sequence. However, the sequence must be defined in the lookup (unsharded) keyspace. It is then referred from the user (sharded) keyspace. In this example, we are designating the user_id (Primary Vindex) column as the auto-increment.
-
-Schema:
-
-``` sql
-# lookup keyspace
-create table user_seq(id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence';
-insert into user_seq(id, next_id, cache) values(0, 1, 3);
-```
-
-For the sequence table, `id` is always 0. `next_id` starts off as 1, and the cache is usually a medium-sized number like 1000. In our example, we are using a small number to showcase how it works.
-
-VSchema:
-
-``` json
-// lookup keyspace
-{
- "sharded": false,
- "tables": {
- "user_seq": {
- "type": "sequence"
- }
- }
-}
-
-// user keyspace
-{
- "sharded": true,
- "vindexes": {
- "hash": {
- "type": "hash"
- },
- "tables": {
- "user": {
- "column_vindexes": [
- {
- "column": "user_id",
- "name": "hash"
- }
- ],
- "auto_increment": {
- "column": "user_id",
- "sequence": "user_seq"
- }
- }
- }
-}
-```
-
-### Specifying A Secondary Vindex
-
-The following snippet shows how to configure a Secondary Vindex that is backed by a lookup table. In this case, the lookup table is configured to be in the unsharded lookup keyspace:
-
-Schema:
-
-``` sql
-# lookup keyspace
-create table name_user_idx(name varchar(128), user_id bigint, primary key(name, user_id));
-```
-
-VSchema:
-
-``` json
-// lookup keyspace
-{
- "sharded": false,
- "tables": {
- "name_user_idx": {}
- }
-}
-
-// user keyspace
-{
- "sharded": true,
- "vindexes": {
- "name_user_idx": {
- "type": "lookup_hash",
- "params": {
- "table": "name_user_idx",
- "from": "name",
- "to": "user_id"
- },
- "owner": "user"
- },
- "tables": {
- "user": {
- "column_vindexes": [
- {
- "column": "name",
- "name": "name_user_idx"
- }
- ]
- }
- }
-}
-```
-
-To recap, a checklist for creating the shared Secondary Vindex is:
-
-* Create physical `name_user_idx` table in lookup database.
-* Define a routing for it in the lookup VSchema.
-* Define a Vindex as type `lookup_hash` that points to it. Ensure that the `params` match the table name and columns.
-* Define the owner for the Vindex as the `user` table.
-* Specify that `name` uses the Vindex.
-
-Currently, these steps have to be currently performed manually. However, extended DDLs backed by improved automation will simplify these tasks in the future.
-
-### Advanced usage
-
-The examples/demo also shows more tricks you can perform:
-
-* The `music` table uses a secondary lookup vindex `music_user_idx`. However, this lookup vindex is itself a sharded table.
-* `music_extra` shares `music_user_idx` with `music`, and uses it as Primary Vindex.
-* `music_extra` defines an additional Functional Vindex called `keyspace_id` which the demo auto-populates using the reverse mapping capability.
-* There is also a `name_info` table that showcases a case-insensitive Vindex `unicode_loose_md5`.
-
-## Roadmap
-
-VSchema is still evolving. Features are mostly added on demand. The following features are currently on our roadmap:
-
-* DDL support
-* Lookup Vindex backfill
-* Pinned tables: This feature will allow unsharded tables to be pinned to a keyspace id. This avoids the need for a separate unsharded keyspace to contain them.
diff --git a/doc/VTTabletModes.md b/doc/VTTabletModes.md
deleted file mode 100644
index 1d37efdf4af..00000000000
--- a/doc/VTTabletModes.md
+++ /dev/null
@@ -1,107 +0,0 @@
-VTTablet can be configured to control mysql at many levels. At the level with the most control, vttablet can perform backups and restores, respond to reparenting commands coming through vtctld, automatically fix replication, and enforce semi-sync settings.
-
-At the level with the least control, vttablet just sends the application’s queries to mysql. The level of desired control is achieved through various command line arguments, explained below.
-
-## Managed MySQL
-
-In the mode with the highest control, VTTablet can take backups. It can also automatically restore from an existing backup to prime a new replica. For this mode, vttablet needs to run on the same host as mysql, and must be given access to mysql's my.cnf file. Additionally, the flags must not contain any connectivity parameters like `-db_host` or `-db_socket`; VTTablet will fetch the socket information from my.cnf and use that to connect to the local mysql.
-
-It will also load other information from the my.cnf, like the location of data files, etc. When it receives a request to take a backup, it will shut down mysql, copy the mysql data files to the backup store, and restart mysql.
-
-The my.cnf file can be specified the following ways:
-
-* Implicit: If mysql was initialized by the `mysqlctl` tool, then vttablet can find it based on just the `-tablet-path`. The default location for this file is `$VTDATAROOT/vt_/my.cnf`.
-* `-mycnf-file`: This option can be used if the file is not present in the default location.
-* `-my_cnf_server_id` and other flags: You can specify all values of the my.cnf file from the command line, and vttablet will behave as it read this information from a physical file.
-
-Specifying a `-db_host` or a `-db_socket` parameter will cause vttablet to skip the loading of the my.cnf file, and will disable its ability to perform backups or restores.
-
-### -restore\_from\_backup
-
-The default value for this flag is false. If set to true, and the my.cnf file was successfully loaded, then vttablet can perform automatic restores as follows:
-
-If started against a mysql instance that has no data files, it will search the list of backups for the latest one, and initiate a restore. After this, it will point the mysql to the current master and wait for replication to catch up. Once replication is caught up to the specified tolerance limit, it will advertise itself as serving. This will cause the vtgates to add it to the list of healthy tablets to serve queries from.
-
-If this flag is true, but my.cnf was not loaded, then vttablet will fatally exit with an error message.
-
-You can additionally control the level of concurrency for a restore with the `-restore_concurrency` flag. This is typically useful in cloud environments to prevent the restore process from becoming a 'noisy' neighbor by consuming all available disk IOPS.
-
-## Unmanaged or remote MySQL
-
-You can start a vttablet against a remote mysql by simply specifying the connection parameters `-db_host` and `-db_port` on the command line. In this mode, backup and restore operations will be disabled. If you start vttablet against a local mysql, you can specify a `-db_socket` instead, which will still make vttablet treat mysql as if it was remote.
-
-Specifically, the absence of a my.cnf file indicates to vttablet that it's connecting to a remote MySQL.
-
-## Partially managed MySQL
-
-Even if a MySQL is remote, you can still make vttablet perform some management functions. They are as follows:
-
-* `-disable_active_reparents`: If this flag is set, then any reparent or slave commands will not be allowed. These are InitShardMaster, PlannedReparent, EmergencyReparent, and ReparentTablet. In this mode, you should use the TabletExternallyReparented command to inform vitess of the current master.
-* `-master_connect_retry`: This value is give to mysql when it connects a slave to the master as the retry duration parameter.
-* `-enable_replication_reporter`: If this flag is set, then vttablet will transmit replica lag related information to the vtgates, which will allow it to balance load better. Additionally, enabling this will also cause vttablet to restart replication if it was stopped. However, it will do this only if -disable_active_reparents was not turned on.
-* `-enable_semi_sync`: This option will automatically enable semi-sync on new replicas as well as on any tablet that transitions into a replica type. This includes the demotion of a master to a replica.
-* `-heatbeat_enable` and `-heartbeat_interval_duration`: cause vttablet to write heartbeats to the sidecar database. This information is also used by the replication reporter to assess replica lag.
-
-## Typical vttablet command line flags
-
-### Minimal vttablet to enable query serving
-```
-$TOPOLOGY_FLAGS
--tablet-path $alias
--init_keyspace $keyspace
--init_shard $shard
--init_tablet_type $tablet_type
--port $port
--grpc_port $grpc_port
--service_map 'grpc-queryservice,grpc-tabletmanager,grpc-updatestream'
-```
-
-$alias needs to be of the form: `-id`, and the cell should match one of the local cells that was created in the topology. The id can be left padded with zeroes: `cell-100` and `cell-000000100` are synonymous.
-
-Example TOPOLOGY\_FLAGS for a lockserver like zookeeper:
-
-`-topo_implementation zk2 -topo_global_server_address localhost:21811,localhost:21812,localhost:21813 -topo_global_root /vitess/global`
-
-### Additional parameters to enable cluster management
-```
--enable_semi_sync
--enable_replication_reporter
--backup_storage_implementation file
--file_backup_storage_root $BACKUP_MOUNT
--restore_from_backup
--vtctld_addr http://$hostname:$vtctld_web_port/
-```
-
-### Additional parameters for running in prod
-
-```
--queryserver-config-pool-size 24
--queryserver-config-stream-pool-size 24
--queryserver-config-transaction-cap 300
-```
-
-More tuning parameters are available, but the above overrides are definitely needed for serving reasonable production traffic.
-
-### Connecting vttablet to an already running mysql
-
-```
--db_host $MYSQL_HOST
--db_port $MYSQL_PORT
--db_app_user $USER
--db_app_password $PASSWORD
-```
-
-### Additional user credentials that need to be supplied for performing various operations
-
-```
--db_allprivs_user
--db_allprivs_password
--db_appdebug_user
--db_appdebug_password
--db_dba_user
--db_dba_password
--db_filtered_user
--db_filtered_password
-```
-
-Other flags exist for finer control.
diff --git a/doc/VTTabletModules.png b/doc/VTTabletModules.png
deleted file mode 100644
index 7d107faa703..00000000000
Binary files a/doc/VTTabletModules.png and /dev/null differ
diff --git a/doc/VitessApi.md b/doc/VitessApi.md
deleted file mode 100644
index 61b5ffc10a9..00000000000
--- a/doc/VitessApi.md
+++ /dev/null
@@ -1,1033 +0,0 @@
-This document describes Vitess API methods that enable your client application to more easily talk to your storage system to query data. API methods are grouped into the following categories:
-
-* [Range-based Sharding](#range-based-sharding)
-* [Transactions](#transactions)
-* [Custom Sharding](#custom-sharding)
-* [Map Reduce](#map-reduce)
-* [Topology](#topology)
-* [v3 API (alpha)](#v3-api-(alpha))
-
-
-The following table lists the methods in each group and links to more detail about each method:
-
-
GetSrvKeyspace returns a SrvKeyspace object (as seen by this vtgate). This method is provided as a convenient way for clients to take a look at the sharding configuration for a Keyspace. Looking at the sharding information should not be used for routing queries (as the information may change, use the Execute calls for that). It is convenient for monitoring applications for instance, or if using custom sharding.
Execute tries to route the query to the right shard. It depends on the query and bind variables to provide enough information in conjunction with the vindexes to route the query.
StreamExecute executes a streaming query based on shards. It depends on the query and bind variables to provide enough information in conjunction with the vindexes to route the query. Use this method if the query returns a large number of rows.
-
-
-##Range-based Sharding
-### ExecuteBatchKeyspaceIds
-
-ExecuteBatchKeyspaceIds executes the list of queries based on the specified keyspace ids.
-
-#### Request
-
- ExecuteBatchKeyspaceIdsRequest is the payload to ExecuteBatchKeyspaceId.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| queries list <[BoundKeyspaceIdQuery](#boundkeyspaceidquery)>| BoundKeyspaceIdQuery represents a single query request for the specified list of keyspace ids. This is used in a list for ExecuteBatchKeyspaceIdsRequest. |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| as_transaction bool| as_transaction will execute the queries in this batch in a single transaction per shard, created for this purpose. (this can be seen as adding a 'begin' before and 'commit' after the queries). Only makes sense if tablet_type is master. If set, the Session is ignored. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Response
-
- ExecuteBatchKeyspaceIdsResponse is the returned value from ExecuteBatchKeyspaceId.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| error [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| results list <[query.QueryResult](#query.queryresult)>| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-### ExecuteEntityIds
-
-ExecuteEntityIds executes the query based on the specified external id to keyspace id map.
-
-#### Request
-
- ExecuteEntityIdsRequest is the payload to ExecuteEntityIds.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| keyspace string| keyspace to target the query to. |
-| entity_column_name string| entity_column_name is the column name to use. |
-| entity_keyspace_ids list <[EntityId](#executeentityidsrequest.entityid)>| entity_keyspace_ids are pairs of entity_column_name values associated with its corresponding keyspace_id. |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| not_in_transaction bool| not_in_transaction is deprecated and should not be used. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Messages
-
-##### ExecuteEntityIdsRequest.EntityId
-
-Properties
-
-| Name |Description |
-| :-------- | :--------
-| type [query.Type](#query.type)| Type defines the various supported data types in bind vars and query results. |
-| value bytes| value is the value for the entity. Not set if type is NULL_TYPE. |
-| keyspace_id bytes| keyspace_id is the associated keyspace_id for the entity. |
-
-#### Response
-
- ExecuteEntityIdsResponse is the returned value from ExecuteEntityIds.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| error [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| result [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-### ExecuteKeyRanges
-
-ExecuteKeyRanges executes the query based on the specified key ranges.
-
-#### Request
-
- ExecuteKeyRangesRequest is the payload to ExecuteKeyRanges.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| keyspace string| keyspace to target the query to |
-| key_ranges list <[topodata.KeyRange](#topodata.keyrange)>| KeyRange describes a range of sharding keys, when range-based sharding is used. |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| not_in_transaction bool| not_in_transaction is deprecated and should not be used. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Response
-
- ExecuteKeyRangesResponse is the returned value from ExecuteKeyRanges.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| error [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| result [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-### ExecuteKeyspaceIds
-
-ExecuteKeyspaceIds executes the query based on the specified keyspace ids.
-
-#### Request
-
- ExecuteKeyspaceIdsRequest is the payload to ExecuteKeyspaceIds.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| keyspace string| keyspace to target the query to. |
-| keyspace_ids list <bytes>| keyspace_ids contains the list of keyspace_ids affected by this query. Will be used to find the shards to send the query to. |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| not_in_transaction bool| not_in_transaction is deprecated and should not be used. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Response
-
- ExecuteKeyspaceIdsResponse is the returned value from ExecuteKeyspaceIds.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| error [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| result [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-### StreamExecuteKeyRanges
-
-StreamExecuteKeyRanges executes a streaming query based on key ranges. Use this method if the query returns a large number of rows.
-
-#### Request
-
- StreamExecuteKeyRangesRequest is the payload to StreamExecuteKeyRanges.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| keyspace string| keyspace to target the query to. |
-| key_ranges list <[topodata.KeyRange](#topodata.keyrange)>| KeyRange describes a range of sharding keys, when range-based sharding is used. |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Response
-
- StreamExecuteKeyRangesResponse is the returned value from StreamExecuteKeyRanges.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| result [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-### StreamExecuteKeyspaceIds
-
-StreamExecuteKeyspaceIds executes a streaming query based on keyspace ids. Use this method if the query returns a large number of rows.
-
-#### Request
-
- StreamExecuteKeyspaceIdsRequest is the payload to StreamExecuteKeyspaceIds.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| keyspace string| keyspace to target the query to. |
-| keyspace_ids list <bytes>| keyspace_ids contains the list of keyspace_ids affected by this query. Will be used to find the shards to send the query to. |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Response
-
- StreamExecuteKeyspaceIdsResponse is the returned value from StreamExecuteKeyspaceIds.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| result [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-##Transactions
-### Begin
-
-Begin a transaction.
-
-#### Request
-
- BeginRequest is the payload to Begin.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| single_db bool| single_db specifies if the transaction should be restricted to a single database. |
-
-#### Response
-
- BeginResponse is the returned value from Begin.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-
-### Commit
-
-Commit a transaction.
-
-#### Request
-
- CommitRequest is the payload to Commit.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| atomic bool| atomic specifies if the commit should go through the 2PC workflow to ensure atomicity. |
-
-#### Response
-
- CommitResponse is the returned value from Commit.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-
-### ResolveTransaction
-
-ResolveTransaction resolves a transaction.
-
-#### Request
-
- ResolveTransactionRequest is the payload to ResolveTransaction.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| dtid string| dtid is the dtid of the transaction to be resolved. |
-
-#### Response
-
- ResolveTransactionResponse is the returned value from Rollback.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-
-### Rollback
-
-Rollback a transaction.
-
-#### Request
-
- RollbackRequest is the payload to Rollback.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-
-#### Response
-
- RollbackResponse is the returned value from Rollback.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-
-##Custom Sharding
-### ExecuteBatchShards
-
-ExecuteBatchShards executes the list of queries on the specified shards.
-
-#### Request
-
- ExecuteBatchShardsRequest is the payload to ExecuteBatchShards
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| queries list <[BoundShardQuery](#boundshardquery)>| BoundShardQuery represents a single query request for the specified list of shards. This is used in a list for ExecuteBatchShardsRequest. |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| as_transaction bool| as_transaction will execute the queries in this batch in a single transaction per shard, created for this purpose. (this can be seen as adding a 'begin' before and 'commit' after the queries). Only makes sense if tablet_type is master. If set, the Session is ignored. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Response
-
- ExecuteBatchShardsResponse is the returned value from ExecuteBatchShards.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| error [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| results list <[query.QueryResult](#query.queryresult)>| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-### ExecuteShards
-
-ExecuteShards executes the query on the specified shards.
-
-#### Request
-
- ExecuteShardsRequest is the payload to ExecuteShards.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| keyspace string| keyspace to target the query to. |
-| shards list <string>| shards to target the query to. A DML can only target one shard. |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| not_in_transaction bool| not_in_transaction is deprecated and should not be used. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Response
-
- ExecuteShardsResponse is the returned value from ExecuteShards.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| error [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| result [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-### StreamExecuteShards
-
-StreamExecuteShards executes a streaming query based on shards. Use this method if the query returns a large number of rows.
-
-#### Request
-
- StreamExecuteShardsRequest is the payload to StreamExecuteShards.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| keyspace string| keyspace to target the query to. |
-| shards list <string>| shards to target the query to. |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Response
-
- StreamExecuteShardsResponse is the returned value from StreamExecuteShards.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| result [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-##Map Reduce
-### SplitQuery
-
-Split a query into non-overlapping sub queries
-
-#### Request
-
- SplitQueryRequest is the payload to SplitQuery. SplitQuery takes a "SELECT" query and generates a list of queries called "query-parts". Each query-part consists of the original query with an added WHERE clause that restricts the query-part to operate only on rows whose values in the columns listed in the "split_column" field of the request (see below) are in a particular range. It is guaranteed that the set of rows obtained from executing each query-part on a database snapshot and merging (without deduping) the results is equal to the set of rows obtained from executing the original query on the same snapshot with the rows containing NULL values in any of the split_column's excluded. This is typically called by the MapReduce master when reading from Vitess. There it's desirable that the sets of rows returned by the query-parts have roughly the same size.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| keyspace string| keyspace to target the query to. |
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| split_column list <string>| Each generated query-part will be restricted to rows whose values in the columns listed in this field are in a particular range. The list of columns named here must be a prefix of the list of columns defining some index or primary key of the table referenced in 'query'. For many tables using the primary key columns (in order) is sufficient and this is the default if this field is omitted. See the comment on the 'algorithm' field for more restrictions and information. |
-| split_count int64| You can specify either an estimate of the number of query-parts to generate or an estimate of the number of rows each query-part should return. Thus, exactly one of split_count or num_rows_per_query_part should be nonzero. The non-given parameter is calculated from the given parameter using the formula: split_count * num_rows_per_query_pary = table_size, where table_size is an approximation of the number of rows in the table. Note that if "split_count" is given it is regarded as an estimate. The number of query-parts returned may differ slightly (in particular, if it's not a whole multiple of the number of vitess shards). |
-| num_rows_per_query_part int64| |
-| algorithm query.SplitQueryRequest.Algorithm| The algorithm to use to split the query. The split algorithm is performed on each database shard in parallel. The lists of query-parts generated by the shards are merged and returned to the caller. Two algorithms are supported: EQUAL_SPLITS If this algorithm is selected then only the first 'split_column' given is used (or the first primary key column if the 'split_column' field is empty). In the rest of this algorithm's description, we refer to this column as "the split column". The split column must have numeric type (integral or floating point). The algorithm works by taking the interval [min, max], where min and max are the minimum and maximum values of the split column in the table-shard, respectively, and partitioning it into 'split_count' sub-intervals of equal size. The added WHERE clause of each query-part restricts that part to rows whose value in the split column belongs to a particular sub-interval. This is fast, but requires that the distribution of values of the split column be uniform in [min, max] for the number of rows returned by each query part to be roughly the same. FULL_SCAN If this algorithm is used then the split_column must be the primary key columns (in order). This algorithm performs a full-scan of the table-shard referenced in 'query' to get "boundary" rows that are num_rows_per_query_part apart when the table is ordered by the columns listed in 'split_column'. It then restricts each query-part to the rows located between two successive boundary rows. This algorithm supports multiple split_column's of any type, but is slower than EQUAL_SPLITS. |
-| use_split_query_v2 bool| Remove this field after this new server code is released to prod. We must keep it for now, so that clients can still send it to the old server code currently in production. |
-
-#### Response
-
- SplitQueryResponse is the returned value from SplitQuery.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| splits list <[Part](#splitqueryresponse.part)>| splits contains the queries to run to fetch the entire data set. |
-
-#### Messages
-
-##### SplitQueryResponse.KeyRangePart
-
-Properties
-
-| Name |Description |
-| :-------- | :--------
-| keyspace string| keyspace to target the query to. |
-| key_ranges list <[topodata.KeyRange](#topodata.keyrange)>| KeyRange describes a range of sharding keys, when range-based sharding is used. |
-
-##### SplitQueryResponse.Part
-
-Properties
-
-| Name |Description |
-| :-------- | :--------
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| key_range_part [KeyRangePart](#splitqueryresponse.keyrangepart)| key_range_part is set if the query should be executed by ExecuteKeyRanges. |
-| shard_part [ShardPart](#splitqueryresponse.shardpart)| shard_part is set if the query should be executed by ExecuteShards. |
-| size int64| size is the approximate number of rows this query will return. |
-
-##### SplitQueryResponse.ShardPart
-
-Properties
-
-| Name |Description |
-| :-------- | :--------
-| keyspace string| keyspace to target the query to. |
-| shards list <string>| shards to target the query to. |
-
-##Topology
-### GetSrvKeyspace
-
-GetSrvKeyspace returns a SrvKeyspace object (as seen by this vtgate). This method is provided as a convenient way for clients to take a look at the sharding configuration for a Keyspace. Looking at the sharding information should not be used for routing queries (as the information may change, use the Execute calls for that). It is convenient for monitoring applications for instance, or if using custom sharding.
-
-#### Request
-
- GetSrvKeyspaceRequest is the payload to GetSrvKeyspace.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| keyspace string| keyspace name to fetch. |
-
-#### Response
-
- GetSrvKeyspaceResponse is the returned value from GetSrvKeyspace.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| srv_keyspace [topodata.SrvKeyspace](#topodata.srvkeyspace)| SrvKeyspace is a rollup node for the keyspace itself. |
-
-##v3 API (alpha)
-### Execute
-
-Execute tries to route the query to the right shard. It depends on the query and bind variables to provide enough information in conjunction with the vindexes to route the query.
-
-#### Request
-
- ExecuteRequest is the payload to Execute.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| not_in_transaction bool| not_in_transaction is deprecated and should not be used. |
-| keyspace string| keyspace to target the query to. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Response
-
- ExecuteResponse is the returned value from Execute.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| error [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. |
-| session [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. |
-| result [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-### StreamExecute
-
-StreamExecute executes a streaming query based on shards. It depends on the query and bind variables to provide enough information in conjunction with the vindexes to route the query. Use this method if the query returns a large number of rows.
-
-#### Request
-
- StreamExecuteRequest is the payload to StreamExecute.
-
-##### Parameters
-
-| Name |Description |
-| :-------- | :--------
-| caller_id [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. |
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-| keyspace string| keyspace to target the query to. |
-| options [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. |
-
-#### Response
-
- StreamExecuteResponse is the returned value from StreamExecute.
-
-##### Properties
-
-| Name |Description |
-| :-------- | :--------
-| result [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-## Enums
-
-### query.Type
-
- Type defines the various supported data types in bind vars and query results.
-
-| Name |Value |Description |
-| :-------- | :-------- | :--------
-| NULL_TYPE | 0 | NULL_TYPE specifies a NULL type. |
-| INT8 | 257 | INT8 specifies a TINYINT type. Properties: 1, IsNumber. |
-| UINT8 | 770 | UINT8 specifies a TINYINT UNSIGNED type. Properties: 2, IsNumber, IsUnsigned. |
-| INT16 | 259 | INT16 specifies a SMALLINT type. Properties: 3, IsNumber. |
-| UINT16 | 772 | UINT16 specifies a SMALLINT UNSIGNED type. Properties: 4, IsNumber, IsUnsigned. |
-| INT24 | 261 | INT24 specifies a MEDIUMINT type. Properties: 5, IsNumber. |
-| UINT24 | 774 | UINT24 specifies a MEDIUMINT UNSIGNED type. Properties: 6, IsNumber, IsUnsigned. |
-| INT32 | 263 | INT32 specifies a INTEGER type. Properties: 7, IsNumber. |
-| UINT32 | 776 | UINT32 specifies a INTEGER UNSIGNED type. Properties: 8, IsNumber, IsUnsigned. |
-| INT64 | 265 | INT64 specifies a BIGINT type. Properties: 9, IsNumber. |
-| UINT64 | 778 | UINT64 specifies a BIGINT UNSIGNED type. Properties: 10, IsNumber, IsUnsigned. |
-| FLOAT32 | 1035 | FLOAT32 specifies a FLOAT type. Properties: 11, IsFloat. |
-| FLOAT64 | 1036 | FLOAT64 specifies a DOUBLE or REAL type. Properties: 12, IsFloat. |
-| TIMESTAMP | 2061 | TIMESTAMP specifies a TIMESTAMP type. Properties: 13, IsQuoted. |
-| DATE | 2062 | DATE specifies a DATE type. Properties: 14, IsQuoted. |
-| TIME | 2063 | TIME specifies a TIME type. Properties: 15, IsQuoted. |
-| DATETIME | 2064 | DATETIME specifies a DATETIME type. Properties: 16, IsQuoted. |
-| YEAR | 785 | YEAR specifies a YEAR type. Properties: 17, IsNumber, IsUnsigned. |
-| DECIMAL | 18 | DECIMAL specifies a DECIMAL or NUMERIC type. Properties: 18, None. |
-| TEXT | 6163 | TEXT specifies a TEXT type. Properties: 19, IsQuoted, IsText. |
-| BLOB | 10260 | BLOB specifies a BLOB type. Properties: 20, IsQuoted, IsBinary. |
-| VARCHAR | 6165 | VARCHAR specifies a VARCHAR type. Properties: 21, IsQuoted, IsText. |
-| VARBINARY | 10262 | VARBINARY specifies a VARBINARY type. Properties: 22, IsQuoted, IsBinary. |
-| CHAR | 6167 | CHAR specifies a CHAR type. Properties: 23, IsQuoted, IsText. |
-| BINARY | 10264 | BINARY specifies a BINARY type. Properties: 24, IsQuoted, IsBinary. |
-| BIT | 2073 | BIT specifies a BIT type. Properties: 25, IsQuoted. |
-| ENUM | 2074 | ENUM specifies an ENUM type. Properties: 26, IsQuoted. |
-| SET | 2075 | SET specifies a SET type. Properties: 27, IsQuoted. |
-| TUPLE | 28 | TUPLE specifies a tuple. This cannot be returned in a QueryResult, but it can be sent as a bind var. Properties: 28, None. |
-| GEOMETRY | 2077 | GEOMETRY specifies a GEOMETRY type. Properties: 29, IsQuoted. |
-| JSON | 2078 | JSON specified a JSON type. Properties: 30, IsQuoted. |
-
-### topodata.KeyspaceIdType
-
- KeyspaceIdType describes the type of the sharding key for a range-based sharded keyspace.
-
-| Name |Value |Description |
-| :-------- | :-------- | :--------
-| UNSET | 0 | UNSET is the default value, when range-based sharding is not used. |
-| UINT64 | 1 | UINT64 is when uint64 value is used. This is represented as 'unsigned bigint' in mysql |
-| BYTES | 2 | BYTES is when an array of bytes is used. This is represented as 'varbinary' in mysql |
-
-### topodata.TabletType
-
- TabletType represents the type of a given tablet.
-
-| Name |Value |Description |
-| :-------- | :-------- | :--------
-| UNKNOWN | 0 | UNKNOWN is not a valid value. |
-| MASTER | 1 | MASTER is the master server for the shard. Only MASTER allows DMLs. |
-| REPLICA | 2 | REPLICA is a slave type. It is used to serve live traffic. A REPLICA can be promoted to MASTER. A demoted MASTER will go to REPLICA. |
-| RDONLY | 3 | RDONLY (old name) / BATCH (new name) is used to serve traffic for long-running jobs. It is a separate type from REPLICA so long-running queries don't affect web-like traffic. |
-| BATCH | 3 | |
-| SPARE | 4 | SPARE is a type of servers that cannot serve queries, but is available in case an extra server is needed. |
-| EXPERIMENTAL | 5 | EXPERIMENTAL is like SPARE, except it can serve queries. This type can be used for usages not planned by Vitess, like online export to another storage engine. |
-| BACKUP | 6 | BACKUP is the type a server goes to when taking a backup. No queries can be served in BACKUP mode. |
-| RESTORE | 7 | RESTORE is the type a server uses when restoring a backup, at startup time. No queries can be served in RESTORE mode. |
-| DRAINED | 8 | DRAINED is the type a server goes into when used by Vitess tools to perform an offline action. It is a serving type (as the tools processes may need to run queries), but it's not used to route queries from Vitess users. In this state, this tablet is dedicated to the process that uses it. |
-
-### vtrpc.ErrorCode
-
- ErrorCode is the enum values for Errors. Internally, errors should be created with one of these codes. These will then be translated over the wire by various RPC frameworks.
-
-| Name |Value |Description |
-| :-------- | :-------- | :--------
-| SUCCESS | 0 | SUCCESS is returned from a successful call. |
-| CANCELLED | 1 | CANCELLED means that the context was cancelled (and noticed in the app layer, as opposed to the RPC layer). |
-| UNKNOWN_ERROR | 2 | UNKNOWN_ERROR includes: 1. MySQL error codes that we don't explicitly handle. 2. MySQL response that wasn't as expected. For example, we might expect a MySQL timestamp to be returned in a particular way, but it wasn't. 3. Anything else that doesn't fall into a different bucket. |
-| BAD_INPUT | 3 | BAD_INPUT is returned when an end-user either sends SQL that couldn't be parsed correctly, or tries a query that isn't supported by Vitess. |
-| DEADLINE_EXCEEDED | 4 | DEADLINE_EXCEEDED is returned when an action is taking longer than a given timeout. |
-| INTEGRITY_ERROR | 5 | INTEGRITY_ERROR is returned on integrity error from MySQL, usually due to duplicate primary keys. |
-| PERMISSION_DENIED | 6 | PERMISSION_DENIED errors are returned when a user requests access to something that they don't have permissions for. |
-| RESOURCE_EXHAUSTED | 7 | RESOURCE_EXHAUSTED is returned when a query exceeds its quota in some dimension and can't be completed due to that. Queries that return RESOURCE_EXHAUSTED should not be retried, as it could be detrimental to the server's health. Examples of errors that will cause the RESOURCE_EXHAUSTED code: 1. TxPoolFull: this is retried server-side, and is only returned as an error if the server-side retries failed. 2. Query is killed due to it taking too long. |
-| QUERY_NOT_SERVED | 8 | QUERY_NOT_SERVED means that a query could not be served right now. Client can interpret it as: "the tablet that you sent this query to cannot serve the query right now, try a different tablet or try again later." This could be due to various reasons: QueryService is not serving, should not be serving, wrong shard, wrong tablet type, blacklisted table, etc. Clients that receive this error should usually retry the query, but after taking the appropriate steps to make sure that the query will get sent to the correct tablet. |
-| NOT_IN_TX | 9 | NOT_IN_TX means that we're not currently in a transaction, but we should be. |
-| INTERNAL_ERROR | 10 | INTERNAL_ERRORs are problems that only the server can fix, not the client. These errors are not due to a query itself, but rather due to the state of the system. Generally, we don't expect the errors to go away by themselves, but they may go away after human intervention. Examples of scenarios where INTERNAL_ERROR is returned: 1. Something is not configured correctly internally. 2. A necessary resource is not available, and we don't expect it to become available by itself. 3. A sanity check fails. 4. Some other internal error occurs. Clients should not retry immediately, as there is little chance of success. However, it's acceptable for retries to happen internally, for example to multiple backends, in case only a subset of backend are not functional. |
-| TRANSIENT_ERROR | 11 | TRANSIENT_ERROR is used for when there is some error that we expect we can recover from automatically - often due to a resource limit temporarily being reached. Retrying this error, with an exponential backoff, should succeed. Clients should be able to successfully retry the query on the same backends. Examples of things that can trigger this error: 1. Query has been throttled 2. VtGate could have request backlog |
-| UNAUTHENTICATED | 12 | UNAUTHENTICATED errors are returned when a user requests access to something, and we're unable to verify the user's authentication. |
-
-## Messages
-
-### BoundKeyspaceIdQuery
-
-BoundKeyspaceIdQuery represents a single query request for the specified list of keyspace ids. This is used in a list for ExecuteBatchKeyspaceIdsRequest.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| keyspace string| keyspace to target the query to. |
-| keyspace_ids list <bytes>| keyspace_ids contains the list of keyspace_ids affected by this query. Will be used to find the shards to send the query to. |
-
-### BoundShardQuery
-
-BoundShardQuery represents a single query request for the specified list of shards. This is used in a list for ExecuteBatchShardsRequest.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| query [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables |
-| keyspace string| keyspace to target the query to. |
-| shards list <string>| shards to target the query to. A DML can only target one shard. |
-
-### Session
-
-Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| in_transaction bool| |
-| shard_sessions list <[ShardSession](#session.shardsession)>| |
-| single_db bool| single_db specifies if the transaction should be restricted to a single database. |
-
-#### Messages
-
-##### Session.ShardSession
-
-Properties
-
-| Name |Description |
-| :-------- | :--------
-| target [query.Target](#query.target)| Target describes what the client expects the tablet is. If the tablet does not match, an error is returned. |
-| transaction_id int64| |
-
-### query.BindVariable
-
-BindVariable represents a single bind variable in a Query.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| type [Type](#query.type)| |
-| value bytes| |
-| values list <[Value](#query.value)>| Value represents a typed value. |
-
-### query.BoundQuery
-
-BoundQuery is a query with its bind variables
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| sql string| sql is the SQL query to execute |
-| bind_variables map <string, [BindVariable](#query.bindvariable)>| bind_variables is a map of all bind variables to expand in the query |
-
-### query.EventToken
-
-EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| timestamp int64| timestamp is the MySQL timestamp of the statements. Seconds since Epoch. |
-| shard string| The shard name that applied the statements. Note this is not set when streaming from a vttablet. It is only used on the client -> vtgate link. |
-| position string| The position on the replication stream after this statement was applied. It is not the transaction ID / GTID, but the position / GTIDSet. |
-
-### query.ExecuteOptions
-
-ExecuteOptions is passed around for all Execute calls.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| include_event_token bool| This used to be exclude_field_names, which was replaced by IncludedFields enum below If set, we will try to include an EventToken with the responses. |
-| compare_event_token [EventToken](#query.eventtoken)| EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. |
-| included_fields [IncludedFields](#executeoptions.includedfields)| Controls what fields are returned in Field message responses from mysql, i.e. field name, table name, etc. This is an optimization for high-QPS queries where the client knows what it's getting |
-
-#### Enums
-
-##### ExecuteOptions.IncludedFields
-
-| Name |Value |Description |
-| :-------- | :-------- | :--------
-| TYPE_AND_NAME | 0 | |
-| TYPE_ONLY | 1 | |
-| ALL | 2 | |
-
-### query.Field
-
-Field describes a single column returned by a query
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| name string| name of the field as returned by mysql C API |
-| type [Type](#query.type)| vitess-defined type. Conversion function is in sqltypes package. |
-| table string| Remaining fields from mysql C API. These fields are only populated when ExecuteOptions.included_fields is set to IncludedFields.ALL. |
-| org_table string| |
-| database string| |
-| org_name string| |
-| column_length uint32| column_length is really a uint32. All 32 bits can be used. |
-| charset uint32| charset is actually a uint16. Only the lower 16 bits are used. |
-| decimals uint32| decimals is actually a uint8. Only the lower 8 bits are used. |
-| flags uint32| flags is actually a uint16. Only the lower 16 bits are used. |
-
-### query.QueryResult
-
-QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]).
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| fields list <[Field](#query.field)>| Field describes a single column returned by a query |
-| rows_affected uint64| |
-| insert_id uint64| |
-| rows list <[Row](#query.row)>| Row is a database row. |
-| extras [ResultExtras](#query.resultextras)| ResultExtras contains optional out-of-band information. Usually the extras are requested by adding ExecuteOptions flags. |
-
-### query.ResultExtras
-
-ResultExtras contains optional out-of-band information. Usually the extras are requested by adding ExecuteOptions flags.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| event_token [EventToken](#query.eventtoken)| EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. |
-| fresher bool| If set, it means the data returned with this result is fresher than the compare_token passed in the ExecuteOptions. |
-
-### query.ResultWithError
-
-ResultWithError represents a query response in the form of result or error but not both.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| error [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. |
-| result [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). |
-
-### query.Row
-
-Row is a database row.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| lengths list <sint64>| lengths contains the length of each value in values. A length of -1 means that the field is NULL. While reading values, you have to accummulate the length to know the offset where the next value begins in values. |
-| values bytes| values contains a concatenation of all values in the row. |
-
-### query.StreamEvent
-
-StreamEvent describes a set of transformations that happened as a single transactional unit on a server. It is streamed back by the Update Stream calls.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| statements list <[Statement](#streamevent.statement)>| The statements in this transaction. |
-| event_token [EventToken](#query.eventtoken)| EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. |
-
-#### Messages
-
-##### StreamEvent.Statement
-
-One individual Statement in a transaction.
-
-Properties
-
-| Name |Description |
-| :-------- | :--------
-| category [Category](#streamevent.statement.category)| |
-| table_name string| table_name, primary_key_fields and primary_key_values are set for DML. |
-| primary_key_fields list <[Field](#query.field)>| Field describes a single column returned by a query |
-| primary_key_values list <[Row](#query.row)>| Row is a database row. |
-| sql bytes| sql is set for all queries. FIXME(alainjobart) we may not need it for DMLs. |
-
-#### Enums
-
-##### StreamEvent.Statement.Category
-
- One individual Statement in a transaction. The category of one statement.
-
-| Name |Value |Description |
-| :-------- | :-------- | :--------
-| Error | 0 | |
-| DML | 1 | |
-| DDL | 2 | |
-
-### query.Target
-
-Target describes what the client expects the tablet is. If the tablet does not match, an error is returned.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| keyspace string| |
-| shard string| |
-| tablet_type [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. |
-
-### query.Value
-
-Value represents a typed value.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| type [Type](#query.type)| |
-| value bytes| |
-
-### topodata.KeyRange
-
-KeyRange describes a range of sharding keys, when range-based sharding is used.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| start bytes| |
-| end bytes| |
-
-### topodata.ShardReference
-
-ShardReference is used as a pointer from a SrvKeyspace to a Shard
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| name string| Copied from Shard. |
-| key_range [KeyRange](#topodata.keyrange)| KeyRange describes a range of sharding keys, when range-based sharding is used. |
-
-### topodata.SrvKeyspace
-
-SrvKeyspace is a rollup node for the keyspace itself.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| partitions list <[KeyspacePartition](#srvkeyspace.keyspacepartition)>| The partitions this keyspace is serving, per tablet type. |
-| sharding_column_name string| copied from Keyspace |
-| sharding_column_type [KeyspaceIdType](#topodata.keyspaceidtype)| |
-| served_from list <[ServedFrom](#srvkeyspace.servedfrom)>| |
-
-#### Messages
-
-##### SrvKeyspace.KeyspacePartition
-
-Properties
-
-| Name |Description |
-| :-------- | :--------
-| served_type [TabletType](#topodata.tablettype)| The type this partition applies to. |
-| shard_references list <[ShardReference](#topodata.shardreference)>| ShardReference is used as a pointer from a SrvKeyspace to a Shard |
-
-##### SrvKeyspace.ServedFrom
-
-ServedFrom indicates a relationship between a TabletType and the keyspace name that's serving it.
-
-Properties
-
-| Name |Description |
-| :-------- | :--------
-| tablet_type [TabletType](#topodata.tablettype)| ServedFrom indicates a relationship between a TabletType and the keyspace name that's serving it. the tablet type |
-| keyspace string| the keyspace name that's serving it |
-
-### vtrpc.CallerID
-
-CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| principal string| principal is the effective user identifier. It is usually filled in with whoever made the request to the appserver, if the request came from an automated job or another system component. If the request comes directly from the Internet, or if the Vitess client takes action on its own accord, it is okay for this field to be absent. |
-| component string| component describes the running process of the effective caller. It can for instance be the hostname:port of the servlet initiating the database call, or the container engine ID used by the servlet. |
-| subcomponent string| subcomponent describes a component inisde the immediate caller which is responsible for generating is request. Suggested values are a servlet name or an API endpoint name. |
-
-### vtrpc.RPCError
-
-RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code.
-
-#### Properties
-
-| Name |Description |
-| :-------- | :--------
-| code [ErrorCode](#vtrpc.errorcode)| |
-| message string| |
-
diff --git a/doc/VitessComponents.png b/doc/VitessComponents.png
deleted file mode 100644
index 73e90422153..00000000000
Binary files a/doc/VitessComponents.png and /dev/null differ
diff --git a/doc/VitessOverview.md b/doc/VitessOverview.md
deleted file mode 100644
index dc66784b9da..00000000000
--- a/doc/VitessOverview.md
+++ /dev/null
@@ -1,239 +0,0 @@
-Vitess is a database solution for deploying, scaling and managing large clusters of MySQL instances.
-It's architected to run as effectively in a public or private cloud architecture as it does
-on dedicated hardware. It combines and extends many important MySQL features with the
-scalability of a NoSQL database. Vitess can help you with the following problems:
-
-1. Scaling a MySQL database by allowing you to shard it, while keeping application changes to a minimum.
-2. Migrating from baremetal to a private or public cloud.
-3. Deploying and managing a large number of MySQL instances.
-
-Vitess includes compliant JDBC and Go database drivers using a native query protocol. Additionally, it implements the MySQL server protocol which is compatible with virtually any other language.
-
-Vitess has been serving all YouTube database traffic since 2011, and has now been adopted by many enterprises for their production needs.
-
-## Features
-
-* **Performance**
- * Connection pooling - Multiplex front-end application queries onto a pool of MySQL connections to optimize performance.
- * Query de-duping – Reuse results of an in-flight query for any identical requests received while the in-flight query was still executing.
- * Transaction manager – Limit number of concurrent transactions and manage deadlines to optimize overall throughput.
-
-* **Protection**
- * Query rewriting and sanitization – Add limits and avoid non-deterministic updates.
- * Query blacklisting – Customize rules to prevent potentially problematic queries from hitting your database.
- * Query killer – Terminate queries that take too long to return data.
- * Table ACLs – Specify access control lists (ACLs) for tables based on the connected user.
-
-* **Monitoring**
- * Performance analysis: Tools let you monitor, diagnose, and analyze your database performance.
- * Query streaming – Use a list of incoming queries to serve OLAP workloads.
- * Update stream – A server streams the list of rows changing in the database, which can be used as a mechanism to propagate changes to other data stores.
-
-* **Topology Management Tools**
- * Master management tools (handles reparenting)
- * Web-based management GUI
- * Designed to work in multiple data centers / regions
-
-* **Sharding**
- * Virtually seamless dynamic re-sharding
- * Vertical and Horizontal sharding support
- * Multiple sharding schemes, with the ability to plug-in custom ones
-
-## Comparisons to other storage options
-
-The following sections compare Vitess to two common alternatives, a vanilla MySQL implementation and a NoSQL implementation.
-
-### Vitess vs. Vanilla MySQL
-
-Vitess improves a vanilla MySQL implementation in several ways:
-
-
-
-
-
Vanilla MySQL
-
Vitess
-
-
-
-
-
Every MySQL connection has a memory overhead that ranges between 256KB and almost 3MB, depending on which MySQL release you're using. As your user base grows, you need to add RAM to support additional connections, but the RAM does not contribute to faster queries. In addition, there is a significant CPU cost associated with obtaining the connections.
-
Vitess' gRPC-based protocol creates very lightweight connections. Vitess' connection pooling feature uses Go's concurrency support to map these lightweight connections to a small pool of MySQL connections. As such, Vitess can easily handle thousands of connections.
-
-
-
Poorly written queries, such as those that don't set a LIMIT, can negatively impact database performance for all users.
-
Vitess employs a SQL parser that uses a configurable set of rules to rewrite queries that might hurt database performance.
-
-
-
Sharding is a process of partitioning your data to improve scalability and performance. MySQL lacks native sharding support, requiring you to write sharding code and embed sharding logic in your application.
-
Vitess supports a variety of sharding schemes. It can also migrate tables into different databases and scale up or down the number of shards. These functions are performed non-intrusively, completing most data transitions with just a few seconds of read-only downtime.
-
-
-
A MySQL cluster using replication for availability has a master database and a few replicas. If the master fails, a replica should become the new master. This requires you to manage the database lifecycle and communicate the current system state to your application.
-
Vitess helps to manage the lifecycle of your database scenarios. It supports and automatically handles various scenarios, including master failover and data backups.
-
-
-
A MySQL cluster can have custom database configurations for different workloads, like a master database for writes, fast read-only replicas for web clients, slower read-only replicas for batch jobs, and so forth. If the database has horizontal sharding, the setup is repeated for each shard, and the app needs baked-in logic to know how to find the right database.
-
Vitess uses a topology backed by a consistent data store, like etcd or ZooKeeper. This means the cluster view is always up-to-date and consistent for different clients. Vitess also provides a proxy that routes queries efficiently to the most appropriate MySQL instance.
-
-
-
-
-### Vitess vs. NoSQL
-
-If you're considering a NoSQL solution primarily because of concerns about the scalability of MySQL, Vitess might be a more appropriate choice for your application. While NoSQL provides great support for unstructured data, Vitess still offers several benefits not available in NoSQL datastores:
-
-
-
-
-
NoSQL
-
Vitess
-
-
-
-
-
NoSQL databases do not define relationships between database tables, and only support a subset of the SQL language.
-
Vitess is not a simple key-value store. It supports complex query semantics such as where clauses, JOINS, aggregation functions, and more.
-
-
-
NoSQL datastores do not support transactions.
-
Vitess supports transactions within a shard. For transactions that span multiple shards, it allows you to optionally enable 2PC.
-
-
-
NoSQL solutions have custom APIs, leading to custom architectures, applications, and tools.
-
Vitess adds very little variance to MySQL, a database that most people are already accustomed to working with.
-
-
-
NoSQL solutions provide limited support for database indexes compared to MySQL.
-
Vitess allows you to use all of MySQL's indexing functionality to optimize query performance.
-
-
-
-
-## Architecture
-
-The Vitess platform consists of a number of server processes, command-line utilities, and web-based utilities, backed by a consistent metadata store.
-
-Depending on the current state of your application, you could arrive at a full Vitess implementation through a number of different process flows. For example, if you're building a service from scratch, your first step with Vitess would be to define your database topology. However, if you need to scale your existing database, you'd likely start by deploying a connection proxy.
-
-Vitess tools and servers are designed to help you whether you start with a complete fleet of databases or start small and scale over time. For smaller implementations, vttablet features like connection pooling and query rewriting help you get more from your existing hardware. Vitess' automation tools then provide additional benefits for larger implementations.
-
-The diagram below illustrates Vitess' components:
-
-
-
-
-
-### Topology
-
-The [Topology Service]({% link user-guide/topology-service.md %}) is a metadata store that contains information about running servers, the sharding scheme, and the replication graph. The topology is backed by a consistent data store. You can explore the topology using **vtctl** (command-line) and **vtctld** (web).
-
-In Kubernetes, the data store is [etcd](https://github.com/coreos/etcd). Vitess source code also ships with [Apache ZooKeeper](https://zookeeper.apache.org/) support.
-
-### vtgate
-
-**vtgate** is a light proxy server that routes traffic to the correct vttablet(s) and returns consolidated results back to the client. It is the server to which applications send queries. Thus, the client can be very simple since it only needs to be able to find a vtgate instance.
-
-To route queries, vtgate considers the sharding scheme, required latency, and the availability of the tablets and their underlying MySQL instances.
-
-### vttablet
-
-**vttablet** is a proxy server that sits in front of a MySQL database. A Vitess implementation has one vttablet for each MySQL instance.
-
-vttablet performs tasks that attempt to maximize throughput as well as protect MySQL from harmful queries. Its features include connection pooling, query rewriting, and query de-duping. In addition, vttablet executes management tasks that vtctl initiates, and it provides streaming services that are used for [filtered replication]({% link user-guide/sharding.md %}#filtered-replication) and data exports.
-
-A lightweight Vitess implementation uses vttablet as a smart connection proxy that serves queries for a single MySQL database. By running vttablet in front of your MySQL database and changing your app to use the Vitess client instead of your MySQL driver, your app benefits from vttablet's connection pooling, query rewriting, and query de-duping features.
-
-### vtctl
-
-**vtctl** is a command-line tool used to administer a Vitess cluster. It allows a human or application to easily interact with a Vitess implementation. Using vtctl, you can identify master and replica databases, create tables, initiate failovers, perform sharding (and resharding) operations, and so forth.
-
-As vtctl performs operations, it updates the lockserver as needed. Other Vitess servers observe those changes and react accordingly. For example, if you use vtctl to fail over to a new master database, vtgate sees the change and directs future write operations to the new master.
-
-### vtctld
-
-**vtctld** is an HTTP server that lets you browse the information stored in the lockserver. It is useful for troubleshooting or for getting a high-level overview of the servers and their current states.
-
-### vtworker
-
-**vtworker** hosts long-running processes. It supports a plugin architecture and offers libraries so that you can easily choose tablets to use. Plugins are available for the following types of jobs:
-
-* **resharding differ** jobs check data integrity during shard splits and joins
-* **vertical split differ** jobs check data integrity during vertical splits and joins
-
-vtworker also lets you easily add other validation procedures. You could do in-tablet integrity checks to verify foreign-key-like relationships or cross-shard integrity checks if, for example, an index table in one keyspace references data in another keyspace.
-
-### Other support tools
-
-Vitess also includes the following tools:
-
-* **mysqlctl**: Manage MySQL instances
-* **vtcombo**: A single binary that contains all components of Vitess. It can be used for testing queries in a Continuous Integration environment.
-* **vtexplain**: A command line tool that is used to explore how Vitess will handle queries based on a user-supplied schema and topology, without needing to set up a full cluster.
-* **zk**: Command-line ZooKeeper client and explorer
-* **zkctl**: Manage ZooKeeper instances
-
-## Vitess on Kubernetes
-
-[Kubernetes](https://kubernetes.io/) is an open-source orchestration system for Docker containers, and Vitess can run as a Kubernetes-aware cloud native distributed database.
-
-Kubernetes handles scheduling onto nodes in a compute cluster, actively manages workloads on those nodes, and groups containers comprising an application for easy management and discovery.
-This provides an analogous open-source environment to the way Vitess runs in YouTube,
-on the [predecessor to Kubernetes](https://kubernetes.io/blog/2015/04/borg-predecessor-to-kubernetes/).
-
-The easiest way to run Vitess is via Kubernetes. However, it's not a requirement, and other types of deployment are used as well.
-
-
-
-## History
-
-Vitess has been a fundamental component of YouTube infrastructure since 2011.
-This section briefly summarizes the sequence of events that led to Vitess'
-creation:
-
-1. YouTube's MySQL database reached a point when peak traffic would soon
- exceed the database's serving capacity. To temporarily alleviate the
- problem, YouTube created a master database for write traffic and a
- replica database for read traffic.
-1. With demand for cat videos at an all-time high, read-only traffic was
- still high enough to overload the replica database. So YouTube added
- more replicas, again providing a temporary solution.
-1. Eventually, write traffic became too high for the master database to
- handle, requiring YouTube to shard data to handle incoming traffic.
- (Sharding would have also become necessary if the overall size of the
- database became too large for a single MySQL instance.)
-1. YouTube's application layer was modified so that before executing any
- database operation, the code could identify the right database shard
- to receive that particular query.
-
-Vitess let YouTube remove that logic from the source code, introducing
-a proxy between the application and the database to route and manage
-database interactions. Since then, YouTube has scaled its user base
-by a factor of more than 50, greatly increasing its capacity to serve
-pages, process newly uploaded videos, and more. Even more importantly,
-Vitess is a platform that continues to scale.
-
-YouTube chose to write Vitess in Go because Go offers a combination of
-expressiveness and performance. It is almost as expressive as Python and
-very maintainable. However, its performance is in the same range as Java
-and close to C++ in certain cases. In addition, the language is extremely
-well suited for concurrent programming and has a very high quality
-standard library.
-
-### Open Source First
-
-The open source version of Vitess is extremely similar to the version
-used at YouTube. While there are some changes that let YouTube take
-advantage of Google's infrastructure, the core functionality is the same.
-When developing new features, the Vitess team first makes them work in
-the Open Source tree. In some cases, the team then writes a plugin
-that makes use of Google-specific technology. This approach ensures that
-the Open Source version of Vitess maintains the same level of quality as
-the internal version.
-
-The vast majority of Vitess development takes place in the open, on GitHub.
-As such, Vitess is built with extensibility in mind so that you can adjust
-it to the needs of your infrastructure.
diff --git a/doc/VitessOverview.png b/doc/VitessOverview.png
deleted file mode 100644
index e8e1b17fc19..00000000000
Binary files a/doc/VitessOverview.png and /dev/null differ
diff --git a/doc/VitessReplication.md b/doc/VitessReplication.md
deleted file mode 100644
index 7e7ad213c91..00000000000
--- a/doc/VitessReplication.md
+++ /dev/null
@@ -1,162 +0,0 @@
-# Vitess, MySQL Replication, and Schema Changes
-
-## Statement vs Row Based Replication
-
-MySQL supports two primary modes of replication in its binary logs: statement or
-row based. Vitess supports both these modes.
-
-For schema changes, if the number of affected rows is greater > 100k (configurable), we don't allow direct application
-of DDLs. The recommended tools in such cases are [gh-ost](https://github.com/github/gh-ost) or [pt-osc](https://www.percona.com/doc/percona-toolkit/LATEST/pt-online-schema-change.html).
-
-Not all statements are safe for Statement Based Replication (SBR): https://dev.mysql.com/doc/refman/8.0/en/replication-rbr-safe-unsafe.html. Vitess rewrites some of these statements to be safe for SBR, and others are explicitly failed. This is described in detail below.
-
-With statement based replication, it becomes easier to perform offline
-advanced schema changes, or large data updates. Vitess’s solution is called
-schema swap (described below).
-
-## Rewriting Update Statements
-
-Vitess rewrites ‘UPDATE’ SQL statements to always know what rows will be
-affected. For instance, this statement:
-
-```
-UPDATE
SET WHERE
-```
-
-Will be rewritten into:
-
-```
-SELECT FROM
WHERE FOR UPDATE
-UPDATE
SET WHERE IN /* primary key values: … */
-```
-
-With this rewrite in effect, we know exactly which rows are affected, by primary
-key, and we also document them as a SQL comment.
-
-The replication stream then doesn’t contain the expensive WHERE clauses, but
-only the UPDATE statements by primary key. In a sense, it is combining the best
-of row based and statement based replication: the slaves only do primary key
-based updates, but the replication stream is very friendly for schema changes.
-
-Also, Vitess adds comments to the rewritten statements that identify the primary
-key affected by that statement. This allows us to produce an Update Stream (see
-section below).
-
-## Vitess Schema Swap
-
-Within YouTube, we also use a combination of statement based replication and
-backups to apply long-running schema changes without disrupting ongoing
-operations. See the [schema swap tutorial]({% link user-guide/schema-swap.md %})
-for a detailed example.
-
-This operation, which is called **schema swap**, works as follows:
-
-* Pick a slave, take it out of service. It is not used by clients any more.
-* Apply whatever schema or large data change is needed, on the slave.
-* Take a backup of that slave.
-* On all the other slaves, one at a time, take them out of service, restore the
- backup, catch up on replication, put them back into service.
-* When all slaves are done, reparent to a slave that has applied the change.
-* The old master can then be restored from a backup too, and put back into
- service.
-
-With this process, the only guarantee we need is for the change (schema or data)
-to be backward compatible: the clients won’t know if they talk to a server
-that has applied the change yet or not. This is usually fairly easy to deal
-with:
-
-* When adding a column, clients cannot use it until the schema swap is done.
-* When removing a column, all clients must stop referring to it before the
- schema swap begins.
-* A column rename is still tricky: the best way to do it is to add a new column
- with the new name in one schema swap, then change the client to populate both
- (and backfill the values), then change the client again to use the new
- column only, then use another schema swap to remove the original column.
-* A whole bunch of operations are really easy to perform though: index changes,
- optimize table, …
-
-Note the real change is only applied to one instance. We then rely on the backup
-/ restore process to propagate the change. This is a very good improvement from
-letting the changes through the replication stream, where they are applied to
-all hosts, not just one. This is also a very good improvement over the industry
-practice of online schema change, which also must run on all hosts.
-Since Vitess’s backup / restore and reparent processes
-are very reliable (they need to be reliable on their own, independently of this
-process!), this does not add much more complexity to a running system.
-
-## Update Stream
-
-Since the SBR replication stream also contains comments of which primary key is
-affected by a change, it is possible to look at the replication stream and know
-exactly what objects have changed. This Vitess feature is
-called [Update Stream]({% link user-guide/update-stream.md %}).
-
-By subscribing to the Update Stream for a given shard, one can know what values
-change. This stream can be used to create a stream of data changes (export to an
-Apache Kafka for instance), or even invalidate an application layer cache.
-
-Note: the Update Stream only reliably contains the primary key values of the
-rows that have changed, not the actual values for all columns. To get these
-values, it is necessary to re-query the database.
-
-We have plans to make this [Update Stream]({% link user-guide/update-stream.md %})
-feature more consistent, very resilient, fast, and transparent to sharding.
-
-## Semi-Sync
-
-If you tell Vitess to enforce semi-sync
-([semisynchronous replication](https://dev.mysql.com/doc/refman/5.7/en/replication-semisync.html))
-by passing the `-enable_semi_sync` flag to vttablets,
-then the following will happen:
-
-* The master will only accept writes if it has at least one slave connected
- and sending semi-sync ACK. It will never fall back to asynchronous
- (not requiring ACKs) because of timeouts while waiting for ACK, nor because
- of having zero slaves connected (although it will fall back to asynchronous
- in case of shutdown, abrupt or graceful).
-
- This is important to prevent split brain (or alternate futures) in case of a
- network partition. If we can verify all slaves have stopped replicating,
- we know the old master is not accepting writes, even if we are unable to
- contact the old master itself.
-
-* Slaves of *replica* type will send semi-sync ACK. Slaves of *rdonly* type will
- **not** send ACK. This is because rdonly slaves are not eligible to be
- promoted to master, so we want to avoid the case where a rdonly slave is the
- single best candidate for election at the time of master failure (though
- a split brain is possible when all rdonly slaves have transactions that
- none of replica slaves have).
-
-These behaviors combine to give you the property that, in case of master
-failure, there is at least one other *replica* type slave that has every
-transaction that was ever reported to clients as having completed.
-You can then ([manually]({% link reference/vtctl.md %}#emergencyreparentshard),
-or with an automated tool like [Orchestrator](https://github.com/github/orchestrator))
-pick the replica that is farthest ahead in GTID position and promote that to be
-the new master.
-
-Thus, you can survive sudden master failure without losing any transactions that
-were reported to clients as completed. In MySQL 5.7+, this guarantee is
-strengthened slightly to preventing loss of any transactions that were ever
-**committed** on the original master, eliminating so-called
-[phantom reads](https://bugs.mysql.com/bug.php?id=62174).
-
-On the other hand these behaviors also give a requirement that each shard must
-have at least 2 tablets with type *replica* (with addition of the master that
-can be demoted to type *replica* this gives a minimum of 3 tablets with initial
-type *replica*). This will allow for the master to have a semi-sync acker when
-one of the *replica* tablets is down for any reason (for a version update,
-machine reboot, schema swap or anything else).
-
-With regard to replication lag, note that this does **not** guarantee there is
-always at least one *replica* type slave from which queries will always return
-up-to-date results. Semi-sync guarantees that at least one slave has the
-transaction in its relay log, but it has not necessarily been applied yet.
-The only way to guarantee a fully up-to-date read is to send the request to the
-master.
-
-## Appendix: Adding support for RBR in Vitess
-
-We are in the process of adding support for RBR in Vitess.
-
-See [this document]({% link user-guide/row-based-replication.md %})) for more information.
diff --git a/doc/VitessSequences.md b/doc/VitessSequences.md
deleted file mode 100644
index 155b315acfb..00000000000
--- a/doc/VitessSequences.md
+++ /dev/null
@@ -1,208 +0,0 @@
-# Vitess Sequences
-
-This document describes the Vitess Sequences feature, and how to use it.
-
-## Motivation
-
-MySQL provides the `auto-increment` feature to assign monotonically incrementing
-IDs to a column in a table. However, when a table is sharded across multiple
-instances, maintaining the same feature is a lot more tricky.
-
-Vitess Sequences fill that gap:
-
-* Inspired from the usual SQL sequences (implemented in different ways by
- Oracle, SQL Server and PostgreSQL).
-
-* Very high throughput for ID creation, using a configurable in-memory block allocation.
-
-* Transparent use, similar to MySQL auto-increment: when the field is omitted in
- an `insert` statement, the next sequence value is used.
-
-## When *not* to Use Auto-Increment
-
-Before we go any further, an auto-increment column has limitations and
-drawbacks. let's explore this topic a bit here.
-
-### Security Considerations
-
-Using auto-increment can leak confidential information about a service. Let's
-take the example of a web site that store user information, and assign user IDs
-to its users as they sign in. The user ID is then passed in a cookie for all
-subsequent requests.
-
-The client then knows their own user ID. It is now possible to:
-
-* Try other user IDs and expose potential system vulnerabilities.
-
-* Get an approximate number of users of the system (using the user ID).
-
-* Get an approximate number of sign-ins during a week (creating two accounts a
- week apart, and diffing the two IDs).
-
-Auto-incrementing IDs should be reserved for either internal applications, or
-exposed to the clients only when safe.
-
-### Alternatives
-
-Alternative to auto-incrementing IDs are:
-
-* use a 64 bits random generator number. Try to insert a new row with that
- ID. If taken (because the statement returns an integrity error), try another
- ID.
-
-* use a UUID scheme, and generate truly unique IDs.
-
-Now that this is out of the way, let's get to MySQL auto-increment.
-
-## MySQL Auto-increment Feature
-
-Let's start by looking at the MySQL auto-increment feature:
-
-* A row that has no value for the auto-increment value will be given the next ID.
-
-* The current value is stored in the table metadata.
-
-* Values may be ‘burned’ (by rolled back transactions).
-
-* Inserting a row with a given value that is higher than the current value will
- set the current value.
-
-* The value used by the master in a statement is sent in the replication stream,
- so slaves will have the same value when re-playing the stream.
-
-* There is no strict guarantee about ordering: two concurrent statements may
- have their commit time in one order, but their auto-incrementing ID in the
- opposite order (as the value for the ID is reserved when the statement is
- issued, not when the transaction is committed).
-
-* MySQL has multiple options for auto-increment, like only using every N number
- (for multi-master configurations), or performance related features (locking
- that table’s current ID may have concurrency implications).
-
-* When inserting a row in a table with an auto-increment column, if the value
- for the auto-increment row is not set, the value for the column is returned to
- the client alongside the statement result.
-
-## Vitess Sequences
-
-An early design was to use a single unsharded database and a table with an
-auto-increment value to generate new values. However, this has serious
-limitations, in particular throughput, and storing one entry for each value in
-that table, for no reason.
-
-So we decided instead to base sequences on a MySQL table, and use a single value
-in that table to describe which values the sequence should have next. To
-increase performance, we also support block allocation of IDs: each update to
-the MySQL table is only done every N IDs (N being configurable), and in between
-only memory structures in vttablet are updated, making the QPS only limited by
-RPC latency.
-
-In a sharded keyspace, a Sequence's data is only present in one shard (but its
-schema is in all the shards). We configure which shard has the data by using a
-keyspace_id for the sequence, and route all sequence traffic to the shard that
-hold that keyspace_id. That way we are completely compatible with any horizontal
-resharding.
-
-The final goal is to have Sequences supported with SQL statements, like:
-
-``` sql
-/* DDL support */
-CREATE SEQUENCE my_sequence;
-
-SELECT NEXT VALUE FROM my_sequence;
-
-ALTER SEQUENCE my_sequence ...;
-
-DROP SEQUENCE my_sequence;
-
-SHOW CREATE SEQUENCE my_sequence;
-```
-
-In the current implementation, we support the query access to Sequences, but not
-the administration commands yet.
-
-### Creating a Sequence
-
-*Note*: The names in this section are extracted from the examples/demo sample
-application.
-
-To create a Sequence, a backing table must first be created and initialized with a single row. The columns for that table have to be respected.
-
-This is an example:
-
-``` sql
-create table user_seq(id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence';
-
-insert into user_seq(id, next_id, cache) values(0, 1, 100);
-```
-
-Then, the Sequence has to be define in the VSchema for that keyspace:
-
-``` json
-{
- "sharded": false,
- "tables": {
- "user_seq": {
- "type": "sequence"
- },
- ...
- }
-}
-```
-
-And the table it is going to be using it can also reference the Sequence in its VSchema:
-
-``` json
-{
- ...
- "tables" : {
- "user": {
- "column_vindexes": [
- ...
- ],
- "auto_increment": {
- "column": "user_id",
- "sequence": "user_seq"
- }
- },
-
-```
-
-After this done (and the Schema has been reloaded on master tablet, and the
-VSchema has been pushed), the sequence can be used.
-
-### Accessing a Sequence
-
-If a Sequence is used to fill in a column for a table, nothing further needs to
-be done. Just sending no value for the column will make vtgate insert the next
-Sequence value in its place.
-
-It is also possible to access the Sequence directly with the following SQL constructs:
-
-``` sql
-/* Returns the next value for the sequence */
-select next value from my_sequence;
-
-/* Returns the next value for the sequence, and also reserve 4 values after that. */
-select next 5 values from my_sequence;
-
-```
-
-## TO-DO List
-
-### DDL Support
-
-We want to add DDL support for sequences, as previously mentioned:
-
-``` sql
-CREATE SEQUENCE my_sequence;
-
-ALTER SEQUENCE my_sequence ...;
-
-DROP SEQUENCE my_sequence;
-
-SHOW CREATE SEQUENCE my_sequence;
-```
-
-But for now, the Sequence backing table has to be created and managed using the
-usual schema management features, with the right column definitions and table comment.
diff --git a/doc/VitessTransportSecurityModel.md b/doc/VitessTransportSecurityModel.md
deleted file mode 100644
index bc9d0ebe832..00000000000
--- a/doc/VitessTransportSecurityModel.md
+++ /dev/null
@@ -1,110 +0,0 @@
-# Vitess Transport Security Model
-
-Vitess exposes a few RPC services, and internally also uses RPCs. These RPCs
-may use secure transport options. This document explains how to use these
-features.
-
-## Overview
-
-The following diagram represents all the RPCs we use in a Vitess cluster:
-
-
-
-
-
-There are two main categories:
-
-* Internal RPCs: they are used to connect Vitess components.
-* Externally visible RPCs: they are use by the app to talk to Vitess.
-
-A few features in the Vitess ecosystem depend on authentication, like Caller ID
-and table ACLs. We'll explore the Caller ID feature first.
-
-The encryption and authentication scheme used depends on the transport
-used. With gRPC (the default for Vitess), TLS can be used to secure both
-internal and external RPCs. We'll detail what the options are.
-
-## Caller ID
-
-Caller ID is a feature provided by the Vitess stack to identify the source of
-queries. There are two different Caller IDs:
-
-* **Immediate Caller ID**: It represents the secure client identity when it
- enters the Vitess side:
- * It is a single string, represents the user connecting to Vitess (vtgate).
- * It is authenticated by the transport layer used.
- * It is used by the Vitess TableACL feature.
-* **Effective Caller ID**: It provides detailed information on who the
- individual caller process is:
- * It contains more information about the caller: principal, component,
- sub-component.
- * It is provided by the application layer.
- * It is not authenticated.
- * It is exposed in query logs to be able to debug the source of a slow query,
- for instance.
-
-## gRPC Transport
-
-### gRPC Encrypted Transport
-
-When using gRPC transport, Vitess can use the usual TLS security features
-(familiarity with SSL / TLS is necessary here):
-
-* Any Vitess server can be configured to use TLS with the following
- command line parameters:
- * grpc\_cert, grpc\_key: server cert and key to use.
- * grpc\_ca (optional): client cert chains to trust. If specified, the client
- must use a certificate signed by one ca in the provided file.
-* A Vitess go client can be configured with symmetrical parameters to enable TLS:
- * ...\_grpc\_ca: list of server cert signers to trust.
- * ...\_grpc\_server\_name: name of the server cert to trust, instead of the
- hostname used to connect.
- * ...\_grpc\_cert, ...\_grpc\_key: client side cert and key to use (when the
- server requires client authentication)
-* Other clients can take similar parameters, in various ways, see each client
- for more information.
-
-With these options, it is possible to use TLS-secured connections for all parts
-of the system. This enables the server side to authenticate the client, and / or
-the client to authenticate the server.
-
-Note this is not enabled by default, as usually the different Vitess servers
-will run on a private network (in a Cloud environment, usually all local traffic
-is already secured over a VPN, for instance).
-
-### Certificates and Caller ID
-
-Additionally, if a client uses a certificate to connect to Vitess (vtgate), the
-common name of that certificate is passed to vttablet as the Immediate Caller
-ID. It can then be used by table ACLs, to grant read, write or admin access to
-individual tables. This should be used if different clients should have
-different access to Vitess tables.
-
-### Caller ID Override
-
-In a private network, where SSL security is not required, it might still be
-desirable to use table ACLs as a safety mechanism to prevent a user from
-accessing sensitive data. The gRPC connector provides the
-grpc\_use\_effective\_callerid flag for this purpose: if specified when running
-vtgate, the Effective Caller ID's principal is copied into the Immediate Caller
-ID, and then used throughout the Vitess stack.
-
-**Important**: this is not secure. Any user code can provide any value for
-the Effective Caller ID's principal, and therefore access any data. This is
-intended as a safety feature to make sure some applications do not misbehave.
-Therefore, this flag is not enabled by default.
-
-### Example
-
-For a concrete example, see
-[test/encrypted\_transport.py](https://github.com/vitessio/vitess/blob/master/test/encrypted_transport.py)
-in the source tree. It first sets up all the certificates, and some table ACLs,
-then uses the python client to connect with SSL. It also exercises the
-grpc\_use\_effective\_callerid flag, by connecting without SSL.
-
-## MySQL Transport
-
-To get vtgate to support SSL/TLS use `-mysql_server_ssl_cert` and `-mysql_server_ssl_key`.
-
-To require client certificates set `-mysql_server_ssl_ca`. If there is no CA specified then
-TLS is optional.
diff --git a/doc/VtExplain.md b/doc/VtExplain.md
deleted file mode 100644
index 93d06a8f0c3..00000000000
--- a/doc/VtExplain.md
+++ /dev/null
@@ -1,151 +0,0 @@
-# VTExplain Tool
-
-The vtexplain tool provides information about how Vitess will execute a statement (the Vitess version of MySQL `EXPLAIN`).
-
-## Prerequisites
-
-You'll need to build the `vtexplain` binary in your environment.
-To find instructions on how to build this binary please refer to this [guide](https://vitess.io/docs/tutorials/local/).
-
-## Explaining a Query
-
-In order to explain a query you will need to first collect a sql schema for the various tables and a vschema json file containing a map of keyspace to the set of vindexes / tables in the vschema.
-
-For example, let's use the following:
-
-Schema:
-
-```SQL
-CREATE TABLE users(
- user_id bigint,
- name varchar(128),
- primary key(user_id)
-);
-
-CREATE TABLE users_name_idx(
- user_id bigint,
- name varchar(128),
- primary key(name, user_id)
-);
-```
-
-VSchema:
-
-```json
-{
- "mainkeyspace": {
- "sharded": true,
- "vindexes": {
- "hash": {
- "type": "hash"
- },
- "md5": {
- "type": "unicode_loose_md5",
- "params": {},
- "owner": ""
- },
- "users_name_idx": {
- "type": "lookup_hash",
- "params": {
- "from": "name",
- "table": "users_name_idx",
- "to": "user_id"
- },
- "owner": "users"
- }
- },
- "tables": {
- "users": {
- "column_vindexes": [
- {
- "column": "user_id",
- "name": "hash"
- },
- {
- "column": "name",
- "name": "users_name_idx"
- }
- ],
- "auto_increment": null
- },
- "users_name_idx": {
- "type": "",
- "column_vindexes": [
- {
- "column": "name",
- "name": "md5"
- }
- ],
- "auto_increment": null
- }
- }
- }
-}
-```
-
-These can be passed to vtexplain either on the command line or (more readily) through files.
-
-Then you can use the tool like this:
-
-**Select:**
-
-```bash
-vtexplain -shards 8 -vschema-file /tmp/vschema.json -schema-file /tmp/schema.sql -replication-mode "ROW" -output-mode text -sql "SELECT * from users"
-----------------------------------------------------------------------
-SELECT * from users
-
-1 mainkeyspace/-20: select * from users limit 10001
-1 mainkeyspace/20-40: select * from users limit 10001
-1 mainkeyspace/40-60: select * from users limit 10001
-1 mainkeyspace/60-80: select * from users limit 10001
-1 mainkeyspace/80-a0: select * from users limit 10001
-1 mainkeyspace/a0-c0: select * from users limit 10001
-1 mainkeyspace/c0-e0: select * from users limit 10001
-1 mainkeyspace/e0-: select * from users limit 10001
-
-----------------------------------------------------------------------
-```
-
-The output shows the sequence of queries run.
-
-In this case, the query planner is a scatter query to all shards, and each line shows:
-
-(a) the logical sequence of the query
-(b) the keyspace/shard
-(c) the query that was executed
-
-The fact that each query runs at time `1` shows that vitess executes these in parallel, and the `limit 10001` is automatically added as a protection against large results.
-
-**Insert:**
-
-```bash
-vtexplain -shards 128 -vschema-file /tmp/vschema.json -schema-file /tmp/schema.sql -replication-mode "ROW" -output-mode text -sql "INSERT INTO users (user_id, name) VALUES(1, 'john')"
-
-----------------------------------------------------------------------
-INSERT INTO users (user_id, name) VALUES(1, 'john')
-
-1 mainkeyspace/22-24: begin
-1 mainkeyspace/22-24: insert into users_name_idx(name, user_id) values ('john', 1) /* vtgate:: keyspace_id:22c0c31d7a0b489a16332a5b32b028bc */
-2 mainkeyspace/16-18: begin
-2 mainkeyspace/16-18: insert into users(user_id, name) values (1, 'john') /* vtgate:: keyspace_id:166b40b44aba4bd6 */
-3 mainkeyspace/22-24: commit
-4 mainkeyspace/16-18: commit
-
-----------------------------------------------------------------------
-```
-
-This example shows how Vitess handles an insert into a table with a secondary lookup vindex.
-
-First, at time `1`, a transaction is opened on one shard to insert the row into the `users_name_idx` table. Then at time `2` a second transaction is opened on another shard with the actual insert into the `users` table, and finally each transaction is committed at time `3` and `4`.
-
-**Configuration Options**
-
-The `--shards` option specifies the number of shards to simulate. vtexplain will always allocate an evenly divided key range to each.
-
-The `--replication-mode` option controls whether to simulate row based or statement based replication.
-
-You can find more usage of `vtexplain` by executing the following command:
-
-```
-vtexplain --help
-```
diff --git a/doc/internal/PublishWebsite.md b/doc/internal/PublishWebsite.md
deleted file mode 100644
index 5787416f932..00000000000
--- a/doc/internal/PublishWebsite.md
+++ /dev/null
@@ -1,166 +0,0 @@
-# Publishing vitess.io Web Site
-
-## Overview
-
-Our website [vitess.io](https://vitess.io) are static HTML pages which are
-generated by [Jekyll](https://github.com/jekyll/jekyll) from Markdown files
-located in the [`doc/`](https://github.com/vitessio/vitess/tree/master/doc)
-directory.
-
-The generated files will be put in the
-[`docs/`](https://github.com/vitessio/vitess/tree/master/docs) directory (note
-the extra **s**). GitHub serves the website from this directory off the master
-branch.
-
-## TL;DR
-
-### To preview site locally
-
-* Run:
-
- ```
- ./vitess.io/preview-site.sh
- ```
-
-* Site should be live at localhost:4000
-
-### To publish the site
-
-* Make sure your doc and site changes have been committed to your branch and
- your branch is clean.
-* Run:
-
- ```
- ./vitess.io/publish-site.sh
- ```
-
-* Sanity check the diffs.
- * `git diff HEAD~`
-* Create a pull request for your branch and let somebody review it.
-* Merge the pull request into the master branch.
-
-## Details
-
-### Directory Structure
-
-We have three main directories:
-
-* [`doc/`](https://github.com/vitessio/vitess/tree/master/doc) - original
- content
-* [`docs/`](https://github.com/vitessio/vitess/tree/master/docs) - generated
- website actually served at https://vitess.io/
-* [`vitess.io/`](https://github.com/vitessio/vitess/tree/master/vitess.io) -
- all relevant files for the website e.g.
- * Jekyll configuration
- * images e.g. our logo
- * CSS
- * [Navigation
- menu](https://github.com/vitessio/vitess/blob/master/vitess.io/_includes/left-nav-menu.html)
- * boiler plate markdown files which include the actual content from the
- `doc/` directory
- ([example](https://github.com/vitessio/vitess/blob/master/vitess.io/contributing/github-workflow.md))
-
-The boiler plate markdown files have multiple purposes:
-
-* feed the actual content into a template which adds e.g. the navigation to
- the file
-* re-arrange paths on the website e.g.
- [`doc/GitHubWorkFlow.md`](https://github.com/vitessio/vitess/blob/master/doc/GitHubWorkflow.md)
- is actually served as https://vitess.io/docs/contributing/github-workflow/
- because there is the file
- [`vitess.io/contributing/github-workflow.md`](https://github.com/vitessio/vitess/blob/master/vitess.io/contributing/github-workflow.md).
-
-### Changing Content
-
-To modify our website, you need to:
-
-* change the underlying Markdown files in the `doc/` directory
-* re-generate the static pages (see [`publish-site.sh`
- above](#to-publish-the-site))
-* merge your changes into the master branch e.g. as pull request
-
-### Linking pages
-
-Always use the `{% raw %}{% link ... %}{% endraw %}` template tag to link other pages.
-
-Note that you have to refer to the `.md` file of the page. Example:
-
-```
-[GitHub Workflow page]({% raw %}{% link contributing/github-workflow.md %}{% endraw %})
-```
-
-### Adding new Pages
-
-If you want to add a new page, you must also:
-
-* add it to the left menu:
- [`vitess.io/_includes/left-nav-menu.html`](https://github.com/vitessio/vitess/blob/master/vitess.io/_includes/left-nav-menu.html)
-* create a boiler plate .md file. Example:
- [`vitess.io/contributing/github-workflow.md`](https://github.com/vitessio/vitess/blob/master/vitess.io/contributing/github-workflow.md)
-
-When you add a new section to the menu, please create a new directory below
-`vitess.io/`. For example, the "Contributing" section is served out of
-`vitess.io/contributing/`.
-
-The main file in the section should have `index.md` as its boiler plate counter
-part. Example: `doc/Contributing.md` is included by
-`vitess.io/contributing/index.md` and therefore served as
-https://vitess.io/contributing/.
-
-Make sure that you use `{% raw %}{% link ... %}{% endraw %}` to generate the URLs.
-See existing entries for examples.
-
-### Orphaned doc/ Markdown Files
-
-There are several files in `doc/` which are currently not visible on
-https://vitess.io.
-
-Examples:
-
-* https://github.com/vitessio/vitess/blob/master/doc/LifeOfAQuery.md
-* https://github.com/vitessio/vitess/blob/master/doc/V3VindexDesign.md
-
-This is fine and accepted. Users can still view them on GitHub.com.
-
-Note that these files should include images using the full path e.g. in
-`LifeOfAQuery.md`:
-
-```
-
-```
-
-Otherwise GitHub cannot find and show the images.
-
-## Jekyll Install Instructions
-
-This section describes how to install Jekyll to generate the website.
-
-### The Easy Way
-
-* Install Docker.
-* Run the `./vitess.io/preview-site.sh` and `./vitess.io/publish-site.sh` commands as shown above.
-
-### The Hard Way
-
-* On Ubuntu, you need a non-root Ruby install so gem packages can be
- installed correctly.
- * [Install rbenv](https://github.com/sstephenson/rbenv#installation).
- * Close and re-open your shell to complete the installation.
- * [Install
- ruby-build](https://github.com/sstephenson/ruby-build#installation)
- plugin for rbenv.
- * Use rbenv to build a recent version of Ruby.
- * rbenv install 2.2.3
- * You may need to install extra dependencies. The build output should tell
- you which packages. For example: ```sudo apt-get install -y libreadline-dev```
- * Set the new Ruby as the system-wide default.
- * ```rbenv global 2.2.3```
- * ```rbenv rehash```
-* Install bundler.
- * ```gem install bundler```
-* Install "nodejs" as JavaScript runtime.
- * ```sudo apt-get install nodejs```
- * In Ubuntu, the binary is unfortunately renamed from "node" to "nodejs".
- We work-around this by creating a "node" symlink on a directory which is
- early in the PATH list: ```ln -s /usr/bin/nodejs $HOME/.rbenv/bin/node```
-* Add `--docker=false` to the commands above.
diff --git a/doc/slides/Percona2015.pptx b/doc/slides/Percona2015.pptx
deleted file mode 100644
index b38e77df5ee..00000000000
Binary files a/doc/slides/Percona2015.pptx and /dev/null differ
diff --git a/doc/slides/Vitess2014.pdf b/doc/slides/Vitess2014.pdf
deleted file mode 100644
index 2beb924c267..00000000000
Binary files a/doc/slides/Vitess2014.pdf and /dev/null differ
diff --git a/doc/vtctlReference.md b/doc/vtctlReference.md
deleted file mode 100644
index a679512f3dd..00000000000
--- a/doc/vtctlReference.md
+++ /dev/null
@@ -1,2573 +0,0 @@
-This reference guide explains the commands that the vtctl tool supports. **vtctl** is a command-line tool used to administer a Vitess cluster, and it allows a human or application to easily interact with a Vitess implementation.
-
-Commands are listed in the following groups:
-
-* [Cells](#cells)
-* [Generic](#generic)
-* [Keyspaces](#keyspaces)
-* [Queries](#queries)
-* [Replication Graph](#replication-graph)
-* [Resharding Throttler](#resharding-throttler)
-* [Schema, Version, Permissions](#schema-version-permissions)
-* [Serving Graph](#serving-graph)
-* [Shards](#shards)
-* [Tablets](#tablets)
-* [Topo](#topo)
-* [Workflows](#workflows)
-
-
-## Cells
-
-* [AddCellInfo](#addcellinfo)
-* [DeleteCellInfo](#deletecellinfo)
-* [GetCellInfo](#getcellinfo)
-* [GetCellInfoNames](#getcellinfonames)
-* [UpdateCellInfo](#updatecellinfo)
-
-### AddCellInfo
-
-Registers a local topology service in a new cell by creating the CellInfo with the provided parameters. The address will be used to connect to the topology service, and we'll put Vitess data starting at the provided root.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| root | string | The root path the topology server is using for that cell. |
-| server_address | string | The address the topology server is using for that cell. |
-
-
-#### Arguments
-
-* <addr> – Required.
-* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-
-#### Errors
-
-* the <cell> argument is required for the <AddCellInfo> command This error occurs if the command is not called with exactly one argument.
-
-
-### DeleteCellInfo
-
-Deletes the CellInfo for the provided cell. The cell cannot be referenced by any Shard record.
-
-#### Example
-
-
DeleteCellInfo <cell>
-
-#### Errors
-
-* the <cell> argument is required for the <DeleteCellInfo> command This error occurs if the command is not called with exactly one argument.
-
-
-### GetCellInfo
-
-Prints a JSON representation of the CellInfo for a cell.
-
-#### Example
-
-
GetCellInfo <cell>
-
-#### Errors
-
-* the <cell> argument is required for the <GetCellInfo> command This error occurs if the command is not called with exactly one argument.
-
-
-### GetCellInfoNames
-
-Lists all the cells for which we have a CellInfo object, meaning we have a local topology service registered.
-
-#### Example
-
-
GetCellInfoNames
-
-#### Errors
-
-* <GetCellInfoNames> command takes no parameter This error occurs if the command is not called with exactly 0 arguments.
-
-
-### UpdateCellInfo
-
-Updates the content of a CellInfo with the provided parameters. If a value is empty, it is not updated. The CellInfo will be created if it doesn't exist.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| root | string | The root path the topology server is using for that cell. |
-| server_address | string | The address the topology server is using for that cell. |
-
-
-#### Arguments
-
-* <addr> – Required.
-* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-
-#### Errors
-
-* the <cell> argument is required for the <UpdateCellInfo> command This error occurs if the command is not called with exactly one argument.
-
-
-## Generic
-
-* [ListAllTablets](#listalltablets)
-* [ListTablets](#listtablets)
-* [Validate](#validate)
-
-### ListAllTablets
-
-Lists all tablets in an awk-friendly way.
-
-#### Example
-
-
ListAllTablets <cell name>
-
-#### Arguments
-
-* <cell name> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-
-#### Errors
-
-* the <cell name> argument is required for the <ListAllTablets> command This error occurs if the command is not called with exactly one argument.
-
-
-### ListTablets
-
-Lists specified tablets in an awk-friendly way.
-
-#### Example
-
-
ListTablets <tablet alias> ...
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <ListTablets> command This error occurs if the command is not called with at least one argument.
-
-
-### Validate
-
-Validates that all nodes reachable from the global replication graph and that all tablets in all discoverable cells are consistent.
-
-#### Example
-
-
Validate [-ping-tablets]
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process |
-
-
-
-
-## Keyspaces
-
-* [CreateKeyspace](#createkeyspace)
-* [DeleteKeyspace](#deletekeyspace)
-* [FindAllShardsInKeyspace](#findallshardsinkeyspace)
-* [GetKeyspace](#getkeyspace)
-* [GetKeyspaces](#getkeyspaces)
-* [MigrateServedFrom](#migrateservedfrom)
-* [MigrateServedTypes](#migrateservedtypes)
-* [CancelResharding](#cancelresharding)
-* [ShowResharding](#showresharding)
-* [RebuildKeyspaceGraph](#rebuildkeyspacegraph)
-* [RemoveKeyspaceCell](#removekeyspacecell)
-* [SetKeyspaceServedFrom](#setkeyspaceservedfrom)
-* [SetKeyspaceShardingInfo](#setkeyspaceshardinginfo)
-* [ValidateKeyspace](#validatekeyspace)
-* [WaitForDrain](#waitfordrain)
-
-### CreateKeyspace
-
-Creates the specified keyspace.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| force | Boolean | Proceeds even if the keyspace already exists |
-| served_from | string | Specifies a comma-separated list of dbtype:keyspace pairs used to serve traffic |
-| sharding_column_name | string | Specifies the column to use for sharding operations |
-| sharding_column_type | string | Specifies the type of the column to use for sharding operations |
-
-
-#### Arguments
-
-* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace name> argument is required for the <CreateKeyspace> command This error occurs if the command is not called with exactly one argument.
-
-
-### DeleteKeyspace
-
-Deletes the specified keyspace. In recursive mode, it also recursively deletes all shards in the keyspace. Otherwise, there must be no shards left in the keyspace.
-
-#### Example
-
-
DeleteKeyspace [-recursive] <keyspace>
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| recursive | Boolean | Also recursively delete all shards in the keyspace. |
-
-
-#### Arguments
-
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* must specify the <keyspace> argument for <DeleteKeyspace> This error occurs if the command is not called with exactly one argument.
-
-
-### FindAllShardsInKeyspace
-
-Displays all of the shards in the specified keyspace.
-
-#### Example
-
-
FindAllShardsInKeyspace <keyspace>
-
-#### Arguments
-
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace> argument is required for the <FindAllShardsInKeyspace> command This error occurs if the command is not called with exactly one argument.
-
-
-### GetKeyspace
-
-Outputs a JSON structure that contains information about the Keyspace.
-
-#### Example
-
-
GetKeyspace <keyspace>
-
-#### Arguments
-
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace> argument is required for the <GetKeyspace> command This error occurs if the command is not called with exactly one argument.
-
-
-### GetKeyspaces
-
-Outputs a sorted list of all keyspaces.
-
-
-### MigrateServedFrom
-
-Makes the <destination keyspace/shard> serve the given type. This command also rebuilds the serving graph.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| cells | string | Specifies a comma-separated list of cells to update |
-| filtered_replication_wait_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations |
-| reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble |
-
-
-#### Arguments
-
-* <destination keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-* <served tablet type> – Required. The vttablet's role. Valid values are:
-
- * backup – A slaved copy of data that is offline to queries other than for backup purposes
- * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
- * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication.
- * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
- * master – A primary copy of data
- * rdonly – A slaved copy of data for OLAP load patterns
- * replica – A slaved copy of data ready to be promoted to master
- * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
- * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
- * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode:
vtctl Snapshot -server-mode ...
Use this command to exit this mode:
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
-
-
-
-
-#### Errors
-
-* the <destination keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedFrom> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### MigrateServedTypes
-
-Migrates a serving type from the source shard to the shards that it replicates to. This command also rebuilds the serving graph. The <keyspace/shard> argument can specify any of the shards involved in the migration.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| cells | string | Specifies a comma-separated list of cells to update |
-| filtered\_replication\_wait\_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations |
-| reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble |
-| skip-refresh-state | Boolean | Skips refreshing the state of the source tablets after the migration, meaning that the refresh will need to be done manually, replica and rdonly only) |
-| reverse\_replication | Boolean | For master migration, enabling this flag reverses replication which allows you to rollback |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-* <served tablet type> – Required. The vttablet's role. Valid values are:
-
- * backup – A slaved copy of data that is offline to queries other than for backup purposes
- * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
- * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication.
- * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
- * master – A primary copy of data
- * rdonly – A slaved copy of data for OLAP load patterns
- * replica – A slaved copy of data ready to be promoted to master
- * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
- * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
- * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode:
vtctl Snapshot -server-mode ...
Use this command to exit this mode:
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
-
-
-
-
-#### Errors
-
-* the <source keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedTypes> command This error occurs if the command is not called with exactly 2 arguments.
-* the <skip-refresh-state> flag can only be specified for non-master migrations
-
-
-### CancelResharding
-
-Permanently cancels a resharding in progress. All resharding related metadata will be deleted.
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-
-### ShowResharding
-
-"Displays all metadata about a resharding in progress.
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-
-### RebuildKeyspaceGraph
-
-Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| cells | string | Specifies a comma-separated list of cells to update |
-
-
-#### Arguments
-
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. To specify multiple values for this argument, separate individual values with a space.
-
-#### Errors
-
-* the <keyspace> argument must be used to specify at least one keyspace when calling the <RebuildKeyspaceGraph> command This error occurs if the command is not called with at least one argument.
-
-
-### RemoveKeyspaceCell
-
-Removes the cell from the Cells list for all shards in the keyspace, and the SrvKeyspace for that keyspace in that cell.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| force | Boolean | Proceeds even if the cell's topology server cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. |
-| recursive | Boolean | Also delete all tablets in that cell belonging to the specified keyspace. |
-
-
-#### Arguments
-
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace> and <cell> arguments are required for the <RemoveKeyspaceCell> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### SetKeyspaceServedFrom
-
-Changes the ServedFromMap manually. This command is intended for emergency fixes. This field is automatically set when you call the *MigrateServedFrom* command. This command does not rebuild the serving graph.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| cells | string | Specifies a comma-separated list of cells to affect |
-| remove | Boolean | Indicates whether to add (default) or remove the served from record |
-| source | string | Specifies the source keyspace name |
-
-
-#### Arguments
-
-* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-* <tablet type> – Required. The vttablet's role. Valid values are:
-
- * backup – A slaved copy of data that is offline to queries other than for backup purposes
- * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
- * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication.
- * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
- * master – A primary copy of data
- * rdonly – A slaved copy of data for OLAP load patterns
- * replica – A slaved copy of data ready to be promoted to master
- * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
- * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
- * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode:
vtctl Snapshot -server-mode ...
Use this command to exit this mode:
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
-
-
-
-
-#### Errors
-
-* the <keyspace name> and <tablet type> arguments are required for the <SetKeyspaceServedFrom> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### SetKeyspaceShardingInfo
-
-Updates the sharding information for a keyspace.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| force | Boolean | Updates fields even if they are already set. Use caution before calling this command. |
-
-
-#### Arguments
-
-* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-* <column name> – Optional.
-* <column type> – Optional.
-
-#### Errors
-
-* the <keyspace name> argument is required for the <SetKeyspaceShardingInfo> command. The <column name> and <column type> arguments are both optional This error occurs if the command is not called with between 1 and 3 arguments.
-* both <column name> and <column type> must be set, or both must be unset
-
-
-### ValidateKeyspace
-
-Validates that all nodes reachable from the specified keyspace are consistent.
-
-#### Example
-
-
ValidateKeyspace [-ping-tablets] <keyspace name>
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| ping-tablets | Boolean | Specifies whether all tablets will be pinged during the validation process |
-
-
-#### Arguments
-
-* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace name> argument is required for the <ValidateKeyspace> command This error occurs if the command is not called with exactly one argument.
-
-
-### WaitForDrain
-
-Blocks until no new queries were observed on all tablets with the given tablet type in the specified keyspace. This can be used as sanity check to ensure that the tablets were drained after running vtctl MigrateServedTypes and vtgate is no longer using them. If -timeout is set, it fails when the timeout is reached.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| cells | string | Specifies a comma-separated list of cells to look for tablets |
-| initial_wait | Duration | Time to wait for all tablets to check in |
-| retry_delay | Duration | Time to wait between two checks |
-| timeout | Duration | Timeout after which the command fails |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-* <served tablet type> – Required. The vttablet's role. Valid values are:
-
- * backup – A slaved copy of data that is offline to queries other than for backup purposes
- * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
- * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication.
- * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
- * master – A primary copy of data
- * rdonly – A slaved copy of data for OLAP load patterns
- * replica – A slaved copy of data ready to be promoted to master
- * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
- * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
- * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode:
vtctl Snapshot -server-mode ...
Use this command to exit this mode:
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
-
-
-
-
-#### Errors
-
-* the <keyspace/shard> and <tablet type> arguments are both required for the <WaitForDrain> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-## Queries
-
-* [VtGateExecute](#vtgateexecute)
-* [VtGateExecuteKeyspaceIds](#vtgateexecutekeyspaceids)
-* [VtGateExecuteShards](#vtgateexecuteshards)
-* [VtGateSplitQuery](#vtgatesplitquery)
-* [VtTabletBegin](#vttabletbegin)
-* [VtTabletCommit](#vttabletcommit)
-* [VtTabletExecute](#vttabletexecute)
-* [VtTabletRollback](#vttabletrollback)
-* [VtTabletStreamHealth](#vttabletstreamhealth)
-* [VtTabletUpdateStream](#vttabletupdatestream)
-
-### VtGateExecute
-
-Executes the given SQL query with the provided bound variables against the vtgate server.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| json | Boolean | Output JSON instead of human-readable table |
-| options | string | execute options values as a text encoded proto of the ExecuteOptions structure |
-| server | string | VtGate server to connect to |
-| target | string | keyspace:shard@tablet_type |
-
-
-#### Arguments
-
-* <vtgate> – Required.
-* <sql> – Required.
-
-#### Errors
-
-* the <sql> argument is required for the <VtGateExecute> command This error occurs if the command is not called with exactly one argument.
-* query commands are disabled (set the -enable_queries flag to enable)
-* error connecting to vtgate '%v': %v
-* Execute failed: %v
-
-
-### VtGateExecuteKeyspaceIds
-
-Executes the given SQL query with the provided bound variables against the vtgate server. It is routed to the shards that contain the provided keyspace ids.
-
-#### Example
-
-
VtGateExecuteKeyspaceIds -server <vtgate> -keyspace <keyspace> -keyspace_ids <ks1 in hex>,<k2 in hex>,... [-bind_variables <JSON map>] [-tablet_type <tablet type>] [-options <proto text options>] [-json] <sql>
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| json | Boolean | Output JSON instead of human-readable table |
-| keyspace | string | keyspace to send query to |
-| keyspace_ids | string | comma-separated list of keyspace ids (in hex) that will map into shards to send query to |
-| options | string | execute options values as a text encoded proto of the ExecuteOptions structure |
-| server | string | VtGate server to connect to |
-| tablet_type | string | tablet type to query |
-
-
-#### Arguments
-
-* <vtgate> – Required.
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-* <ks1 in hex> – Required. To specify multiple values for this argument, separate individual values with a comma.
-* <sql> – Required.
-
-#### Errors
-
-* the <sql> argument is required for the <VtGateExecuteKeyspaceIds> command This error occurs if the command is not called with exactly one argument.
-* query commands are disabled (set the -enable_queries flag to enable)
-* cannot hex-decode value %v '%v': %v
-* error connecting to vtgate '%v': %v
-* Execute failed: %v
-
-
-### VtGateExecuteShards
-
-Executes the given SQL query with the provided bound variables against the vtgate server. It is routed to the provided shards.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| json | Boolean | Output JSON instead of human-readable table |
-| keyspace | string | keyspace to send query to |
-| options | string | execute options values as a text encoded proto of the ExecuteOptions structure |
-| server | string | VtGate server to connect to |
-| shards | string | comma-separated list of shards to send query to |
-| tablet_type | string | tablet type to query |
-
-
-#### Arguments
-
-* <vtgate> – Required.
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-* <shard> – Required. The name of a shard. The argument value is typically in the format <range start>-<range end>. To specify multiple values for this argument, separate individual values with a comma.
-* <sql> – Required.
-
-#### Errors
-
-* the <sql> argument is required for the <VtGateExecuteShards> command This error occurs if the command is not called with exactly one argument.
-* query commands are disabled (set the -enable_queries flag to enable)
-* error connecting to vtgate '%v': %v
-* Execute failed: %v
-
-
-### VtGateSplitQuery
-
-Executes the SplitQuery computation for the given SQL query with the provided bound variables against the vtgate server (this is the base query for Map-Reduce workloads, and is provided here for debug / test purposes).
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| algorithm | string | The algorithm to |
-| keyspace | string | keyspace to send query to |
-| server | string | VtGate server to connect to |
-| split_count | Int64 | number of splits to generate. |
-
-
-#### Arguments
-
-* <vtgate> – Required.
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-* <split_count> – Required.
-* <sql> – Required.
-
-#### Errors
-
-* the <sql> argument is required for the <VtGateSplitQuery> command This error occurs if the command is not called with exactly one argument.
-* query commands are disabled (set the -enable_queries flag to enable)
-* Exactly one of <split_count> or num_rows_per_query_part
-* Unknown split-query <algorithm>: %v
-* error connecting to vtgate '%v': %v
-* Execute failed: %v
-* SplitQuery failed: %v
-
-
-### VtTabletBegin
-
-Starts a transaction on the provided server.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check |
-
-
-#### Arguments
-
-* <TableACL user> – Required.
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet_alias> argument is required for the <VtTabletBegin> command This error occurs if the command is not called with exactly one argument.
-* query commands are disabled (set the -enable_queries flag to enable)
-* cannot connect to tablet %v: %v
-* Begin failed: %v
-
-
-### VtTabletCommit
-
-Commits the given transaction on the provided server.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check |
-
-
-#### Arguments
-
-* <TableACL user> – Required.
-* <transaction_id> – Required.
-
-#### Errors
-
-* the <tablet_alias> and <transaction_id> arguments are required for the <VtTabletCommit> command This error occurs if the command is not called with exactly 2 arguments.
-* query commands are disabled (set the -enable_queries flag to enable)
-* cannot connect to tablet %v: %v
-
-
-### VtTabletExecute
-
-Executes the given query on the given tablet. -transaction_id is optional. Use VtTabletBegin to start a transaction.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| json | Boolean | Output JSON instead of human-readable table |
-| options | string | execute options values as a text encoded proto of the ExecuteOptions structure |
-| transaction_id | Int | transaction id to use, if inside a transaction. |
-| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check |
-
-
-#### Arguments
-
-* <TableACL user> – Required.
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-* <sql> – Required.
-
-#### Errors
-
-* the <tablet_alias> and <sql> arguments are required for the <VtTabletExecute> command This error occurs if the command is not called with exactly 2 arguments.
-* query commands are disabled (set the -enable_queries flag to enable)
-* cannot connect to tablet %v: %v
-* Execute failed: %v
-
-
-### VtTabletRollback
-
-Rollbacks the given transaction on the provided server.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check |
-
-
-#### Arguments
-
-* <TableACL user> – Required.
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-* <transaction_id> – Required.
-
-#### Errors
-
-* the <tablet_alias> and <transaction_id> arguments are required for the <VtTabletRollback> command This error occurs if the command is not called with exactly 2 arguments.
-* query commands are disabled (set the -enable_queries flag to enable)
-* cannot connect to tablet %v: %v
-
-
-### VtTabletStreamHealth
-
-Executes the StreamHealth streaming query to a vttablet process. Will stop after getting <count> answers.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| count | Int | number of responses to wait for |
-
-
-#### Arguments
-
-* <count default 1> – Required.
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <VtTabletStreamHealth> command This error occurs if the command is not called with exactly one argument.
-* query commands are disabled (set the -enable_queries flag to enable)
-* cannot connect to tablet %v: %v
-
-
-### VtTabletUpdateStream
-
-Executes the UpdateStream streaming query to a vttablet process. Will stop after getting <count> answers.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| count | Int | number of responses to wait for |
-| position | string | position to start the stream from |
-| timestamp | Int | timestamp to start the stream from |
-
-
-#### Arguments
-
-* <count default 1> – Required.
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <VtTabletUpdateStream> command This error occurs if the command is not called with exactly one argument.
-* query commands are disabled (set the -enable_queries flag to enable)
-* cannot connect to tablet %v: %v
-
-
-## Replication Graph
-
-* [GetShardReplication](#getshardreplication)
-
-### GetShardReplication
-
-Outputs a JSON structure that contains information about the ShardReplication.
-
-#### Example
-
-
GetShardReplication <cell> <keyspace/shard>
-
-#### Arguments
-
-* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <cell> and <keyspace/shard> arguments are required for the <GetShardReplication> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-## Resharding Throttler
-
-* [GetThrottlerConfiguration](#getthrottlerconfiguration)
-* [ResetThrottlerConfiguration](#resetthrottlerconfiguration)
-* [ThrottlerMaxRates](#throttlermaxrates)
-* [ThrottlerSetMaxRate](#throttlersetmaxrate)
-* [UpdateThrottlerConfiguration](#updatethrottlerconfiguration)
-
-### GetThrottlerConfiguration
-
-Returns the current configuration of the MaxReplicationLag module. If no throttler name is specified, the configuration of all throttlers will be returned.
-
-#### Example
-
-
GetThrottlerConfiguration -server <vtworker or vttablet> [<throttler name>]
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| server | string | vtworker or vttablet to connect to |
-
-
-#### Arguments
-
-* <vtworker or vttablet> – Required.
-* <throttler name> – Optional.
-
-#### Errors
-
-* the <GetThrottlerConfiguration> command accepts only <throttler name> as optional positional parameter This error occurs if the command is not called with more than 1 arguments.
-* error creating a throttler client for <server> '%v': %v
-* failed to get the throttler configuration from <server> '%v': %v
-
-
-### ResetThrottlerConfiguration
-
-Resets the current configuration of the MaxReplicationLag module. If no throttler name is specified, the configuration of all throttlers will be reset.
-
-#### Example
-
-
ResetThrottlerConfiguration -server <vtworker or vttablet> [<throttler name>]
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| server | string | vtworker or vttablet to connect to |
-
-
-#### Arguments
-
-* <vtworker or vttablet> – Required.
-* <throttler name> – Optional.
-
-#### Errors
-
-* the <ResetThrottlerConfiguration> command accepts only <throttler name> as optional positional parameter This error occurs if the command is not called with more than 1 arguments.
-* error creating a throttler client for <server> '%v': %v
-* failed to get the throttler configuration from <server> '%v': %v
-
-
-### ThrottlerMaxRates
-
-Returns the current max rate of all active resharding throttlers on the server.
-
-#### Example
-
-
ThrottlerMaxRates -server <vtworker or vttablet>
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| server | string | vtworker or vttablet to connect to |
-
-
-#### Arguments
-
-* <vtworker or vttablet> – Required.
-
-#### Errors
-
-* the ThrottlerSetMaxRate command does not accept any positional parameters This error occurs if the command is not called with exactly 0 arguments.
-* error creating a throttler client for <server> '%v': %v
-* failed to get the throttler rate from <server> '%v': %v
-
-
-### ThrottlerSetMaxRate
-
-Sets the max rate for all active resharding throttlers on the server.
-
-#### Example
-
-
ThrottlerSetMaxRate -server <vtworker or vttablet> <rate>
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| server | string | vtworker or vttablet to connect to |
-
-
-#### Arguments
-
-* <vtworker or vttablet> – Required.
-* <rate> – Required.
-
-#### Errors
-
-* the <rate> argument is required for the <ThrottlerSetMaxRate> command This error occurs if the command is not called with exactly one argument.
-* failed to parse rate '%v' as integer value: %v
-* error creating a throttler client for <server> '%v': %v
-* failed to set the throttler rate on <server> '%v': %v
-
-
-### UpdateThrottlerConfiguration
-
-Updates the configuration of the MaxReplicationLag module. The configuration must be specified as protobuf text. If a field is omitted or has a zero value, it will be ignored unless -copy_zero_values is specified. If no throttler name is specified, all throttlers will be updated.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| copy_zero_values | Boolean | If true, fields with zero values will be copied as well |
-| server | string | vtworker or vttablet to connect to |
-
-
-#### Arguments
-
-* <vtworker or vttablet> – Required.
-* <throttler name> – Optional.
-
-#### Errors
-
-* Failed to unmarshal the configuration protobuf text (%v) into a protobuf instance: %v
-* error creating a throttler client for <server> '%v': %v
-* failed to update the throttler configuration on <server> '%v': %v
-
-
-## Schema, Version, Permissions
-
-* [ApplySchema](#applyschema)
-* [ApplyVSchema](#applyvschema)
-* [CopySchemaShard](#copyschemashard)
-* [GetPermissions](#getpermissions)
-* [GetSchema](#getschema)
-* [GetVSchema](#getvschema)
-* [RebuildVSchemaGraph](#rebuildvschemagraph)
-* [ReloadSchema](#reloadschema)
-* [ReloadSchemaKeyspace](#reloadschemakeyspace)
-* [ReloadSchemaShard](#reloadschemashard)
-* [ValidatePermissionsKeyspace](#validatepermissionskeyspace)
-* [ValidatePermissionsShard](#validatepermissionsshard)
-* [ValidateSchemaKeyspace](#validateschemakeyspace)
-* [ValidateSchemaShard](#validateschemashard)
-* [ValidateVersionKeyspace](#validateversionkeyspace)
-* [ValidateVersionShard](#validateversionshard)
-
-### ApplySchema
-
-Applies the schema change to the specified keyspace on every master, running in parallel on all shards. The changes are then propagated to slaves via replication. If -allow_long_unavailability is set, schema changes affecting a large number of rows (and possibly incurring a longer period of unavailability) will not be rejected.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| allow_long_unavailability | Boolean | Allow large schema changes which incur a longer unavailability of the database. |
-| sql | string | A list of semicolon-delimited SQL commands |
-| sql-file | string | Identifies the file that contains the SQL commands |
-| wait_slave_timeout | Duration | The amount of time to wait for slaves to receive the schema change via replication. |
-
-
-#### Arguments
-
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace> argument is required for the command<ApplySchema> command This error occurs if the command is not called with exactly one argument.
-
-
-### ApplyVSchema
-
-Applies the VTGate routing schema to the provided keyspace. Shows the result after application.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| cells | string | If specified, limits the rebuild to the cells, after upload. Ignored if skipRebuild is set. |
-| skip_rebuild | Boolean | If set, do no rebuild the SrvSchema objects. |
-| dry-run | Boolean | Shows the proposed change without executing it |
-| vschema | string | Identifies the VTGate routing schema |
-| vschema_file | string | Identifies the VTGate routing schema file |
-| sql | string | Identifies a VSchema DDL SQL statement |
-| sql_file | string | Identifies a VSchema DDL SQL statement |
-
-
-#### Arguments
-
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace> argument is required for the <ApplyVSchema> command This error occurs if the command is not called with exactly one argument.
-* either the <vschema> or <vschema>File flag must be specified when calling the <ApplyVSchema> command
-
-
-### CopySchemaShard
-
-Copies the schema from a source shard's master (or a specific tablet) to a destination shard. The schema is applied directly on the master of the destination shard, and it is propagated to the replicas through binlogs.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ |
-| include-views | Boolean | Includes views in the output |
-| tables | string | Specifies a comma-separated list of tables to copy. Each is either an exact match, or a regular expression of the form /regexp/ |
-| wait_slave_timeout | Duration | The amount of time to wait for slaves to receive the schema change via replication. |
-
-
-#### Arguments
-
-* <source tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-* <destination keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <source keyspace/shard> and <destination keyspace/shard> arguments are both required for the <CopySchemaShard> command. Instead of the <source keyspace/shard> argument, you can also specify <tablet alias> which refers to a specific tablet of the shard in the source keyspace This error occurs if the command is not called with exactly 2 arguments.
-
-
-### GetPermissions
-
-Displays the permissions for a tablet.
-
-#### Example
-
-
GetPermissions <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <GetPermissions> command This error occurs if the command is not called with exactly one argument.
-
-
-### GetSchema
-
-Displays the full schema for a tablet, or just the schema for the specified tables in that tablet.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ |
-| include-views | Boolean | Includes views in the output |
-| table_names_only | Boolean | Only displays table names that match |
-| tables | string | Specifies a comma-separated list of tables for which we should gather information. Each is either an exact match, or a regular expression of the form /regexp/ |
-
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <GetSchema> command This error occurs if the command is not called with exactly one argument.
-
-
-### GetVSchema
-
-Displays the VTGate routing schema.
-
-#### Example
-
-
GetVSchema <keyspace>
-
-#### Arguments
-
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace> argument is required for the <GetVSchema> command This error occurs if the command is not called with exactly one argument.
-
-
-### RebuildVSchemaGraph
-
-Rebuilds the cell-specific SrvVSchema from the global VSchema objects in the provided cells (or all cells if none provided).
-
-#### Example
-
-
RebuildVSchemaGraph [-cells=c1,c2,...]
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| cells | string | Specifies a comma-separated list of cells to look for tablets |
-
-
-#### Errors
-
-* <RebuildVSchemaGraph> doesn't take any arguments This error occurs if the command is not called with exactly 0 arguments.
-
-
-### ReloadSchema
-
-Reloads the schema on a remote tablet.
-
-#### Example
-
-
ReloadSchema <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <ReloadSchema> command This error occurs if the command is not called with exactly one argument.
-
-
-### ReloadSchemaKeyspace
-
-Reloads the schema on all the tablets in a keyspace.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| concurrency | Int | How many tablets to reload in parallel |
-| include_master | Boolean | Include the master tablet(s) |
-
-
-#### Arguments
-
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace> argument is required for the <ReloadSchemaKeyspace> command This error occurs if the command is not called with exactly one argument.
-
-
-### ReloadSchemaShard
-
-Reloads the schema on all the tablets in a shard.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| concurrency | Int | How many tablets to reload in parallel |
-| include_master | Boolean | Include the master tablet |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <ReloadSchemaShard> command This error occurs if the command is not called with exactly one argument.
-
-
-### ValidatePermissionsKeyspace
-
-Validates that the master permissions from shard 0 match those of all of the other tablets in the keyspace.
-
-#### Example
-
-
ValidatePermissionsKeyspace <keyspace name>
-
-#### Arguments
-
-* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace name> argument is required for the <ValidatePermissionsKeyspace> command This error occurs if the command is not called with exactly one argument.
-
-
-### ValidatePermissionsShard
-
-Validates that the master permissions match all the slaves.
-
-#### Example
-
-
ValidatePermissionsShard <keyspace/shard>
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <ValidatePermissionsShard> command This error occurs if the command is not called with exactly one argument.
-
-
-### ValidateSchemaKeyspace
-
-Validates that the master schema from shard 0 matches the schema on all of the other tablets in the keyspace.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ |
-| include-views | Boolean | Includes views in the validation |
-
-
-#### Arguments
-
-* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace name> argument is required for the <ValidateSchemaKeyspace> command This error occurs if the command is not called with exactly one argument.
-
-
-### ValidateSchemaShard
-
-Validates that the master schema matches all of the slaves.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ |
-| include-views | Boolean | Includes views in the validation |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <ValidateSchemaShard> command This error occurs if the command is not called with exactly one argument.
-
-
-### ValidateVersionKeyspace
-
-Validates that the master version from shard 0 matches all of the other tablets in the keyspace.
-
-#### Example
-
-
ValidateVersionKeyspace <keyspace name>
-
-#### Arguments
-
-* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace name> argument is required for the <ValidateVersionKeyspace> command This error occurs if the command is not called with exactly one argument.
-
-
-### ValidateVersionShard
-
-Validates that the master version matches all of the slaves.
-
-#### Example
-
-
ValidateVersionShard <keyspace/shard>
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <ValidateVersionShard> command This error occurs if the command is not called with exactly one argument.
-
-
-## Serving Graph
-
-* [GetSrvKeyspace](#getsrvkeyspace)
-* [GetSrvKeyspaceNames](#getsrvkeyspacenames)
-* [GetSrvVSchema](#getsrvvschema)
-
-### GetSrvKeyspace
-
-Outputs a JSON structure that contains information about the SrvKeyspace.
-
-#### Example
-
-
GetSrvKeyspace <cell> <keyspace>
-
-#### Arguments
-
-* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace.
-
-#### Errors
-
-* the <cell> and <keyspace> arguments are required for the <GetSrvKeyspace> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### GetSrvKeyspaceNames
-
-Outputs a list of keyspace names.
-
-#### Example
-
-
GetSrvKeyspaceNames <cell>
-
-#### Arguments
-
-* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-
-#### Errors
-
-* the <cell> argument is required for the <GetSrvKeyspaceNames> command This error occurs if the command is not called with exactly one argument.
-
-
-### GetSrvVSchema
-
-Outputs a JSON structure that contains information about the SrvVSchema.
-
-#### Example
-
-
GetSrvVSchema <cell>
-
-#### Arguments
-
-* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-
-#### Errors
-
-* the <cell> argument is required for the <GetSrvVSchema> command This error occurs if the command is not called with exactly one argument.
-
-
-## Shards
-
-* [CreateShard](#createshard)
-* [DeleteShard](#deleteshard)
-* [EmergencyReparentShard](#emergencyreparentshard)
-* [GetShard](#getshard)
-* [InitShardMaster](#initshardmaster)
-* [ListBackups](#listbackups)
-* [ListShardTablets](#listshardtablets)
-* [PlannedReparentShard](#plannedreparentshard)
-* [RemoveBackup](#removebackup)
-* [RemoveShardCell](#removeshardcell)
-* [SetShardIsMasterServing](#setshardismasterserving)
-* [SetShardTabletControl](#setshardtabletcontrol)
-* [ShardReplicationFix](#shardreplicationfix)
-* [ShardReplicationPositions](#shardreplicationpositions)
-* [SourceShardAdd](#sourceshardadd)
-* [SourceShardDelete](#sourcesharddelete)
-* [TabletExternallyReparented](#tabletexternallyreparented)
-* [ValidateShard](#validateshard)
-* [WaitForFilteredReplication](#waitforfilteredreplication)
-
-### CreateShard
-
-Creates the specified shard.
-
-#### Example
-
-
CreateShard [-force] [-parent] <keyspace/shard>
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| force | Boolean | Proceeds with the command even if the keyspace already exists |
-| parent | Boolean | Creates the parent keyspace if it doesn't already exist |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <CreateShard> command This error occurs if the command is not called with exactly one argument.
-
-
-### DeleteShard
-
-Deletes the specified shard(s). In recursive mode, it also deletes all tablets belonging to the shard. Otherwise, there must be no tablets left in the shard.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| even_if_serving | Boolean | Remove the shard even if it is serving. Use with caution. |
-| recursive | Boolean | Also delete all tablets belonging to the shard. |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>. To specify multiple values for this argument, separate individual values with a space.
-
-#### Errors
-
-* the <keyspace/shard> argument must be used to identify at least one keyspace and shard when calling the <DeleteShard> command This error occurs if the command is not called with at least one argument.
-
-
-### EmergencyReparentShard
-
-Reparents the shard to the new master. Assumes the old master is dead and not responsding.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented |
-| new_master | string | alias of a tablet that should be the new master |
-| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting |
-
-
-#### Errors
-
-* action <EmergencyReparentShard> requires -keyspace_shard=<keyspace/shard> -new_master=<tablet alias> This error occurs if the command is not called with exactly 0 arguments.
-* active reparent commands disabled (unset the -disable_active_reparents flag to enable)
-* cannot use legacy syntax and flag -<new_master> for action <EmergencyReparentShard> at the same time
-
-
-### GetShard
-
-Outputs a JSON structure that contains information about the Shard.
-
-#### Example
-
-
GetShard <keyspace/shard>
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <GetShard> command This error occurs if the command is not called with exactly one argument.
-
-
-### InitShardMaster
-
-Sets the initial master for a shard. Will make all other tablets in the shard slaves of the provided master. WARNING: this could cause data loss on an already replicating shard. PlannedReparentShard or EmergencyReparentShard should be used instead.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| force | Boolean | will force the reparent even if the provided tablet is not a master or the shard master |
-| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* action <InitShardMaster> requires <keyspace/shard><tablet alias> This error occurs if the command is not called with exactly 2 arguments.
-* active reparent commands disabled (unset the -disable_active_reparents flag to enable)
-
-
-### ListBackups
-
-Lists all the backups for a shard.
-
-#### Example
-
-
ListBackups <keyspace/shard>
-
-#### Errors
-
-* action <ListBackups> requires <keyspace/shard> This error occurs if the command is not called with exactly one argument.
-
-
-### ListShardTablets
-
-Lists all tablets in the specified shard.
-
-#### Example
-
-
ListShardTablets <keyspace/shard>
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <ListShardTablets> command This error occurs if the command is not called with exactly one argument.
-
-
-### PlannedReparentShard
-
-Reparents the shard to the new master, or away from old master. Both old and new master need to be up and running.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| avoid_master | string | alias of a tablet that should not be the master, i.e. reparent to any other tablet if this one is the master |
-| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented |
-| new_master | string | alias of a tablet that should be the new master |
-| wait_slave_timeout | Duration | time to wait for slaves to catch up in reparenting |
-
-
-#### Errors
-
-* action <PlannedReparentShard> requires -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>] This error occurs if the command is not called with exactly 0 arguments.
-* active reparent commands disabled (unset the -disable_active_reparents flag to enable)
-* cannot use legacy syntax and flags -<keyspace_shard> and -<new_master> for action <PlannedReparentShard> at the same time
-
-
-### RemoveBackup
-
-Removes a backup for the BackupStorage.
-
-#### Example
-
-
RemoveBackup <keyspace/shard> <backup name>
-
-#### Arguments
-
-* <backup name> – Required.
-
-#### Errors
-
-* action <RemoveBackup> requires <keyspace/shard><backup name> This error occurs if the command is not called with exactly 2 arguments.
-
-
-### RemoveShardCell
-
-Removes the cell from the shard's Cells list.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| force | Boolean | Proceeds even if the cell's topology server cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. |
-| recursive | Boolean | Also delete all tablets in that cell belonging to the specified shard. |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-
-#### Errors
-
-* the <keyspace/shard> and <cell> arguments are required for the <RemoveShardCell> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### SetShardIsMasterServing
-
-Add or remove a shard from serving. This is meant as an emergency function. It does not rebuild any serving graph i.e. does not run 'RebuildKeyspaceGraph'.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| cells | string | Specifies a comma-separated list of cells to update |
-| remove | Boolean | Removes the served tablet type |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-* <served tablet type> – Required. The vttablet's role. Valid values are:
-
- * backup – A slaved copy of data that is offline to queries other than for backup purposes
- * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
- * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication.
- * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
- * master – A primary copy of data
- * rdonly – A slaved copy of data for OLAP load patterns
- * replica – A slaved copy of data ready to be promoted to master
- * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
- * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
- * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode:
vtctl Snapshot -server-mode ...
Use this command to exit this mode:
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
-
-
-
-
-#### Errors
-
-* the <keyspace/shard> and <served tablet type> arguments are both required for the <SetShardServedTypes> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### SetShardTabletControl
-
-Sets the TabletControl record for a shard and type. Only use this for an emergency fix or after a finished vertical split. The *MigrateServedFrom* and *MigrateServedType* commands set this field appropriately already. Always specify the blacklisted_tables flag for vertical splits, but never for horizontal splits.
To set the DisableQueryServiceFlag, keep 'blacklisted_tables' empty, and set 'disable_query_service' to true or false. Useful to fix horizontal splits gone wrong.
To change the blacklisted tables list, specify the 'blacklisted_tables' parameter with the new list. Useful to fix tables that are being blocked after a vertical split.
To just remove the ShardTabletControl entirely, use the 'remove' flag, useful after a vertical split is finished to remove serving restrictions.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| blacklisted_tables | string | Specifies a comma-separated list of tables to blacklist (used for vertical split). Each is either an exact match, or a regular expression of the form '/regexp/'. |
-| cells | string | Specifies a comma-separated list of cells to update |
-| disable_query_service | Boolean | Disables query service on the provided nodes. This flag requires 'blacklisted_tables' and 'remove' to be unset, otherwise it's ignored. |
-| remove | Boolean | Removes cells for vertical splits. |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-* <tablet type> – Required. The vttablet's role. Valid values are:
-
- * backup – A slaved copy of data that is offline to queries other than for backup purposes
- * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
- * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication.
- * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
- * master – A primary copy of data
- * rdonly – A slaved copy of data for OLAP load patterns
- * replica – A slaved copy of data ready to be promoted to master
- * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
- * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
- * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode:
vtctl Snapshot -server-mode ...
Use this command to exit this mode:
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
-
-
-
-
-#### Errors
-
-* the <keyspace/shard> and <tablet type> arguments are both required for the <SetShardTabletControl> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### ShardReplicationFix
-
-Walks through a ShardReplication object and fixes the first error that it encounters.
-
-#### Example
-
-
ShardReplicationFix <cell> <keyspace/shard>
-
-#### Arguments
-
-* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <cell> and <keyspace/shard> arguments are required for the ShardReplicationRemove command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### ShardReplicationPositions
-
-Shows the replication status of each slave machine in the shard graph. In this case, the status refers to the replication lag between the master vttablet and the slave vttablet. In Vitess, data is always written to the master vttablet first and then replicated to all slave vttablets. Output is sorted by tablet type, then replication position. Use ctrl-C to interrupt command and see partial result if needed.
-
-#### Example
-
-
ShardReplicationPositions <keyspace/shard>
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <ShardReplicationPositions> command This error occurs if the command is not called with exactly one argument.
-
-
-### SourceShardAdd
-
-Adds the SourceShard record with the provided index. This is meant as an emergency function. It does not call RefreshState for the shard master.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| key_range | string | Identifies the key range to use for the SourceShard |
-| tables | string | Specifies a comma-separated list of tables to replicate (used for vertical split). Each is either an exact match, or a regular expression of the form /regexp/ |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-* <uid> – Required.
-* <source keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard>, <uid>, and <source keyspace/shard> arguments are all required for the <SourceShardAdd> command This error occurs if the command is not called with exactly 3 arguments.
-
-
-### SourceShardDelete
-
-Deletes the SourceShard record with the provided index. This is meant as an emergency cleanup function. It does not call RefreshState for the shard master.
-
-#### Example
-
-
SourceShardDelete <keyspace/shard> <uid>
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-* <uid> – Required.
-
-#### Errors
-
-* the <keyspace/shard> and <uid> arguments are both required for the <SourceShardDelete> command This error occurs if the command is not called with at least 2 arguments.
-
-
-### TabletExternallyReparented
-
-Changes metadata in the topology server to acknowledge a shard master change performed by an external tool. See the Reparenting guide for more information:https://github.com/vitessio/vitess/blob/master/doc/Reparenting.md#external-reparents.
-
-#### Example
-
-
TabletExternallyReparented <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <TabletExternallyReparented> command This error occurs if the command is not called with exactly one argument.
-
-
-### ValidateShard
-
-Validates that all nodes that are reachable from this shard are consistent.
-
-#### Example
-
-
ValidateShard [-ping-tablets] <keyspace/shard>
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <ValidateShard> command This error occurs if the command is not called with exactly one argument.
-
-
-### WaitForFilteredReplication
-
-Blocks until the specified shard has caught up with the filtered replication of its source shard.
-
-#### Example
-
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <WaitForFilteredReplication> command This error occurs if the command is not called with exactly one argument.
-
-
-## Tablets
-
-* [Backup](#backup)
-* [ChangeSlaveType](#changeslavetype)
-* [DeleteTablet](#deletetablet)
-* [ExecuteFetchAsDba](#executefetchasdba)
-* [ExecuteHook](#executehook)
-* [GetTablet](#gettablet)
-* [IgnoreHealthError](#ignorehealtherror)
-* [InitTablet](#inittablet)
-* [Ping](#ping)
-* [RefreshState](#refreshstate)
-* [RefreshStateByShard](#refreshstatebyshard)
-* [ReparentTablet](#reparenttablet)
-* [RestoreFromBackup](#restorefrombackup)
-* [RunHealthCheck](#runhealthcheck)
-* [SetReadOnly](#setreadonly)
-* [SetReadWrite](#setreadwrite)
-* [Sleep](#sleep)
-* [StartSlave](#startslave)
-* [StopSlave](#stopslave)
-* [UpdateTabletAddrs](#updatetabletaddrs)
-
-### Backup
-
-Stops mysqld and uses the BackupStorage service to store a new backup. This function also remembers if the tablet was replicating so that it can restore the same state after the backup completes.
-
-#### Example
-
-
Backup [-concurrency=4] <tablet alias>
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| concurrency | Int | Specifies the number of compression/checksum jobs to run simultaneously |
-
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <Backup> command requires the <tablet alias> argument This error occurs if the command is not called with exactly one argument.
-
-
-### ChangeSlaveType
-
-Changes the db type for the specified tablet, if possible. This command is used primarily to arrange replicas, and it will not convert a master.
NOTE: This command automatically updates the serving graph.
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| dry-run | Boolean | Lists the proposed change without actually executing it |
-
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-* <tablet type> – Required. The vttablet's role. Valid values are:
-
- * backup – A slaved copy of data that is offline to queries other than for backup purposes
- * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
- * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication.
- * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
- * master – A primary copy of data
- * rdonly – A slaved copy of data for OLAP load patterns
- * replica – A slaved copy of data ready to be promoted to master
- * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
- * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
- * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode:
vtctl Snapshot -server-mode ...
Use this command to exit this mode:
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
-
-
-
-
-#### Errors
-
-* the <tablet alias> and <db type> arguments are required for the <ChangeSlaveType> command This error occurs if the command is not called with exactly 2 arguments.
-* failed reading tablet %v: %v
-* invalid type transition %v: %v -> %v
-
-
-### DeleteTablet
-
-Deletes tablet(s) from the topology.
-
-#### Example
-
-
DeleteTablet [-allow_master] <tablet alias> ...
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| allow_master | Boolean | Allows for the master tablet of a shard to be deleted. Use with caution. |
-
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space.
-
-#### Errors
-
-* the <tablet alias> argument must be used to specify at least one tablet when calling the <DeleteTablet> command This error occurs if the command is not called with at least one argument.
-
-
-### ExecuteFetchAsDba
-
-Runs the given SQL command as a DBA on the remote tablet.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| disable_binlogs | Boolean | Disables writing to binlogs during the query |
-| json | Boolean | Output JSON instead of human-readable table |
-| max_rows | Int | Specifies the maximum number of rows to allow in reset |
-| reload_schema | Boolean | Indicates whether the tablet schema will be reloaded after executing the SQL command. The default value is false, which indicates that the tablet schema will not be reloaded. |
-
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-* <sql command> – Required.
-
-#### Errors
-
-* the <tablet alias> and <sql command> arguments are required for the <ExecuteFetchAsDba> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### ExecuteHook
-
-Runs the specified hook on the given tablet. A hook is a script that resides in the $VTROOT/vthook directory. You can put any script into that directory and use this command to run that script.
For this command, the param=value arguments are parameters that the command passes to the specified hook.
-
-#### Example
-
-
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-* <hook name> – Required.
-* <param1=value1><param2=value2> . – Optional.
-
-#### Errors
-
-* the <tablet alias> and <hook name> arguments are required for the <ExecuteHook> command This error occurs if the command is not called with at least 2 arguments.
-
-
-### GetTablet
-
-Outputs a JSON structure that contains information about the Tablet.
-
-#### Example
-
-
GetTablet <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <GetTablet> command This error occurs if the command is not called with exactly one argument.
-
-
-### IgnoreHealthError
-
-Sets the regexp for health check errors to ignore on the specified tablet. The pattern has implicit ^$ anchors. Set to empty string or restart vttablet to stop ignoring anything.
-
-#### Example
-
-
IgnoreHealthError <tablet alias> <ignore regexp>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-* <ignore regexp> – Required.
-
-#### Errors
-
-* the <tablet alias> and <ignore regexp> arguments are required for the <IgnoreHealthError> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### InitTablet
-
-Initializes a tablet in the topology.
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| allow_master_override | Boolean | Use this flag to force initialization if a tablet is created as master, and a master for the keyspace/shard already exists. Use with caution. |
-| allow_update | Boolean | Use this flag to force initialization if a tablet with the same name already exists. Use with caution. |
-| db_name_override | string | Overrides the name of the database that the vttablet uses |
-| grpc_port | Int | The gRPC port for the vttablet process |
-| hostname | string | The server on which the tablet is running |
-| keyspace | string | The keyspace to which this tablet belongs |
-| mysql_host | string | The mysql host for the mysql server |
-| mysql_port | Int | The mysql port for the mysql server |
-| parent | Boolean | Creates the parent shard and keyspace if they don't yet exist |
-| port | Int | The main port for the vttablet process |
-| shard | string | The shard to which this tablet belongs |
-| tags | string | A comma-separated list of key:value pairs that are used to tag the tablet |
-
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-* <tablet type> – Required. The vttablet's role. Valid values are:
-
- * backup – A slaved copy of data that is offline to queries other than for backup purposes
- * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs)
- * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication.
- * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting.
- * master – A primary copy of data
- * rdonly – A slaved copy of data for OLAP load patterns
- * replica – A slaved copy of data ready to be promoted to master
- * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state.
- * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type.
- * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode:
vtctl Snapshot -server-mode ...
Use this command to exit this mode:
vtctl SnapshotSourceEnd ...
- * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet.
-
-
-
-
-#### Errors
-
-* the <tablet alias> and <tablet type> arguments are both required for the <InitTablet> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### Ping
-
-Checks that the specified tablet is awake and responding to RPCs. This command can be blocked by other in-flight operations.
-
-#### Example
-
-
Ping <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <Ping> command This error occurs if the command is not called with exactly one argument.
-
-
-### RefreshState
-
-Reloads the tablet record on the specified tablet.
-
-#### Example
-
-
RefreshState <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <RefreshState> command This error occurs if the command is not called with exactly one argument.
-
-
-### RefreshStateByShard
-
-Runs 'RefreshState' on all tablets in the given shard.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| cells | string | Specifies a comma-separated list of cells whose tablets are included. If empty, all cells are considered. |
-
-
-#### Arguments
-
-* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitepace, while the shard is typically identified by a string in the format <range start>-<range end>.
-
-#### Errors
-
-* the <keyspace/shard> argument is required for the <RefreshStateByShard> command This error occurs if the command is not called with exactly one argument.
-
-
-### ReparentTablet
-
-Reparent a tablet to the current master in the shard. This only works if the current slave position matches the last known reparent action.
-
-#### Example
-
-
ReparentTablet <tablet alias>
-
-#### Errors
-
-* action <ReparentTablet> requires <tablet alias> This error occurs if the command is not called with exactly one argument.
-* active reparent commands disabled (unset the -disable_active_reparents flag to enable)
-
-
-### RestoreFromBackup
-
-Stops mysqld and restores the data from the latest backup.
-
-#### Example
-
-
RestoreFromBackup <tablet alias>
-
-#### Errors
-
-* the <RestoreFromBackup> command requires the <tablet alias> argument This error occurs if the command is not called with exactly one argument.
-
-
-### RunHealthCheck
-
-Runs a health check on a remote tablet.
-
-#### Example
-
-
RunHealthCheck <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <RunHealthCheck> command This error occurs if the command is not called with exactly one argument.
-
-
-### SetReadOnly
-
-Sets the tablet as read-only.
-
-#### Example
-
-
SetReadOnly <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <SetReadOnly> command This error occurs if the command is not called with exactly one argument.
-* failed reading tablet %v: %v
-
-
-### SetReadWrite
-
-Sets the tablet as read-write.
-
-#### Example
-
-
SetReadWrite <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <SetReadWrite> command This error occurs if the command is not called with exactly one argument.
-* failed reading tablet %v: %v
-
-
-### Sleep
-
-Blocks the action queue on the specified tablet for the specified amount of time. This is typically used for testing.
-
-#### Example
-
-
Sleep <tablet alias> <duration>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-* <duration> – Required. The amount of time that the action queue should be blocked. The value is a string that contains a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms" or "1h45m". See the definition of the Go language's ParseDuration function for more details. Note that, in practice, the value should be a positively signed value.
-
-#### Errors
-
-* the <tablet alias> and <duration> arguments are required for the <Sleep> command This error occurs if the command is not called with exactly 2 arguments.
-
-
-### StartSlave
-
-Starts replication on the specified slave.
-
-#### Example
-
-
StartSlave <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* action <StartSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument.
-* failed reading tablet %v: %v
-
-
-### StopSlave
-
-Stops replication on the specified slave.
-
-#### Example
-
-
StopSlave <tablet alias>
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* action <StopSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument.
-* failed reading tablet %v: %v
-
-
-### UpdateTabletAddrs
-
-Updates the IP address and port numbers of a tablet.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| grpc-port | Int | The gRPC port for the vttablet process |
-| hostname | string | The fully qualified host name of the server on which the tablet is running. |
-| mysql-port | Int | The mysql port for the mysql daemon |
-| mysql_host | string | The mysql host for the mysql server |
-| vt-port | Int | The main port for the vttablet process |
-
-
-#### Arguments
-
-* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>.
-
-#### Errors
-
-* the <tablet alias> argument is required for the <UpdateTabletAddrs> command This error occurs if the command is not called with exactly one argument.
-
-
-## Topo
-
-* [TopoCat](#topocat)
-
-### TopoCat
-
-Retrieves the file(s) at <path> from the topo service, and displays it. It can resolve wildcards, and decode the proto-encoded data.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| cell | string | topology cell to cat the file from. Defaults to global cell. |
-| decode_proto | Boolean | decode proto files and display them as text |
-| long | Boolean | long listing. |
-
-
-#### Arguments
-
-* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace.
-* <path> – Required.
-* <path>. – Optional.
-
-#### Errors
-
-* <TopoCat>: no path specified This error occurs if the command is not called with at least one argument.
-* <TopoCat>: invalid wildcards: %v
-* <TopoCat>: some paths had errors
-
-
-## Workflows
-
-* [WorkflowAction](#workflowaction)
-* [WorkflowCreate](#workflowcreate)
-* [WorkflowDelete](#workflowdelete)
-* [WorkflowStart](#workflowstart)
-* [WorkflowStop](#workflowstop)
-* [WorkflowTree](#workflowtree)
-* [WorkflowWait](#workflowwait)
-
-### WorkflowAction
-
-Sends the provided action name on the specified path.
-
-#### Example
-
-
WorkflowAction <path> <name>
-
-#### Arguments
-
-* <name> – Required.
-
-#### Errors
-
-* the <path> and <name> arguments are required for the <WorkflowAction> command This error occurs if the command is not called with exactly 2 arguments.
-* no workflow.Manager registered
-
-
-### WorkflowCreate
-
-Creates the workflow with the provided parameters. The workflow is also started, unless -skip_start is specified.
-
-#### Example
-
-
-
-#### Flags
-
-| Name | Type | Definition |
-| :-------- | :--------- | :--------- |
-| skip_start | Boolean | If set, the workflow will not be started. |
-
-
-#### Arguments
-
-* <factoryName> – Required.
-
-#### Errors
-
-* the <factoryName> argument is required for the <WorkflowCreate> command This error occurs if the command is not called with at least one argument.
-* no workflow.Manager registered
-
-
-### WorkflowDelete
-
-Deletes the finished or not started workflow.
-
-#### Example
-
-
WorkflowDelete <uuid>
-
-#### Errors
-
-* the <uuid> argument is required for the <WorkflowDelete> command This error occurs if the command is not called with exactly one argument.
-* no workflow.Manager registered
-
-
-### WorkflowStart
-
-Starts the workflow.
-
-#### Example
-
-
WorkflowStart <uuid>
-
-#### Errors
-
-* the <uuid> argument is required for the <WorkflowStart> command This error occurs if the command is not called with exactly one argument.
-* no workflow.Manager registered
-
-
-### WorkflowStop
-
-Stops the workflow.
-
-#### Example
-
-
WorkflowStop <uuid>
-
-#### Errors
-
-* the <uuid> argument is required for the <WorkflowStop> command This error occurs if the command is not called with exactly one argument.
-* no workflow.Manager registered
-
-
-### WorkflowTree
-
-Displays a JSON representation of the workflow tree.
-
-#### Example
-
-
WorkflowTree
-
-#### Errors
-
-* the <WorkflowTree> command takes no parameter This error occurs if the command is not called with exactly 0 arguments.
-* no workflow.Manager registered
-
-
-### WorkflowWait
-
-Waits for the workflow to finish.
-
-#### Example
-
-
-
-*Image Source:* https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows
-
-The Vitess code is hosted on GitHub (https://github.com/vitessio/vitess).
-This repository is called *upstream*.
-You develop and commit your changes in a clone of our upstream repository (shown as *local* in the image above).
-Then you push your changes to your forked repository (*origin*) and send us a pull request.
-Eventually, we will merge your pull request back into the *upstream* repository.
-
-## Remotes
-
-Since you should have cloned the repository from your fork, the `origin` remote
-should look like this:
-
-```
-$ git remote -v
-origin git@github.com:
-
-Quickstart
-
-