The following has been verified to work on macOS Mojave. If you are new to Vitess, it is recommended to start with the local install guide instead.

Install Dependencies #

Install Xcode #

Install Xcode.

Install Homebrew and Dependencies #

Install Homebrew. From here you should be able to install:

brew install automake git curl wget mysql nvm

Add mysql to your PATH:

echo 'export PATH="/usr/local/opt/mysql/bin:$PATH"' >> ~/.bash_profile

Download and install Golang. For example for go1.20.2, at writing:

curl -LO https://golang.org/dl/go1.20.2.darwin-amd64.pkg
sudo installer -pkg go1.20.2.darwin-amd64.pkg -target /

Vitess is tested and shipped using a specific Golang version for each release. For maximum compatibility we encourage you to use the same Golang version as the one mentioned in our build.env file.

Do not install etcd via brew otherwise it will not be the version that is supported. Let it be installed when running make build.

Do not set up MySQL or etcd to restart at login.

Install node >= 16.13.0 LTS (note you also need npm >= 8.1.0, which will come with node). For example, using nvm (which we installed earlier with homebrew):

nvm install --lts 16.13.0
nvm use 16.13.0

See the vtadmin README for more details.

Build Vitess #

Navigate to the directory where you want to download the Vitess source code and clone the Vitess GitHub repo:

cd ~
git clone https://github.com/vitessio/vitess.git
cd vitess

Set environment variables that Vitess will require. It is recommended to put these in your ~/.bash_profile file:

# Vitess binaries
export PATH=~/vitess/bin:${PATH}

Build Vitess:

make build

Since the addition of #13263 the vtadmin React application will be built when doing a make build. You can skip this step by setting the NOVTADMINBUILD environment variable.

NOVTADMINBUILD=1 make build

Testing your Binaries #

The unit tests require that you first install a Java runtime. This is required for running ZooKeeper tests:

brew tap adoptopenjdk/openjdk
brew install adoptopenjdk8
brew info java

You will also need to install ant and maven:

brew install ant maven

You can then install additional components from make tools. 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) first:

make tools
make unit_test

In addition to running tests, you can try running the local example.

Common Build Issues #

Key Already Exists #

This error is because etcd was not cleaned up from the previous run of the example. You can manually fix this by running ./401_teardown.sh, removing vtdataroot and then starting again:

Error:  105: Key already exists (/vitess/zone1) [6]
Error:  105: Key already exists (/vitess/global) [6]

/tmp/mysql.sock Already In Use #

This error occurs because mysql is serving on the same port that vttgate requires. To solve this issue stop mysql service. If you have installed mysql via brew as specified above you should run:

brew services stop mysql