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 local build instructions for macOS have improved signficantly over the last few months, and our Vagrant deployment has not kept up with all core-Vitess changes. We are currently seeking a new maintainer for Vagrant. If we do not find a maintainer, we intend to deprecate support for Vagrant.

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

  1. Install Vagrant in your OS.
  2. Install Virtual Box

Build Vitess

  1. Clone Vitess repo into your local environment:

    git clone 
    1. From the repo directory run the following command:
    vagrant up

    This will bootstrap the VM with all Vitess dependencies.

  2. Once the bootstrap is done run the following:

    vagrant ssh

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

    1. Moving forward, if you want to build the project you just need to run: sh make build

Run Tests

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

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

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

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:

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.

  1. Start Cluster

    (local) vagrant@vitess:/vagrant/src/$ vagrant-scripts/vitess/

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

    1. Connect to VTGate

    From the VM, you can connect to VTGate using the 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

    1. Connect to Vtctld

    Vitess cluster admin control UI is available in http://localhost:15000

    Run a Client Application

    The file is a simple sample application that connects to vtgate and executes some queries. To run it, you need to either

    • use the wrapper 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
    ### 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/$ vagrant-scripts/vitess/


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.