Instructions for using Vitess on your macOS machine for testing purposes

<< Local Install

This guide covers installing Vitess locally to macOS for testing purposes, from pre-compiled binaries. We will launch multiple copies of , so it is recommended to have greater than 4GB RAM, as well as 20GB of available disk space.

A Homebrew package manager is also available, which requires no dependencies on your local host.

Vitess supports MySQL 5.7+ and MariaDB 10.3+. Homebrew will install latest tagged Vitess Release.

  1. $ brew install vitess
  2. Updating Homebrew...
  3. ==> Auto-updated Homebrew!
  4. Updated 2 taps (homebrew/core and homebrew/cask).
  5. ==> Updated Formulae
  6. Updated 19 formulae.
  7. ==> Updated Casks
  8. Updated 1 cask.
  10. ==> Downloading https://homebrew.bintray.com/bottles/vitess-9.0.0.catalina.bottle.tar.gz
  11. Already downloaded: /Users/askdba/Library/Caches/Homebrew/downloads/45991b27589a191910e89a1ce529fcdaa694bb5f36b99f1b20146f8f0fc3ee6d--vitess-9.0.0.catalina.bottle.tar.gz
  12. ==> Pouring vitess-9.0.0.catalina.bottle.tar.gz
  13. 🍺  /usr/local/Cellar/vitess/9.0.0: 268 files, 528.3MB

At this point Vitess binaries installed under default Homebrew install location at /usr/local/share/vitess.

Start a Single Keyspace Cluster 

  1. $ cd /usr/local/share/vitess/examples/local/
  2. $ ./101_initial_cluster.sh
  3. add /vitess/global
  4. add /vitess/zone1
  5. add zone1 CellInfo
  6. etcd start done...
  7. Starting vtctld...
  8. Starting MySQL for tablet zone1-0000000100...
  9. Starting vttablet for zone1-0000000100...
  10. HTTP/1.1 200 OK
  11. Date: Wed, 17 Feb 2021 13:09:54 GMT
  12. Content-Type: text/html; charset=utf-8
  14. Starting MySQL for tablet zone1-0000000101...
  15. Starting vttablet for zone1-0000000101...
  16. HTTP/1.1 200 OK
  17. Date: Wed, 17 Feb 2021 13:10:03 GMT
  18. Content-Type: text/html; charset=utf-8
  20. Starting vttablet for zone1-0000000102...
  21. HTTP/1.1 200 OK
  22. Date: Wed, 17 Feb 2021 13:10:12 GMT
  23. Content-Type: text/html; charset=utf-8
  24. W0217 16:10:13.075530   65562 main.go:67] W0217 13:10:13.074510 reparent.go:188] master-elect tablet zone1-0000000100 is not the shard master, proceeding anyway as -force was used
  25. W0217 16:10:13.076472   65562 main.go:67] W0217 13:10:13.075483 reparent.go:194] master-elect tablet zone1-0000000100 is not a master in the shard, proceeding anyway as -force was used
  26. I0217 16:10:13.076498   65562 main.go:67] I0217 13:10:13.075729 reparent.go:225] resetting replication on tablet zone1-0000000102
  27. I0217 16:10:13.076503   65562 main.go:67] I0217 13:10:13.075730 reparent.go:225] resetting replication on tablet zone1-0000000101
  29. I0217 16:10:13.649509   65562 main.go:67] I0217 13:10:13.649327 reparent.go:244] initializing master on zone1-0000000100
  30. I0217 16:10:13.819282   65562 main.go:67] I0217 13:10:13.818887 reparent.go:277] populating reparent journal on new master zone1-0000000100
  31. I0217 16:10:13.819341   65562 main.go:67] I0217 13:10:13.818928 reparent.go:284] initializing replica zone1-0000000101
  32. I0217 16:10:13.819363   65562 main.go:67] I0217 13:10:13.819005 reparent.go:284] initializing replica zone1-0000000102
  33. I0217 16:10:15.913013   65563 main.go:67] I0217 13:10:15.912595 tablet_executor.go:240] Received DDL request. strategy=direct
  34. I0217 16:10:16.020590   65563 main.go:67] I0217 13:10:16.020461 tablet_executor.go:240] Received DDL request. strategy=direct
  35. I0217 16:10:16.189170   65563 main.go:67] I0217 13:10:16.189044 tablet_executor.go:240] Received DDL request. strategy=direct
  36. New VSchema object:
  37. {
  38.   "tables": {
  39.     "corder": {
  41.     },
  42.     "customer": {
  44.     },
  45.     "product": {
  47.     }
  48.   }
  49. }
  50. If this is not what you expected, check the input data (as JSON parsing will skip unexpected fields).
  51. Waiting for vtgate to be up...
  52. vtgate is up!
  53. Access vtgate at http://askdba:15001/debug/status

Verify your initial cluster:

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

  1. $ pgrep -fl vtdataroot | awk '{print $2,$3}'
  2. etcd --enable-v2=true
  3. vtctld -topo_implementation
  4. /usr/local/opt/mysql@5.7/bin/mysqld --defaults-file=/usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot/vt_0000000100/my.cnf
  5. vttablet -topo_implementation
  6. /bin/sh /usr/local/opt/mysql@5.7/bin/mysqld_safe
  7. /usr/local/opt/mysql@5.7/bin/mysqld --defaults-file=/usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot/vt_0000000101/my.cnf
  8. vttablet -topo_implementation
  9. /bin/sh /usr/local/opt/mysql@5.7/bin/mysqld_safe
  10. /usr/local/opt/mysql@5.7/bin/mysqld --defaults-file=/usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot/vt_0000000102/my.cnf
  11. vttablet -topo_implementation
  12. vtgate -topo_implementation

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)' # kill Vitess processes

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

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 

  1. /usr/local/share/vitess/examples/local> mysql
  2. Welcome to the MySQL monitor.  Commands end with ; or \g.
  3. Your MySQL connection id is 2
  4. Server version: 5.7.9-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 browse to the vtctld console using the following URL:

  1. http://localhost:15000

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:

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 .

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

  1. rm -rf /usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot

<< Local Install