Tutorial - Cluster Deploy


In this tutorial we will walk you through the process of creating a cluster, deploying to it, starting the cluster and running commands on it.

Download The Software

Unpack Package

  • Linux/Mac: Type "tar -xzf sonicbase-<version>.tgz" in the parent directory where you want the software to go. A directory named "sonicbase" will be created.
  • Windows: Unzip the file sonicbase-<version>.zip in the parent directory where you want the software to go. A directory named "sonicbase" will be created.
  • Create a Config File

    In the sonicbase/config directory is the config file "config-1-local.json". Copy this file to "config-test.json".

    Set Paths In The Config


    Note on Windows you will need to escape the backslashes so the value can be stored in the json file.
    On Windows the directory may look like "c:\\\\db-data". On linux it may look like "/mnt/db-data". On linux and mac you also have the option of prefixing your path with "$HOME" to specify the home directory. This option is not available on Windows. The $WORKING_DIR macro should only be used on a local cluster.

    Configure Servers

    Simple Server Config

    Create a text file listing the address of each server you want in the cluster. Type the following command:
    ./cli --cluster=[cluster name] --command="build config [path to text file]"

    Detailed Server Config

    Example With 2 Shards and 2 Replicas

    
    "shards" :
    [
      {
        "replicas" :
        [
          {
            "publicAddress" : "18.232.5.217",
            "privateAddress" : "10.0.0.205",
            "port" : 9010
          },
          {
            "publicAddress" : "10.0.0.141",
            "privateAddress" : "10.0.0.141",
            "port" : 9010
          }
        ]
      },
      {
        "replicas" :
        [
          {
            "publicAddress" : "10.0.0.42",
            "privateAddress" : "10.0.0.42",
            "port" : 9010
          },
          {
            "publicAddress" : "10.0.0.252",
            "privateAddress" : "10.0.0.252",
            "port" : 9010
          }
        ]
      }
    ]

    Example With 2 Shards, 1 Replica

    
    "shards" :
    [
      {
        "replicas" :
        [
          {
            "publicAddress" : "18.232.5.217",
            "privateAddress" : "10.0.0.205",
            "port" : 9010
          }
        ]
      },
      {
        "replicas" :
        [
          {
            "publicAddress" : "10.0.0.42",
            "privateAddress" : "10.0.0.42",
            "port" : 9010
          }
        ]
      }
    ]
    If you want to deploy from your laptop to the cluster, the first server listed needs a public address that can be accessed from you laptop.

    Start Admin Client

    Change to the sonicbase/bin directory and type "./cli" for MacOS and Linux and "./cli.bat" for cygwin and "cli.bat" for Windows. This will start the SonicBase admin client.

    Use Cluster

    In the client, type:
      use cluster test

    Passwordless SSH

    If your servers aren't local, for Linux and Mac you need to setup passwordless ssh between all your servers before taking the next steps. You also need passwordless ssh between your laptop and the first server configured in your cluster.

    PowerShell for Windows

    Deploy Cluster

    In the client, type:
      deploy cluster

    If all your servers are local, you do not need to deploy the cluster. Note that this command is not available in Windows. In Windows you need to manually copy the local install directory to each server in the location specified by "installDirectory" in the config file.

    Switch to Server for Administration

    If any of your servers are configured with a private address(no accessible via you laptop) you will need to administer your cluster from a server located in your private network. To do this, ssh to your server of choice and start the admin client. The following commands are run from the admin client on this server.

    Start Cluster

    In the client, type:
      start cluster

    This will start the cluster on the servers specified in the config file.

    Create Database

    In the client, type:
      create database db

    This will create the database named "db".

    Create Table

    In the client, type:
      create table persons (name VARCHAR, age INTEGER, ssn VARCHAR, PRIMARY KEY (ssn))

    Insert Record

    In the client, type:
      insert into persons (name, age, ssn) VALUES ('bob', 22, '555-66-7777')

    Read Record

    In the client, type:
      select * from persons

    You should see the inserted record displayed in the client.

    Access From JDBC Driver


    Create and run the following class:

    
    package foo;
    
    public class Tutorial {
      public static void main(String[] args) throws ClassNotFoundException, SQLException {
        Class.forName("com.sonicbase.jdbcdriver.Driver");
        try (Connection conn = DriverManager.getConnection("jdbc:sonicbase:127.0.0.1:9010/db");
             PreparedStatement stmt = conn.prepareStatement("select * from persons");
             ResultSet rs = stmt.executeQuery()) {
          rs.next();
          System.out.println(rs.getString("name") + " " + rs.getInt("age") + " " + rs.getString("ssn"));
        }
      }
    }

    Stop Cluster

    In the client, type:
      stop cluster