Outdated Version

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

Deploy SingleStore DB


The user that deploys MemSQL via SingleStore DB Toolbox must be able to SSH to each host in the cluster. When memsql-server is installed via an RPM or Debian package when deploying MemSQL, a memsql user and group are also created on each host in the cluster.

This memsql user does not have a shell, and attempting to log in or SSH as this user will fail. The user that deploys MemSQL is added to the memsql group. This group allows most Toolbox commands to run without sudo privileges, and members of this group can perform many Toolbox operations without the need to escalate to sudo. Users who desire to run SingleStore DB Toolbox commands must be added to the memsql group on each host in the cluster. They must also be able to SSH to each host.

Manually creating a memsql user and group is only recommended in a sudo-less environment when performing a tarball-baed deployment of MemSQL. In order to run SingleStore DB Toolbox commands against a cluster, this manually-created memsql user must be configured so that it can SSH to each host in the cluster.

Now that the SingleStore DB Tools are installed, you can deploy MemSQL onto each host from the main deployment host and create the MemSQL nodes for your cluster.

  1. When deploying a cluster through the manual steps in this guide, you must register all hosts used in cluster deployment. Start by logging into the main deployment host over SSH.

  2. Once connected, register the host. Host names must be unique across the cluster, so the IP address of the host will be used in this tutorial.

    sdb-toolbox-config register-host --localhost --host <IP_address>

    Note: 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.

  3. Repeat this step for the other hosts in the cluster.

    sdb-toolbox-config register-host --identity-file </ssh_key_file/including/path> --host <IP_address>
  4. Verify all hosts have been added.

    sdb-toolbox-config list-hosts
  5. Install MemSQL on all of your hosts. If you are deploying in an environment with no Internet access, specify the absolute path to the memsql-server RPM or Debian package you downloaded previously.

    Note: If your host does not have the which command available, follow the offline installation method using a downloaded memsql-server RPM or Debian package.

    Online access to APT or YUM repositories

    sdb-deploy install --all --version 7.0

    Offline deployment or no which command available

    sdb-deploy install --file-path /tmp/<memsql-server-package> --all

    MemSQL will be copied onto each host. 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>
  7. From the output of the 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 [YOUR LICENSE KEY]

    Note: If your license key is not shown in the code block above, you can retrieve it from the MemSQL Customer Portal.


    After the master aggregator node is deployed, it must be bootstrapped by adding this license for the cluster. This step must be completed before deploying additional nodes.

    If you skip this step and attempt to deploy additional nodes, an error will occur and the deployment will fail.

  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.

    sdb-admin create-node --host <IP_address> --password <secure_password>
  10. As you did in Step 7, copy the MemSQL ID of your recently-created node from the output of the 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 MemSQL nodes. Change <IP_address> to match the values for the last two hosts and set the secure password for the root database user.

    Note: If the hosts for your leaf nodes are NUMA capable, follow the steps here to setup the hosts 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 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

If you encounter errors running any of these commands, verify that your deployment environment satisfies the following conditions:

  • You can SSH to every host in the cluster using the IPs specified above.

  • Your deployment user has root or sudo privileges in order to install packages on all hosts:

    sudo apt-get install ...
  • MemSQL ports on all hosts are open to all other hosts in the cluster.

Congratulations! Your MemSQL cluster is now setup and ready to use.

You can connect to your cluster using the singlestore client application by simply typing singlestore in a terminal window on the main deployment host.

In addition, you can use SingleStore DB Studio to easily monitor, debug, and interact with all of your MemSQL clusters. See the next step for how to connect and use Studio.