Local Install via Homebrew

Instructions for using Vitess on your macOS machine for testing purposes

This guide covers installing Vitess locally to macOS 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 Homebrew package manager is also available, which requires no dependencies on your local host.

  1. /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

In this guide, v9.0.0 is used in most outputs. You can replace it by the version of Vitess you are using.

Install Vitess with Homebrew

Vitess supports the databases listed here. 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.

Install Node 18.16.0+ (required to run VTAdmin)

  1. brew install nvm
  2. nvm install --lts 18.16.0
  3. nvm use 18.16.0

See the vtadmin README for more details.

Start a Single Keyspace Cluster

For testing purposes initiate following example;

  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. Created cell: zone1
  7. etcd start done...
  8. Starting vtctld...
  9. vtctld is running!
  10. Successfully created keyspace commerce. Result:
  11. {
  12.   "name": "commerce",
  13.   "keyspace": {
  14.     "served_froms": [],
  15.     "keyspace_type": 0,
  16.     "base_keyspace": "",
  17.     "snapshot_time": null,
  18.     "durability_policy": "semi_sync",
  19.     "throttler_config": null,
  20.     "sidecar_db_name": "_vt"
  21.   }
  22. }
  23. Starting MySQL for tablet zone1-0000000100...
  24. Starting vttablet for zone1-0000000100...
  25. HTTP/1.1 200 OK
  26. Date: Mon, 26 Jun 2023 19:21:51 GMT
  27. Content-Type: text/html; charset=utf-8
  29. Starting MySQL for tablet zone1-0000000101...
  30. Starting vttablet for zone1-0000000101...
  31. HTTP/1.1 200 OK
  32. Date: Mon, 26 Jun 2023 19:21:54 GMT
  33. Content-Type: text/html; charset=utf-8
  35. Starting MySQL for tablet zone1-0000000102...
  36. Starting vttablet for zone1-0000000102...
  37. HTTP/1.1 200 OK
  38. Date: Mon, 26 Jun 2023 19:21:56 GMT
  39. Content-Type: text/html; charset=utf-8
  41. vtorc is running!
  42.   - UI: http://localhost:16000
  43.   - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtorc.out
  44.   - PID: 49556
  47. New VSchema object:
  48. {
  49.   "sharded": false,
  50.   "vindexes": {},
  51.   "tables": {
  52.     "corder": {
  53.       "type": "",
  54.       "column_vindexes": [],
  55.       "auto_increment": null,
  56.       "columns": [],
  57.       "pinned": "",
  58.       "column_list_authoritative": false,
  59.       "source": ""
  60.     },
  61.     "customer": {
  62.       "type": "",
  63.       "column_vindexes": [],
  64.       "auto_increment": null,
  65.       "columns": [],
  66.       "pinned": "",
  67.       "column_list_authoritative": false,
  68.       "source": ""
  69.     },
  70.     "product": {
  71.       "type": "",
  72.       "column_vindexes": [],
  73.       "auto_increment": null,
  74.       "columns": [],
  75.       "pinned": "",
  76.       "column_list_authoritative": false,
  77.       "source": ""
  78.     }
  79.   },
  80.   "require_explicit_routing": false
  81. }
  82. If this is not what you expected, check the input data (as JSON parsing will skip unexpected fields).
  83. Waiting for vtgate to be up...
  84. vtgate is up!
  85. Access vtgate at http://Florents-MacBook-Pro-2.local:15001/debug/status
  86. vtadmin-api is running!
  87.   - API: http://Florents-MacBook-Pro-2.local:14200
  88.   - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtadmin-api.out
  89.   - PID: 49695
  91. vtadmin-web is running!
  92.   - Browser: http://Florents-MacBook-Pro-2.local:14201
  93.   - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtadmin-web.out
  94.   - PID: 49698

Verify your initial cluster:

  1. $ mysql -e "show vitess_tablets"
  2. +-------+----------+-------+------------+---------+------------------+-----------+----------------------+
  3. | Cell  | Keyspace | Shard | TabletType | State   | Alias            | Hostname  | MasterTermStartTime  |
  4. +-------+----------+-------+------------+---------+------------------+-----------+----------------------+
  5. | zone1 | commerce | 0     | PRIMARY    | SERVING | zone1-0000000100 | localhost | 2021-02-17T13:10:13Z |
  6. | zone1 | commerce | 0     | REPLICA    | SERVING | zone1-0000000101 | localhost |                      |
  7. | zone1 | commerce | 0     | RDONLY     | SERVING | zone1-0000000102 | localhost |                      |
  8. +-------+----------+-------+------------+---------+------------------+-----------+----------------------+

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

  1. $ pgrep -fl vitess | awk '{print $2,$3}'
  2. etcd --enable-v2=true
  3. vtctld -topo_implementation
  4. /bin/sh /usr/local/opt/mysql@5.7/bin/mysqld_safe
  5. /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
  6. vttablet -topo_implementation
  7. /bin/sh /usr/local/opt/mysql@5.7/bin/mysqld_safe
  8. /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
  9. vttablet -topo_implementation
  10. /bin/sh /usr/local/opt/mysql@5.7/bin/mysqld_safe
  11. /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
  12. vttablet -topo_implementation
  13. vtgate -topo_implementation
  14. vtorc --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|vitess|vtadmin)' # kill Vitess processes
  2. rm -rf /usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot

Setup Aliases

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

  1. source ../common/env.sh

Setting up aliases changes mysql to always connect to Vitess for your current session. To revert this, type unalias mysql && 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. /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 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. pkill -9 -f '(vtdataroot|VTDATAROOT)' # kill Vitess processes
  2. rm -rf /usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot