Oracle NoSQL Database - A Quickstart In 5 Minutes

Install Oracle NoSQL Database

Download the tar.gz file from http://www.oracle.com/technetwork/database/nosqldb/downloads/index.html.

gunzip and untar the .tar.gz package (or unzip if you downloaded the .zip package). Oracle NoSQL Database version 2.0.14 Community Edition is used in this example. The actual package names and directory names will change, depending upon the release version you are using, and whether you are using Community Edition (CE) or Enterprise Edition (EE).
```
$ gunzip kv-ce-2.0.14.tar.gz
$ tar xvf kv-ce-2.0.14.tar
kv-2.0.14/
...
kv-2.0.14/README.txt
$
```

Start up KVLite

KVLite is a single process version of Oracle NoSQL Database. KVLite is not tuned for performance, but does give you easy access to a simple Key/Value store so that you can test the API.

cd into the kv-2.0.14 directory to start the NoSQL Database server.

$ cd kv-2.0.14
$ java -jar lib/kvstore.jar kvlite
Created new kvlite store with args:
-root ./kvroot -store kvstore -host myhost -port 5000 -admin 5001

In a second shell, cd into the kv-2.0.14 directory and ping your KVLite instance to test that it's alive. The details of the output will vary but you should see a running store.

$ cd kv-2.0.14
$ java -jar lib/kvstore.jar ping -host myhost -port 5000
Pinging components of store kvstore based upon topology sequence #14
kvstore comprises 10 partitions and 1 Storage Nodes
Storage Node [sn1] on myhost:5000    Datacenter: KVLite [dc1]  Status: RUNNING  ...
        Rep Node [rg1-rn1]      Status: RUNNING,MASTER at sequence number: 38 haPort: 5011

Compile and run the Hello World example. This opens the Oracle NoSQL Database and writes a single record.

$ javac -cp examples:lib/kvclient.jar examples/hello/HelloBigDataWorld.java
$ java -cp examples:lib/kvclient.jar hello.HelloBigDataWorld
Hello Big Data World!
$

Peruse the Hello World example code and expand it to experiment more with the Oracle NoSQL Database API. If you would like to learn about using schemas and Avro, look at the examples in the examples/avro directory. The Getting Started Guide and Javadoc have additional information about Avro.

Learn more about Oracle NoSQL Database

Open the doc landing page (either locally in kv-2.0.14/doc/index.html or on OTN). From there, the Getting Started Guide (HTML | PDF) and Javadoc will introduce you to the NoSQL Database API. The Oracle NoSQL Database Administrator's Guide (HTML | PDF) will help you understand how to plan and deploy a larger installation.

Remember, KVLite should only be used to become familiar with the NoSQL Database API. Any serious evaluation of the system should be done with a multi-process, multi-node configuration. Here are some basic instructions for installing a simple multi-node system with 1 shard replicated across 3 hosts. The host names and port numbers are for example only. You should substitute appropriate values.

Repeat the instructions above on how to unpack the package on any nodes that do not yet have the software accessible. Then follow a few additional steps, described in the Admin Guide Installation chapter. The next steps assume that Storage Node Agents are running on the 3 nodes used for the example.
Be sure to run ntp on all nodes. Time synchronization problems among nodes will cause unexpected failures.

Use the Command Line Interface (CLI) to configure and deploy the store. In this sample interaction the hosts are named host01, host02, and host03. Host "host01" will be used for the administrative service.

$ java -jar lib/kvstore.jar runadmin -host host01 -port 5000
kv-> configure -name "mystore"
kv-> plan deploy-datacenter -name MyDC -rf 3 -wait
kv-> plan deploy-sn -dcname MyDC -host host01 -port 5000 -wait
kv-> plan deploy-admin -sn sn1 -port 5001
kv-> pool create -name MyPool
kv-> pool join -name MyPool -sn sn1
kv-> plan deploy-sn -dcname MyDC -host host02 -port 5000 -wait
kv-> pool join -name MyPool -sn sn2
kv-> plan deploy-sn -dcname MyDC -host host03 -port 5000 -wait
kv-> pool join -name MyPool -sn sn3
kv-> topology create -name MyStoreLayout -pool MyPool -partitions 100
kv-> topology preview -name MyStoreLayout
kv-> plan deploy-topology -name MyStoreLayout -wait
kv-> show plans
kv-> show topology
kv-> verify
kv-> quit

For more information about the CLI see the NoSQL Database CLI reference.

To evaluate performance, you will want to be sure to configure sufficient memory on the target host machines. This is done by specifying the available memory for each Storage Node, either when initially installing and deploying the Storage Nodes, or by setting the Storage Node configuration parameter after deployment. See Planning Your Installation.

You can ask questions, or make comments on the Oracle NoSQL Database OTN forum.