Join the MemSQL Community Today
Get expert advice, develop skills, and connect with others.

Deploy MemSQL via Tarball

Download MemSQL Files

Download the memsql-client, memsql-toolbox, and memsql-studio files onto the main deployment machine. For this guide, this is the same as the designated Master Aggregator of the MemSQL cluster.

To obtain the latest version of each file, use the following:

curl https://release.memsql.com/production/index/<memsql-file>/latest.json

Replace <memsql-file> with memsqlclient, memsqltoolbox, and memsqlstudio to download the list of available file types.

The JSON you receive contains relative file paths in the following format:

"Path": "production/tar/x86_64/<memsql-file>-<version>-<commit-hash>.x86_64.tar.gz"

Use wget to download the file by copying, pasting, and appending the path (minus the quotes) to https://release.memsql.com/. Examples are shown below.

wget https://release.memsql.com/production/tar/x86_64/<memsql-file>-<version>-<commit-hash>.x86_64.tar.gz

Alternatively, click on the desired file type below and click each button to download these files to your computer.

memsql-toolbox memsql-client memsql-studio

Transfer MemSQL Files

Transfer the memsql-client, memsql-toolbox, and memsql-studio files onto the Master Aggregator host to a dedicated memsql directory that non-sudo users (.tar.gz files) can access.

Unpack MemSQL Files

Note: For the remainder of this document, <version>-<commit-hash> will be written simply as <version>.

For .tar.gz files, unpack memsql-client, memsql-toolbox, and memsql-studio into the memsql directory.

tar xzvf memsql-client-<version>.tar.gz
tar xzvf memsql-toolbox-<version>.tar.gz
tar xzvf memsql-studio-<version>.tar.gz

Deploy MemSQL

While the /home/<user>/memsql directory is used through this guide to hold the necessary deployment files and demonstrate the associated deployment commands, this directory can be substituted with any directory that a non-sudo user has access to.

Run the following commands on the Master Aggregator host from the memsql directory.

  1. Change to the memsql-toolbox-<version> directory.

    cd memsql-toolbox-<version>
    
  2. Deploy MemSQL. The following command deploys a 4-node MemSQL cluster with a Master Aggregator node, a Child Aggregator node, and two leaf nodes.

    ./memsql-deploy setup-cluster -i <id_rsa-file-including-path> \
    --license <memsql-license-from-portal.memsql.com> \
    --master-host <master-aggregator-ip-or-hostname> \
    --aggregator-hosts <child-aggregator-ip-or-hostname> \
    --leaf-hosts <leaf-1-ip-or-hostname>,<leaf-2-ip-or-hostname> \
    --password <secure-password> \
    --force-package-format tar
    

    Note the inclusion of the --force-package-format option.

    Note: Creating a node with an empty root password may be convenient for testing purposes. While this is not recommended, you can specify a blank password via: --password "".

  3. Analyze your current cluster configuration using the memsql-admin optimize command.

    This command checks your current cluster configuration against a set of best practices and either makes changes to maximize performance or provides recommendations for you.

    For hosts with NUMA support, this command will bind the leaf nodes to specific NUMA nodes.

    ./memsql-admin optimize
    

End: Option 1

Run the following commands on the Master Aggregator host from the memsql directory.

