Local Install

Instructions for using Vitess on your machine for testing purposes

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 the databases listed here. We recommend MySQL 8.0 if your installation method provides that option:

  1. # Ubuntu based
  2. sudo apt install -y mysql-server etcd curl
  4. # Debian
  5. sudo apt install -y default-mysql-server default-mysql-client etcd curl
  7. # Yum based
  8. sudo yum -y localinstall https://dev.mysql.com/get/mysql80-community-release-el8-3.noarch.rpm
  9. sudo yum -y install mysql-community-server etcd curl

On apt-based distributions the services mysqld and 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 mysqld:

  1. # Debian and Ubuntu
  2. sudo service mysql stop
  3. sudo service etcd stop
  4. sudo systemctl disable mysql
  5. 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:

AppArmor:

  1. # Debian and Ubuntu
  2. sudo ln -s /etc/apparmor.d/usr.sbin.mysqld /etc/apparmor.d/disable/
  3. sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.mysqld
  5. # The following command should return an empty result:
  6. sudo aa-status | grep mysqld

SELinux:

  1. # CentOS
  2. sudo setenforce 0

Install Vitess

Download the latest binary release for Vitess on Linux. For example with Vitess 17:

Notes:

  1. version=17.0.0
  2. file=vitess-${version}-70a9466.tar.gz
  3. wget https://github.com/vitessio/vitess/releases/download/v${version}/${file}
  4. tar -xzf ${file}
  5. cd ${file/.tar.gz/}
  6. sudo mkdir -p /usr/local/vitess
  7. sudo cp -r * /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 $HOME/.bashrc file:

  1. export PATH=/usr/local/vitess/bin:${PATH}

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 1 phase 01. Lets execute it now:

  1. mkdir -p ~/my-vitess-example/examples
  2. cp -r <vitess source path>/examples ~/my-vitess-example/examples
  3. cp -r <vitess source path>/web ~/my-vitess-example
  4. cd ~/my-vitess-example/examples/local
  5. ./101_initial_cluster.sh

