This guide covers using the vttestserver docker image for testing purposes. This is also the docker image that we use for testing in Vitess Framework Testing.

Get the docker image #

The first step is to get the docker image. There are two ways of doing this :

1. From the vitessio/vitess repository #

Check out the vitessio/vitess repository #

Clone the GitHub repository via:

• SSH: git clone git@github.com:vitessio/vitess.git, or:
• HTTP: git clone https://github.com/vitessio/vitess.git

cd vitess
git checkout release-19.0

Build the docker image #

In your shell, execute:

make docker_vttestserver

This creates 2 docker images named vitess/vttestserver:mysql57 and vitess/vttestserver:mysql80

2. Pulling from docker hub #

Alternately, you can get the latest docker images from the docker hub. In your shell, execute:

docker pull vitess/vttestserver:mysql57
docker pull vitess/vttestserver:mysql80

Run the docker image #

At this point, you should have a docker image named vitess/vttestserver:mysql57 or vitess/vttestserver:mysql80.

Environment variables #

The docker image expects some of the environment variables to be set to function properly. The following table lists all the environment variables available along with their usages.

Environment variables in docker can be specified using the -e aka --env flag.

Sending queries to vttestserver container from outside #

The vtgate listens for MySQL connections on 3 + the PORT environment variable specified. i.e. if you specify PORT to be 33574, then vtgate will be listening to connections on 33577, on the MYSQL_BIND_HOST which defaults to localhost. But this port will be on the docker container side. To connect to vtgate externally from a MySQL client, you will need to publish that port as well and specify the MYSQL_BIND_HOST to 0.0.0.0. This can be done via the -p aka --publish flag to docker. For eg: adding -p 33577:33577 to the docker run command will publish the container's 33577 port to your local 33577 port, which can now be used to connect to the vtgate.

Viewing the vtcombo /debug/status dashboard and running vtctld commands #

The vtcombo /debug/status page is viewable at the port specified by the PORT environment variable on the docker side. To view it in a browser outside, you will need to publish that port as well and specify the VTCOMBO_BIND_HOST to 0.0.0.0. This can be done via the -p aka --publish flag to docker.

Similarily, vtctld listens for grpc requests at the port 1 + PORT. So, in order to run vtctld commands using vtctldclient binary, this port must also be published.

Persisting container data #

If you wish to keep the state of the test container across reboots, such as when running the vttestserver container as a database container in local application development environments, you may optionally pass the --persistent_mode flag, along with a --data_dir directory which is bound to a docker volume. Due to a bug, the --port argument must also be present for correct operation.

When running in this mode, underlying MySQL table schemas, their data, and the Vitess VSchema objects are persisted under the provided --data_dir.

For example:

docker run --name=vttestserver \
  -p 33574:33574 \
  -p 33575:33575 \
  -p 33577:33577 \
  --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" \
  --health-interval=5s \
  --health-timeout=2s \
  --health-retries=5 \
  -v vttestserver_data:/vt/vtdataroot \
  vitess/vttestserver:mysql80 \
  /vt/bin/vttestserver \
  --alsologtostderr \
  --data_dir=/vt/vtdataroot/ \
  --persistent_mode \
  --port=33574 \
  --mysql_bind_host=0.0.0.0 \
  --vtcombo-bind-host=0.0.0.0 \
  --keyspaces=test,unsharded \
  --num_shards=2,1

Example #

An example command to run the docker image is as follows :

docker run --name=vttestserver \
  -p 33574:33574 \
  -p 33575:33575 \
  -p 33577:33577 \
  -e PORT=33574 \
  -e KEYSPACES=test,unsharded \
  -e NUM_SHARDS=2,1 \
  -e MYSQL_MAX_CONNECTIONS=70000 \
  -e MYSQL_BIND_HOST=0.0.0.0 \
  -e VTCOMBO_BIND_HOST=0.0.0.0 \
  --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" \
  --health-interval=5s \
  --health-timeout=2s \
  --health-retries=5 \
  vitess/vttestserver:mysql80

Now, we can connect to the vtgate from a MySQL client as follows :

mysql --host 127.0.0.1 --port 33577 --user "root"

We have 2 keyspaces which we can use, test which has 2 shards and unsharded which has a single shard.

We can run vtctldclient commands as follows :

vtctldclient --server 127.0.0.1:33575 GetKeyspaces

And the vtcombo /debug/status page can be viewed at :

http://localhost:33574/debug/status