This guide covers installing Vitess locally for testing purposes, from pre-compiled binaries. We will launch multiple copies of
mysqld, so it is recommended to have greater than 4GB RAM, as well as 20GB of available disk space.
A docker setup is also available, which requires no dependencies on your local host.
Install MySQL and etcd
Vitess supports MySQL 5.6+ and MariaDB 10.0+. We recommend MySQL 5.7 if your installation method provides a choice:
# Ubuntu based sudo apt install -y mysql-server etcd curl # Debian sudo apt install -y default-mysql-server default-mysql-client etcd curl # Yum based sudo yum -y localinstall https://dev.mysql.com/get/mysql57-community-release-el7-9.noarch.rpm sudo yum -y install mysql-community-server etcd curl
On apt-based distributions the services
etcd will need to be shutdown, since
etcd will conflict with the
etcd started in the examples, and
mysqlctl will start its own copies of
# Debian and Ubuntu sudo service mysql stop sudo service etcd stop sudo systemctl disable mysql sudo systemctl disable etcd
Disable AppArmor or SELinux
AppArmor/SELinux will not allow Vitess to launch MySQL in any data directory by default. You will need to disable it:
# Debian and Ubuntu sudo ln -s /etc/apparmor.d/usr.sbin.mysqld /etc/apparmor.d/disable/ sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.mysqld # The following command should return an empty result: sudo aa-status | grep mysqld
# CentOS sudo setenforce 0
Download the latest binary release for Vitess on Linux. For example with Vitess 6:
tar -xzf vitess-6.0.20-20200508-147bc5a.tar.gz cd vitess-6.0.20-20200508-147bc5a sudo mkdir -p /usr/local/vitess sudo mv * /usr/local/vitess/
Make sure to add
/usr/local/vitess/bin to the
PATH environment variable. You can do this by adding the following to your
You are now ready to start your first cluster! Open a new terminal window to ensure your
.bashrc file changes take effect.
Start a Single Keyspace Cluster
Start by copying the local examples included with Vitess to your preferred location. For our first example we will deploy a single unsharded keyspace. The file
101_initial_cluster.sh is for example
01. Lets execute it now:
cp -r /usr/local/vitess/examples/local ~/my-vitess-example cd ~/my-vitess-example ./101_initial_cluster.sh
You should see output similar to the following:
~/my-vitess-example> ./101_initial_cluster.sh $ ./101_initial_cluster.sh add /vitess/global add /vitess/zone1 add zone1 CellInfo etcd start done... Starting vtctld... Starting MySQL for tablet zone1-0000000100... Starting vttablet for zone1-0000000100... HTTP/1.1 200 OK Date: Wed, 25 Mar 2020 17:32:45 GMT Content-Type: text/html; charset=utf-8 Starting MySQL for tablet zone1-0000000101... Starting vttablet for zone1-0000000101... HTTP/1.1 200 OK Date: Wed, 25 Mar 2020 17:32:53 GMT Content-Type: text/html; charset=utf-8 Starting MySQL for tablet zone1-0000000102... Starting vttablet for zone1-0000000102... HTTP/1.1 200 OK Date: Wed, 25 Mar 2020 17:33:01 GMT Content-Type: text/html; charset=utf-8 W0325 11:33:01.932674 16036 main.go:64] W0325 17:33:01.930970 reparent.go:185] master-elect tablet zone1-0000000100 is not the shard master, proceeding anyway as -force was used W0325 11:33:01.933188 16036 main.go:64] W0325 17:33:01.931580 reparent.go:191] master-elect tablet zone1-0000000100 is not a master in the shard, proceeding anyway as -force was used ..
You can also verify that the processes have started with
~/my-vitess-example> pgrep -fl vtdataroot 14119 etcd 14176 vtctld 14251 mysqld_safe 14720 mysqld 14787 vttablet 14885 mysqld_safe 15352 mysqld 15396 vttablet 15492 mysqld_safe 15959 mysqld 16006 vttablet 16112 vtgate
The exact list of processes will vary. For example, you may not see
If you encounter any errors, such as ports already in use, you can kill the processes and start over:
pkill -9 -e -f '(vtdataroot|VTDATAROOT)' # kill Vitess processes rm -rf vtdataroot
For ease-of-use, Vitess provides aliases for
Setting up aliases changes
mysql to always connect to Vitess for your current session. To revert this, type
unalias mysql && unalias vtctlclient or close your session.
Connect to your cluster
You should now be able to connect to the VTGate server that was started in
~/my-vitess-example> mysql Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 2 Server version: 5.7.9-Vitess (Ubuntu) Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. mysql> show tables; +-----------------------+ | Tables_in_vt_commerce | +-----------------------+ | corder | | customer | | product | +-----------------------+ 3 rows in set (0.00 sec)
You can also browse to the vtctld console using the following URL:
In this example, we deployed a single unsharded keyspace named
commerce. Unsharded keyspaces have a single shard named
0. The following schema reflects a common ecommerce scenario that was created by the script:
create table product ( sku varbinary(128), description varbinary(128), price bigint, primary key(sku) ); create table customer ( customer_id bigint not null auto_increment, email varbinary(128), primary key(customer_id) ); create table corder ( order_id bigint not null auto_increment, customer_id bigint, sku varbinary(128), price bigint, primary key(order_id) );
The schema has been simplified to include only those fields that are significant to the example:
producttable contains the product information for all of the products.
customertable has a
customer_idthat has an
auto_increment. A typical customer table would have a lot more columns, and sometimes additional detail tables.
cordertable (named so because
orderis an SQL reserved word) has an
order_idauto-increment column. It also has foreign keys into
You can now proceed with MoveTables.
Or alternatively, if you would like to teardown your example:
./401_teardown.sh rm -rf vtdataroot