You must individually register each host when manually deploying a MemSQL cluster. Host names must be unique across the cluster, so the IP address of each host will be used in these examples.

  1. Change to the memsql-toolbox-<version> directory.

    cd memsql-toolbox-<version>
    
  2. Register the Master Aggregator host.

    ./memsql-toolbox-config register-host --localhost \
    --host <ip-address> \
    --tar-install-dir /home/<user>/memsql
    

    If a DNS name or IP address is not provided as a host name, then you must specify the ssh address using the --ssh flag. Also, because this host is local to the memsql-toolbox-config tool, you must use the --localhost flag.

    Note the inclusion of the --tar-install-dir option. If you did not specify the --tar-install-dir option when registering a host, unregister the host using the following command and register the host with the --tar-install-dir option.

    ./memsql-toolbox-config unregister-host --host <ip-address>
    

    Include the --tar-install-state <state-file-name-including-path> option to specify where to write the tarInstallState file on a host, which can be outside of the tarInstallDir.

    By default, this file is named packages.hcl and resides in the tar install directory as specified by --tar-install-dir, which is the recommended configuration.

    This option must be specified with the --tar-install-dir option.

  3. Repeat this step for the other host(s) in the cluster.

    ./memsql-toolbox-config register-host \
    --identity-file /path/to/yourSSHkey \
    --host <ip-address> \
    --tar-install-dir /home/<user>/memsql
    

    Note the inclusion of the --tar-install-dir option. If you did not specify the –tar-install-dir option when registering a host, unregister the host using the following command and register the host with the --tar-install-dir option.

    ./memsql-toolbox-config unregister-host --host <ip-address>
    
  4. Verify all hosts have been added.

    ./memsql-toolbox-config list-hosts
    
  5. Install MemSQL on all of your hosts.

    ./memsql-deploy install --all
    

    MemSQL will be downloaded to the current host and then copied to each host in the cluster to be installed. The time for this process is directly dependent upon the size of your cluster.

  6. Create a new node. This node will be the Master Aggregator for the cluster.

    Change <ip-address> to match IP address of the main deployment host.

    For security purposes, you must set a database password for the root user. This can be passed in as a plaintext string or through the MEMSQL_PASSWORD environment variable.

    ./memsql-admin create-node \
    --host <ip-address> \
    --password <secure-password>
    

    Note: Creating a node with an empty root password may be convenient for testing purposes. While this is not recommended, you can specify a blank password via: --password "".

  7. From the output of the memsql-admin create-node command, copy the MemSQL ID of your recently-created node. You will need this for the next two steps.

  8. Assign the node the role of Master Aggregator and set the cluster license.

    ./memsql-admin bootstrap-aggregator \
    --memsql-id <MemSQL-ID> \
    --license <license>
    

    Note: You can retrieve your license key from the MemSQL Customer Portal.

  9. Create another MemSQL node. Change <ip-address> to match the value specified on one of your remaining hosts and set the secure password for the root database user.

    ./memsql-admin create-node \
    --host <ip-address> \
    --password <secure-password>
    
  10. Copy the MemSQL ID of your recently-created node from the output of the memsql-admin create-node command.

  11. Assign this “unknown” node the role of “aggregator” to designate it as a child aggregator.

    ./memsql-admin add-aggregator \
    --memsql-id <MemSQL-ID> \
    --password <secure-password>
    
  12. Create two more MemSQL nodes. Change <ip-address> to match the values for the last two hosts and set the secure password for the root database user.

    If the hosts for your leaf nodes are NUMA capable, follow the steps here to setup the host correctly and then repeat this node creation step for every NUMA node on those hosts.

    The default port is 3306, so you will have to increment that value for each node you add on the same host as well as expose those ports to the other hosts in the cluster.

    ./memsql-admin create-node \
    --host <ip-address> \
    --password <secure-password>
    
  13. Retrieve the ID values for each of the new nodes. They will be listed as “unknown” in the output.

    ./memsql-admin list-nodes
    
  14. Run the following command on each of the remaining nodes to assign them as leaf nodes.

    ./memsql-admin add-leaf \
    --memsql-id <MemSQL-ID> \
    --password <secure-password>
    
  15. Analyze your current cluster configuration using the memsql-admin optimize command.

    This command checks your current cluster configuration against a set of best practices and either makes changes to maximize performance or provides recommendations for you.

    For hosts with NUMA support, this command will bind the leaf nodes to specific NUMA nodes.

    ./memsql-admin optimize
    

End: Option 2

Interact with Your Cluster

On your main deployment host, run the following command to use MemSQL Studio to monitor and interact with your cluster.

Change to the memsql-studio- directory.

cd memsql-studio-<version>

Start MemSQL Studio from the command line. Use nohup to prevent memsql-studio from terminating when you close your terminal session.

nohup ./memsql-studio > studio.stdout 2> studio.stderr < /dev/null &