You should see an output similar to the following:

  1. ~/my-vitess-example> ./101_initial_cluster.sh
  2. $ ./101_initial_cluster.sh 
  3. add /vitess/global
  4. add /vitess/zone1
  5. add zone1 CellInfo
  6. Created cell: zone1
  7. etcd start done...
  8. Starting vtctld...
  9. vtctld is running!
  10. Starting MySQL for tablet zone1-0000000100...
  11. Starting vttablet for zone1-0000000100...
  12. HTTP/1.1 200 OK
  13. Date: Thu, 01 Sep 2022 12:49:50 GMT
  14. Content-Type: text/html; charset=utf-8
  16. Starting MySQL for tablet zone1-0000000101...
  17. Starting vttablet for zone1-0000000101...
  18. HTTP/1.1 200 OK
  19. Date: Thu, 01 Sep 2022 12:49:55 GMT
  20. Content-Type: text/html; charset=utf-8
  22. Starting MySQL for tablet zone1-0000000102...
  23. Starting vttablet for zone1-0000000102...
  24. HTTP/1.1 200 OK
  25. Date: Thu, 01 Sep 2022 12:50:00 GMT
  26. Content-Type: text/html; charset=utf-8
  28. {
  29.   "keyspace": {
  30.     "served_froms": [],
  31.     "keyspace_type": 0,
  32.     "base_keyspace": "",
  33.     "snapshot_time": null,
  34.     "durability_policy": "semi_sync",
  35.     "throttler_config": null,
  36.     "sidecar_db_name": "_vt"
  37.   }
  38. }
  39. vtorc is running!
  40.   - UI: http://localhost:16000
  41.   - Logs: /Users/manangupta/vitess/vtdataroot/tmp/vtorc.out
  42.   - PID: 74088
  44. zone1-0000000100 commerce 0 primary localhost:15100 localhost:17100 [] 2022-09-23T05:48:52Z
  46. New VSchema object:
  47. {
  48.   "sharded": false,
  49.   "vindexes": {},
  50.   "tables": {
  51.     "corder": {
  52.       "type": "",
  53.       "column_vindexes": [],
  54.       "auto_increment": null,
  55.       "columns": [],
  56.       "pinned": "",
  57.       "column_list_authoritative": false
  58.     },
  59.     "customer": {
  60.       "type": "",
  61.       "column_vindexes": [],
  62.       "auto_increment": null,
  63.       "columns": [],
  64.       "pinned": "",
  65.       "column_list_authoritative": false
  66.     },
  67.     "product": {
  68.       "type": "",
  69.       "column_vindexes": [],
  70.       "auto_increment": null,
  71.       "columns": [],
  72.       "pinned": "",
  73.       "column_list_authoritative": false
  74.     }
  75.   },
  76.   "require_explicit_routing": false
  77. }
  78. If this is not what you expected, check the input data (as JSON parsing will skip unexpected fields).
  79. Waiting for vtgate to be up...
  80. vtgate is up!
  81. Access vtgate at http://Manans-MacBook-Pro.local:15001/debug/status
  82. vtadmin-api is running!
  83.   - API: http://localhost:14200
  84.   - Logs: /Users/manangupta/vitess/vtdataroot/tmp/vtadmin-api.out
  85.   - PID: 74039
  87. Installing nvm...
  89. nvm is installed!
  91. Configuring Node.js 16
  93. Downloading and installing node v16.19.1...
  94. Local cache found: ${NVM_DIR}/.cache/bin/node-v16.19.1-darwin-x64/node-v16.19.1-darwin-x64.tar.xz
  95. Checksums match! Using existing downloaded archive ${NVM_DIR}/.cache/bin/node-v16.19.1-darwin-x64/node-v16.19.1-darwin-x64.tar.xz
  96. Now using node v16.19.1 (npm v8.19.3)
  98. > vtadmin@0.1.0 build
  99. > vite build
  101. vite v4.2.1 building for production...
  102. transforming (1218) src/icons/alertFail.svgUse of eval in "node_modules/@protobufjs/inquire/index.js" is strongly discouraged as it poses security risks and may cause issues with minification.
  103. ✓ 1231 modules transformed.
  104. build/assets/chevronUp-3d6782a5.svg              0.18 kB
  105. build/assets/chevronDown-02f94e73.svg            0.19 kB
  106. build/assets/download-8ef290b4.svg               0.21 kB
  107. build/assets/delete-a9184ef9.svg                 0.23 kB
  108. build/assets/info-2617ee9d.svg                   0.34 kB
  109. build/assets/circleAdd-cfd7e5db.svg              0.35 kB
  110. build/assets/alertFail-8056b6e4.svg              0.35 kB
  111. build/assets/checkSuccess-f8fd1dbb.svg           0.36 kB
  112. build/assets/search-3261bac7.svg                 0.41 kB
  113. build/assets/question-a67b2492.svg               0.46 kB
  114. build/assets/runQuery-edfab4ed.svg               0.49 kB
  115. build/assets/open-405dd348.svg                   0.49 kB
  116. build/index.html                                 0.90 kB
  117. build/assets/bug-5b6edb54.svg                    0.99 kB
  118. build/assets/topology-0032b65e.svg               1.62 kB
  119. build/assets/NotoMono-Regular-41fd7ccc.ttf     107.85 kB
  120. build/assets/NotoSans-Regular-c8cff31f.ttf     313.14 kB
  121. build/assets/NotoSans-SemiBold-43207822.ttf    313.72 kB
  122. build/assets/NotoSans-Bold-c6a598dd.ttf        313.79 kB
  123. build/assets/index-ef40fbc9.css                 87.78 kB │ gzip:  15.02 kB
  124. build/assets/index-4ddb52ed.js               2,811.88 kB │ gzip: 492.59 kB
  126. (!) Some chunks are larger than 500 kBs after minification. Consider:
  127. - Using dynamic import() to code-split the application
  128. - Use build.rollupOptions.output.manualChunks to improve chunking: https://rollupjs.org/configuration-options/#output-manualchunks
  129. - Adjust chunk size limit for this warning via build.chunkSizeWarningLimit.
  130. ✓ built in 10.85s
  132. vtadmin-web is running!
  133.   - Browser: http://localhost:14201
  134.   - Logs: /Users/manangupta/vitess/vtdataroot/tmp/vtadmin-web.out
  135.   - PID: 74070

You can also verify that the processes have started with pgrep:

  1. ~/my-vitess-example> pgrep -fl vitess
  2. 14119 etcd
  3. 14176 vtctld
  4. 14251 mysqld_safe
  5. 14720 mysqld
  6. 14787 vttablet
  7. 14885 mysqld_safe
  8. 15352 mysqld
  9. 15396 vttablet
  10. 15492 mysqld_safe
  11. 15959 mysqld
  12. 16006 vttablet
  13. 16112 vtgate
  14. 16788 vtorc

The exact list of processes will vary. For example, you may not see mysqld_safe listed.

If you encounter any errors, such as ports already in use, you can kill the processes and start over:

  1. pkill -9 -f '(vtdataroot|VTDATAROOT|vitess|vtadmin)' # kill Vitess processes
  2. rm -rf vtdataroot

Setup Aliases

For ease-of-use, Vitess provides aliases for mysql, vtctlclient and vtcltdclient:

  1. source ./env.sh

Setting up aliases changes mysql to always connect to Vitess for your current session. To revert this, type unalias mysql && unalias vtctlclient && unalias vtctldclient or close your session.

Connect to your cluster

You should now be able to connect to the VTGate server that was started in 101_initial_cluster.sh:

  1. ~/my-vitess-example> mysql
  2. Welcome to the MySQL monitor.  Commands end with ; or \g.
  3. Your MySQL connection id is 2
  4. Server version: 8.0.31-Vitess (Ubuntu)
  6. Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
  8. Oracle is a registered trademark of Oracle Corporation and/or its
  9. affiliates. Other names may be trademarks of their respective
  10. owners.
  12. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
  14. mysql> show tables;
  15. +-----------------------+
  16. | Tables_in_vt_commerce |
  17. +-----------------------+
  18. | corder                |
  19. | customer              |
  20. | product               |
  21. +-----------------------+
  22. 3 rows in set (0.00 sec)

You can also now browse and administer your new Vitess cluster using the VTAdmin UI at the following URL:

  1. http://localhost:14201

VTOrc is also setup as part of the initialization. You can look at its user-interface at:

  1. http://localhost:16000

Summary

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:

  1. create table product (
  2.   sku varbinary(128),
  3.   description varbinary(128),
  4.   price bigint,
  5.   primary key(sku)
  6. );
  7. create table customer (
  8.   customer_id bigint not null auto_increment,
  9.   email varbinary(128),
  10.   primary key(customer_id)
  11. );
  12. create table corder (
  13.   order_id bigint not null auto_increment,
  14.   customer_id bigint,
  15.   sku varbinary(128),
  16.   price bigint,
  17.   primary key(order_id)
  18. );

The schema has been simplified to include only those fields that are significant to the example:

  • The product table contains the product information for all of the products.
  • The customer table has a customer_id that has an auto_increment. A typical customer table would have a lot more columns, and sometimes additional detail tables.
  • The corder table (named so because order is an SQL reserved word) has an order_id auto-increment column. It also has foreign keys into customer(customer_id) and product(sku).

Next Steps

You can now proceed with MoveTables.

Or alternatively, if you would like to teardown your example:

  1. ./401_teardown.sh
  2. rm -rf vtdataroot