### 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 3.0.5 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-3.0.5.tar.gz
      $ tar xvf kv-ce-3.0.5.tar
      kv-3.0.5/
      ...
      kv-3.0.5/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 APIs.

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

      $ cd kv-3.0.5
      $ 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-3.0.5 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-3.0.5
      $ java -jar lib/kvstore.jar ping -host myhost -port 5000
      Pinging components of store kvstore based upon topology sequence #14
      Time: ...
      kvstore comprises 10 partitions and 1 Storage Nodes
      Storage Node [sn1] on myhost:5000    Zone: [name=KVLite id=zn1 type=PRIMARY]    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 APIs. If you would like to learn about using the Tables API, or using schemas and Avro, look at the examples in the examples/table or examples/avro directories. The Getting Started guides and Javadoc have additional information about Tables and Avro.

#### Learn more about Oracle NoSQL Database

Open the doc landing page (either locally in `kv-3.0.5/doc/index.html` or on OTN). From there, the Getting Started with the Key/Value API guide (HTML | PDF) or the Getting Started with the Tables API guide (HTML | PDF) and Javadoc will introduce you to the NoSQL Database APIs. 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 APIs. 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-zone -name MyZone -rf 3 -wait
      kv-> plan deploy-sn -znname MyZone -host host01 -port 5000 -wait
      kv-> plan deploy-admin -sn sn1 -port 5001 -wait
      kv-> pool create -name MyPool
      kv-> pool join -name MyPool -sn sn1
      kv-> plan deploy-sn -znname MyZone -host host02 -port 5000 -wait
      kv-> pool join -name MyPool -sn sn2
      kv-> plan deploy-sn -znname MyZone -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. In addition to administrative commands, the CLI also lets you add, delete, and modify data in your store from the command line. This tool is intended as an aid for developing store applications, but it can also be helpful in evaluating the store.

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 Initial Capacity Planning for an explanation on sizing your store. In particular, Memory and Network Configuration in that chapter describes how to size the memory available to a Storage Node.

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