Run the Cluster-in-a-Box Container min read


The easiest way to demonstrate how to use MemSQL on any major operating system is through a pre-configured Docker image. The memsql/cluster-in-a-box container is available for free and allows users to easily run a simple single-host MemSQL cluster. It also includes MemSQL Studio, our cluster monitoring and management tool to easily monitor, debug and interact with your MemSQL cluster.

If you are running Windows or macOS, using the memsql/cluster-in-a-box container allows you to easily try out MemSQL on your local machine.

Warning

Running MemSQL in a Docker container as described below is for prototyping and functional testing purposes only! If you wish to test out MemSQL for production deployments, see the multi-host on-premises install guide instead.

By downloading the memsql/cluster-in-a-box image, you agree to the MemSQL terms of service. Users who want to use MemSQL on Docker in production should contact MemSQL Support before proceeding. Get free enterprise support by creating a MemSQL Enterprise trial license key in our Customer Portal and using it with your memsql/cluster-in-a-box container.

Before You Begin

  • For newer macOS and Windows 10 machines, Install Docker Community Edition (CE). For users running older versions of Windows or macOS, install Docker Toolbox instead.

  • Make sure Docker is running. The recommended configuration is at least 4 cores and 4GB of RAM on your host machine. For macOS users, you can enable this in the Advanced tab located under the Preferences menu item. For Windows users, this tab is located under Settings.

  • You must have a License key copied from the MemSQL Customer Portal.

Note For Windows users, the examples in this guide assume you are running them in a PowerShell window.

Run the Container

The MemSQL cluster-in-a-box image contains two nodes: A master aggregator node that runs SQL queries and aggregates the results, and a single leaf node, which is responsible for storing and processing data. These two nodes form the most basic MemSQL cluster.

  1. Export your license key into an environment variable named LICENSE_KEY. If your license key is not shown in the code block below, you can copy it from the MemSQL Customer Portal.

    Linux/macOS

    export LICENSE_KEY=[YOUR LICENSE KEY]
    

    Windows

    $env:LICENSE_KEY = "[YOUR LICENSE KEY]"
    
  2. Initialize the cluster using docker run. If you want to preserve data across an upgrade of the Docker container, put -v memsql-ciab-data:/var/lib/memsql before memsql/cluster-in-a-box in the command below.

    Linux/macOS

    docker run -i --init \
        --name memsql-ciab \
        -e LICENSE_KEY=$LICENSE_KEY \
        -p 3306:3306 -p 8080:8080 \
        memsql/cluster-in-a-box
    

    Windows

    docker run -i --init `
        --name memsql-ciab `
        -e LICENSE_KEY=$env:LICENSE_KEY `
        -p 3306:3306 -p 8080:8080 `
        memsql/cluster-in-a-box
    

    If initialization fails, you will need to remove the container before retrying.

    docker rm memsql-ciab
    
  3. Start the container.

    docker start memsql-ciab
    
  4. Finally, connect to MemSQL Studio at http://localhost:8080. You should see the following:

    image

    The default Username is root and Password should be left blank.

    Info

    MemSQL Studio is only supported on Chrome and Firefox browsers at this time.

Connect to MemSQL and Create a Database

Use the memsql client within the container to perform cluster operations and run SQL queries against a database.

  1. Connect to the container and open the memsql client application.

    docker exec -it memsql-ciab memsql
    
  2. Run the following MemSQL database commands to create a table and seed it with sample data:

    CREATE DATABASE test;
    
    USE test;
    
    CREATE TABLE test_table (id BIGINT PRIMARY KEY AUTO_INCREMENT, c INT);
    
    INSERT INTO test_table (c) VALUES (1);
    
    INSERT INTO test_table (c) SELECT c*2 FROM test_table;
    
    INSERT INTO test_table (c) SELECT c*2 FROM test_table;
    
    INSERT INTO test_table (c) SELECT c*2 FROM test_table;
    
    INSERT INTO test_table (c) SELECT c*2 FROM test_table;
    
    INSERT INTO test_table (c) SELECT c*2 FROM test_table;
    
    SELECT SUM(c) FROM test_table;
    

By exposing port 3306 when starting up the MemSQL container, you can also connect with your favorite tools like Sequel Pro, or use tools such as the MySQL client (if you have it installed) to do local development work.

mysql -h 127.0.0.1 -u root -P 3306 --prompt="memsql> "

Upgrading the MemSQL Docker Image

Warning

If you do not use a volume to persist your data, you will lose any data stored in the MemSQL cluster-in-a-box container during the upgrade process.

  1. To upgrade the memsql/cluster-in-a-box Docker image to the latest version, run docker pull:

    docker pull memsql/cluster-in-a-box
    
  2. Stop and remove the old container. This will delete any data stored in the container.

    docker stop memsql-ciab
    docker rm memsql-ciab
    
  3. If you did not use a volume to preserve data in your container, restart it with the latest image by running steps 2 and 3 from the previous section again.

  4. If you did set up your Docker container with a volume, run the following instead:

    Linux/macOS

    docker run -d --init \
        --name memsql-ciab \
        -v memsql-ciab-data:/var/lib/memsql \
        -p 3306:3306 -p 8080:8080 \
        memsql/cluster-in-a-box
    

    Windows

    docker run -i --init `
        --name memsql-ciab `
        -v memsql-ciab-data:/var/lib/memsql `
        -p 3306:3306 -p 8080:8080 `
        memsql/cluster-in-a-box
    

Stopping, Restarting, and Removing the Image

If you have a running container, you can manage it through the following commands.

Stopping the container (must be running):

docker stop memsql-ciab

Restarting the container (must be running):

docker restart memsql-ciab

Remove the container (all data will be deleted):

docker rm memsql-ciab

Next Steps

See How to Run Queries for an example schema and queries to begin exploring the potential of MemSQL.

Was this article useful?