Outdated Version

You are viewing an older version of this section. View current production version.

Deploy SingleStore DB via Tarball

Download SingleStore DB Files

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

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

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

Replace <singlestore-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/<singlestore-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/<singlestore-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.

singlestoredb-toolbox singlestore-client singlestoredb-studio

Transfer SingleStore DB Files

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

Unpack SingleStore DB Files

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

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

tar xzvf singlestore-client-<version>.tar.gz
tar xzvf singlestoredb-toolbox-<version>.tar.gz
tar xzvf singlestoredb-studio-<version>.tar.gz

Deploy SingleStore DB

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 singlestoredb-toolbox-<version> directory.

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

    ./sdb-deploy setup-cluster -i <id_rsa-file-including-path> \
    --license <memsql-license-from-portal.singlestore.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 sdb-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.

    ./sdb-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 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 singlestoredb-toolbox-<version> directory.

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

    ./sdb-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 sdb-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.

    ./sdb-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.

    ./sdb-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.

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

    ./sdb-toolbox-config list-hosts
    
  5. Install SingleStore DB on all of your hosts.

    ./sdb-deploy install --all
    

    SingleStore DB 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.

    ./sdb-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 sdb-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.

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

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

  9. Create another SingleStore 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.

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

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

    ./sdb-admin add-aggregator \
    --memsql-id <MemSQL-ID> \
    --password <secure-password>
    
  12. Create two more SingleStore 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.

    ./sdb-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.

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

    ./sdb-admin add-leaf \
    --memsql-id <MemSQL-ID> \
    --password <secure-password>
    
  15. Analyze your current cluster configuration using the sdb-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.

    ./sdb-admin optimize
    

End: Option 2

Interact with Your Cluster

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

Change to the singlestoredb-studio- directory.

cd singlestoredb-studio-<version>

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

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