Run Vitess with Vagrant

Instructions for building Vitess on your machine for testing and development purposes using Vagrant

Vagrant is a tool for building and managing virtual machine environments in a single workflow. With an easy-to-use workflow and focus on automation, Vagrant lowers development environment setup time, increases production parity, and makes the “works on my machine” excuse a relic of the past.

The following guide will show you how to build and run Vitess in your local environment using this tool.

If you run into issues or have questions, we recommend posting in our Slack channel, click the Slack icon in the top right to join. This is a very active community forum and a great place to interact with other users.

Install dependencies

Build Vitess

  • Clone Vitess repo into your local environment:
  1. git clone https://github.com/vitessio/vitess.git
  • From the repo directory run the following command:
  1. vagrant up

This will bootstrap the VM with all Vitess dependencies.

  • Once the bootstrap is done run the following:
  1. vagrant ssh

The first time you connect to the VM, it will automatically build vitess for you.

  • Moving forward, if you want to build the project you just need to run:shmake build

Run Tests

If you are using etcd, set the following environment variable:

  1. export VT_TEST_FLAGS='--topo-server-flavor=etcd2'

If you are using Consul, set the following environment variable:

  1. 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.

If you want only to check that Vitess is working in your environment, you can run a lighter set of tests:

  1. make site_test

Start a Vitess cluster

After completing the instructions above to 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 etcd2 as the default topology service plugin.

  • Start Cluster
  1. (local) vagrant@vitess:/vagrant/src/vitess.io/vitess$ vagrant-scripts/vitess/start.sh

Note: This will start a full Vitess cluster with a single shard and five tablets.

  • Connect to VTGateFrom the VM, you can connect to VTGate using the MySQL protocol with the following command:
  1. mysql -umysql_user -pmysql_password -h vitess -P 15306

There is a messages table ready for you to use:

  1. mysql> select count(*) from messages;
  2. +----------+
  3. | count(*) |
  4. +----------+
  5. |        0 |
  6. +----------+
  7. 1 row in set (0.01 sec)

Also, vtgate admin UI is available in http://localhost:15001

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

  • use the client.sh wrapper script, which temporarily sets up the environment and then runs client.py.
  1. export VTROOT=/vagrant
  2. export VTDATAROOT=/tmp/vtdata-dev
  3. export MYSQL_FLAVOR=MySQL56
  4. cd "$VITESS_WORKSPACE"/examples/local
  5. ./client.sh
  6. ### example output:
  7. # Inserting into master...
  8. # Reading from master...
  9. # (5L, 1462510331910124032L, 'V is for speed')
  10. # (15L, 1462519383758071808L, 'V is for speed')
  11. # (42L, 1462510369213753088L, 'V is for speed')
  12. # ...

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.

Tear down the cluster

When you are done testing, you can tear down the cluster with the following script:

  1. (local) vagrant@vitess:/vagrant/src/vitess.io/vitess$ vagrant-scripts/vitess/stop.sh

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 Slack channel. 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.