The Oracle NoSQL Database Blog covers all things Oracle NoSQL Database. On-Prem, Cloud and more.

  • August 24, 2015

Setting up a single node Oracle NoSQL

A Chandak
Product Manager

This blog describes process to setup a single node Oracle NoSQL Database. If you are planning a large system for production use, please read Initial Capacity Planning to estimate the number of storage nodes on which you will need to install the software.  


Follow the steps listed in the product documentation page to install Oracle No SQL Database. It is important that you follow the installation prerequisites


 At high level configuring your store requires following steps :  

  1. Bootstrap Storage Node (SN) : The physical machine or the storage node that we are going to use need to be bootstrapped first, in the bootstrap process we create config file in the KVRoot Dir that holds the cluster deployment info.
  2. Start Storage Node Agent (SNA) :  After bootstrapping, we start the Storage Node Agent or SNA that basically works like a listener that enables communication between the admin node and other replication node (RN) . We run bootstrapping and SNA on all the storage node. 
  3. Run Admin Steps to deploy the cluster 
    1. Create Store
    2. Create Data Center
    3. Assign Storage Nodes (SN) to a DC
    4. Deploy MxN topology

  Before we start   first download the latest binaries, if there are some stale libraries cleanup the environment 

  • Download the kv-ee-<version>.tar.gz software from  OTN site and and unpack it into /home/oracle/nosqldb.
  • Set environment variables, KVHOME points to the directory
    where you unzipped the latest Oracle NoSQL Database binaries, KVROOT where you would like metadata files to be stored and KVDATA to the  storage directories



    mkdir ${KVROOT}

    mkdir ${KVDATA}

  • (Optional) Stop any KVROOT instance if running and remove existing data

    nohup java -jar $KVHOME/lib/kvstore.jar stop -root $KVROOT >stopNoSQL.log 2>&1 &

    // Remove any existing data

     /bin/rm -rf ${KVDATA}/*     
    /bin/rm -rf ${KVROOT}/*

 Lets look into each of above steps.

  • Step 1 - BootStrap Storage Nodes (SN)  
    • Create a configuration file that is use to start a not-yet-deployed Storage Node
      to be used in an instance of Oracle NoSQL Database. Notice that we are defining three different port (-admin, -harangue, -port ) ranges for various
      inter-intra node communication. Number of replication-nodes (RN) this storage node can host is
      defined by the capacity as ‘-capacity’. You can define storage directories where data is going to
      be written using -storagedir argument.
      In our case we defined capacity=1, which means we would like one RN to be hosted on the storage node with RN using its own disk. If there are more RNs then each RN could be potentially made to use their own disk, this is important aspect as
      independent spindles improves performance and the availability of the system. Refer to the guide  to understand the details of each of the above configuration parameters

      mkdir -p $KVROOT

      java -jar $KVHOME/lib/kvstore.jar makebootconfig \

              -root $KVROOT \

               -store-security none \

               -capacity 1 \

               -harange 5010,5030 \

               -admin 5001 \

               -port 5000 \

               -memory_mb 1024 \

               -host `hostname` \

               -storagedir ${KVDATA}

  • Step 2 - Start Storage Node Agent(SNA)
    • Once the Storage Node is bootstrapped we are going to start the Oracle NoSQL Database Storage Agent(SNA). Notice that we are passing KVROOT of the SN to the start command.

      nohup java -Xmx256m -Xms256m -jar $KVHOME/lib/kvstore.jar start -root ${KVROOT} &

  • Step 3 - Deploy the topology
    • Next we deploy the NoSQL DB topology on the storage nodes that we
      just started in previous step. Let's breakdown this steps 
      • First we name the store as ‘mystore’.  Note that the name of your store is essentially used to form a path to records kept in the store. For this reason, you should avoid using characters in the store name that might interfere with its use within a file path. The command line interface does not allow an invalid store name. Valid characters are alphanumeric, '-', '_', and '.'.
      • Create a Data center or zone 'Boston'. When you execute the plan deploy-data-center command, the CLI returns the plan number and whatever additional information it has about plan status
      • Every KVStore has an administration database. You must deploy the Storage Node to which the command line interface is currently connecting to, in this case, "sn1", and then deploy an Administration process on that same node, in order to proceed to configure this database. Use the deploy-sn and deploy-admin commands to complete this step.
      • Once the admin process is created, you must create a Storage node pool, which is used to contain all the SNs in the store. We name this pool as 'BostonPool'
      • Next join the storage node(sn1) to the Storage node pool (BostonPool)
      • The final step in your configuration process is to create Replication Nodes on every node in your store. You do this using the topology create and plan deploy-topology commands in its place.The plan deploy-topology command requires a topology name. We name it 'topo'
      • As a final sanity check, you can confirm that all of the plans succeeded using the show plans command 

        java -Xmx256m -Xms256m -jar ${KVHOME}/lib/kvstore.jar runadmin -port 5000
               -host ${HOSTNAME} << EOF
        configure -name mystore
        plan deploy-zone -name "Boston" -rf 1 -wait
        plan deploy-sn -zn zn1 -host ${HOSTNAME} -port 5000 -wait
        plan deploy-admin -sn sn1 -port 5001 -wait
        pool create -name BostonPool
        show topology
        pool join -name BostonPool -sn sn1
        topology create -name topo -pool BostonPool -partitions 10
        topology preview -name topo
        plan deploy-topology -name topo -wait
        show  plan

Once all the above steps are done, you are set to use the single node Oracle NoSQL - that's how easy it is to setup and deploy a NoSQL Cluster. Depending on interest, I can extend this tutorial to setting up a multi-node cluster of Oracle NoSQL database.

Join the discussion

Comments ( 3 )
  • guest Tuesday, August 25, 2015

    Excellent very helpul

  • guest Tuesday, February 16, 2016

    Please Send me Multinode Configuration Methods

  • Anand Chandak Tuesday, February 16, 2016

    Can you please send me your email address, I'll send you steps to expand the cluster

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.