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.
Clone Vitess repo into your local environment:
git clone https://github.com/vitessio/vitess.git
From the repo directory run the following command:
This will bootstrap the VM with all Vitess dependencies.
Once the bootstrap is done run the following:
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:
If you are using etcd, set the following environment variable:
If you are using Consul, set the following environment variable:
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:
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 ZooKeeper as the lock service. ZooKeeper is included in the Vitess distribution.
(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 Vtgate
From the VM, you can connect to vtgate using mysql protocol with the following command:
mysql -umysql_user -pmysql_password -h vitess -P 15306
There is a messages table ready for you to use:
mysql> select count(*) from messages; +----------+ | count(*) | +----------+ | 0 | +----------+ 1 row in set (0.01 sec)
Also, vtgate admin UI is available in http://localhost:15001
Connect to Vtctld
Vitess cluster admin control UI is available in http://localhost:15000
Run a Client Application
client.py file is a simple sample application that connects to
vtgate and executes some queries. To run it, you need to either
client.shwrapper script, which temporarily sets up the environment and then runs
export VTROOT=/vagrant export VTDATAROOT=/tmp/vtdata-dev export MYSQL_FLAVOR=MySQL56 cd "$VITESS_WORKSPACE"/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.
Tear down the cluster
When you are done testing, you can tear down the cluster with the following script:
(local) vagrant@vitess:/vagrant/src/vitess.io/vitess$ vagrant-scripts/vitess/stop.sh
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
If you need help diagnosing a problem, send a message to our mailing list. 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.