Oracle® NoSQL Database

Quick Start to KVLite

Release 12.2.4.5

E87605-02

February 2018

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Introduction

The Oracle NoSQL Database is a scalable, distributed NoSQL database, designed to provide highly reliable, flexible and available data management across a configurable set of storage nodes. It consists of two parts - a NoSQL DB Driver and a collection of storage nodes called the KVStore. The NoSQL DB Driver is an intelligent driver that transparently handles all the core operations of Oracle NoSQL Database, and the KVStore consists of storage nodes.

KVLite is a simplified version of the Oracle NoSQL Database. It provides a single storage node, single shard store, that is not replicated. It runs in a single process without requiring any administrative interface. You configure, start, and stop KVLite using a command line interface.

Architecture of KVLite

Note: KVLite is intended for use by application developers who need to develop and unit test their Oracle NoSQL Database applications. It can be used as a development platform for developers to get familiar with Oracle NoSQL APIs, and test different ways of interacting with these APIs. KVLite runs on a single machine. It is not intended for production deployment, or for performance measurements.

Also, KVLite is secure by default. If you are performing an unsecured installation, for example, if you are installing KVLite on a Windows platform, refrain from setting the security parameters when executing the commands.

This Quick Start Guide demonstrates how to perform the following tasks:

  1. Install KVLite
  2. Start KVLite
  3. Verify your Installation
  4. Stop and Restart KVLite

Install KVLite

KVLite is bundled with the Oracle NoSQL Database software. To install KVLite, follow the steps below:

  1. Download the tar.gz or .zip file from Oracle Technology Network.
  2. Gunzip and untar the .tar.gz package (or unzip if you downloaded the .zip package). Oracle NoSQL Database version 4.4.6 Enterprise 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), Enterprise Edition (EE), or Basic Edition (BE).

    Be aware that the examples used in this document are part of a separate download and must be unpacked separately.

    Also, make sure you meet the following requirements to run KVLite:

    • Install Java version 8 in your machine.

    • Maintain a minimum disk space of 5GB if you are working with Oracle NoSQL Database release 4.5 or later.

    The examples download package (kv-examples-4.4.6.tar.gz in this tutorial) can be obtained from the same location as you obtained your server download package. 

    $ gunzip kv-ce-4.4.6.tar.gz
$ tar xvf kv-ce-4.4.6.tar  

// To extract the examples package: 
$ gunzip kv-examples-4.4.6.tar.gz
$ tar xvf kv-examples-4.4.6.tar
In this case, the contents of kv-ce-4.4.6.tar.gz is unpacked to a directory called kv-4.4.6 and the contents of kv-examples-4.4.6.tar.gz is unpacked to a directory called kv-4.4.6/examples.

Start KVLite

Perform the following steps to start a KVLite instance:

  1. Open a terminal and cd into the kv-4.4.6 directory to start the NoSQL Database server.
    $ cd kv-4.4.6
$ java -jar lib/kvstore.jar kvlite

    Expected output:

    Generated password for user admin: password
User login file: ./kvroot/security/user.security
Created new kvlite store with args:
-root ./kvroot -store kvstore -host localhost -port 5000 -secure-config enable

    Where kvstore is the name of the store, localhost is the name of the local host, and kvroot is the directory where Oracle NoSQL Database data is placed. It takes about 10 - 60 seconds before this message is issued, depending on the speed of your machine.

    Note that you will not get the command line prompt back until you stop the KVLite.

  2. In a second shell, cd into the kv-4.4.6 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-4.4.6
$ java -jar lib/kvstore.jar ping -host localhost -port 5000 -security kvroot/security/user.security

    Expected output:

    Pinging components of store kvstore based upon topology sequence #14
10 partitions and 1 storage nodes
Time: 2017-05-02 09:34:43 UTC   Version: 12.2.4.4.6
Shard Status: healthy:1 writable-degraded:0 read-only:0 offline:0
Admin Status: healthy
Zone [name=KVLite id=zn1 type=PRIMARY allowArbiters=false]   RN Status: online:1 offline:0
Storage Node [sn1] on localhost:5000    Zone: [name=KVLite id=zn1 type=PRIMARY allowArbiters=false]    
	Status: RUNNING   Ver: 12cR2.4.4.6 2017-04-13 06:54:25 UTC  Build id: d6a9b947763f
	Admin [admin1]		Status: RUNNING,MASTER
	Rep Node [rg1-rn1]	Status: RUNNING,MASTER sequenceNumber:204 haPort:5006
    If you have started KVLite in an unsecured mode, disable the security and ping your KVLite instance:
    $ cd kv-4.4.6
$ java -jar lib/kvstore.jar ping -host localhost -port 5000 -enable-secure disable
The status indicates that the KVLite is up and running.

Verify your Installation

There are several ways to verify your installation and ensure that KVLite is running. Perform one of these steps to verify your installation:

  • Start a new shell and run the following command:
    $ jps -m

    You should see a similar output showing KVLite (and possibly other things as well) running in your machine:

    2674 kvstore.jar kvlite
3118 Jps -m
  • Or, cd into the kv-4.4.6 directory and ping your KVLite instance. The details of the output will vary but you should see a running store.
    $ cd kv-4.4.6
$ java -jar lib/kvstore.jar ping -host localhost -port 5000 -security kvroot/security/user.security

    Expected output:

    Pinging components of store kvstore based upon topology sequence #14
10 partitions and 1 storage nodes
Time: 2017-05-02 09:34:43 UTC   Version: 12.2.4.4.6
Shard Status: healthy:1 writable-degraded:0 read-only:0 offline:0
Admin Status: healthy
Zone [name=KVLite id=zn1 type=PRIMARY allowArbiters=false]   RN Status: online:1 offline:0
Storage Node [sn1] on localhost:5000    Zone: [name=KVLite id=zn1 type=PRIMARY allowArbiters=false]    
	Status: RUNNING   Ver: 12cR2.4.4.6 2017-04-13 06:54:25 UTC  Build id: d6a9b947763f
	Admin [admin1]		Status: RUNNING,MASTER
	Rep Node [rg1-rn1]	Status: RUNNING,MASTER sequenceNumber:204 haPort:5006
    If you have started KVLite in an unsecured mode, disable the security and ping the KVLite instance:
    $ cd kv-4.4.6
$ java -jar lib/kvstore.jar ping -host localhost -port 5000 -enable-secure disable
  • Or, run the kvclient test application using the following commands:
    $ cd kv-4.4.6
$ java -Xmx256m -Xms256m -jar lib/kvclient.jar

    This should write a similar release output to stdout:

    12cR2.4.4.6 2017-04-13 06:54:25 UTC  Build id: d6a9b947763f
  • Or, if you have not already, download the examples package and unpack it so that the examples directory is in KVHOME. In this tutorial, we have already downloaded and extracted the examples package.
    1. Compile the Hello example program:
      $ export KVHOME=<the directory where you have unzipped the CE package> 
$ javac -cp lib/kvclient.jar:examples examples/hello/HelloBigDataWorld.java
    2. Run the example using all default parameters:
      $ cd $KVHOME
$ java -Xmx256m -Xms256m -Doracle.kv.security=./kvroot/security/user.security \
	-cp lib/kvclient.jar:examples hello.HelloBigDataWorld \
	-port 5000 -store kvstore -host localhost

      • Note: In case of an unsecured installation, do not specify the security parameter and run the example: 

        $ java -Xmx256m -Xms256m -cp lib/kvclient.jar:examples hello.HelloBigDataWorld \
	-port 5000 -store kvstore -host localhost

      Or, run it using non-default parameters, if you started KVLite using non-default values:

      $ java -Xmx256m -Xms256m -cp lib/kvclient.jar:examples hello.HelloBigDataWorld \
	-port <hostport> -store <kvstore name> -host <hostname>

      Expected output:

      Hello Big Data World!

Stop and Restart KVLite

To stop and restart KVLite, perform the following steps:

To stop KVLite, use Ctrl C (^C) from within the shell where KVLite is running.

To restart the process, simply run the KVLite utility without any command line options. Do this even if you provided non-standard options when you first started KVLite. This is because KVLite remembers information such as the port value and the store name in between run times. You cannot change these values by using the command line options.

$ java -jar KVHOME/lib/kvstore.jar kvlite

If you want to start over with different options than you initially specified, delete the KVROOT directory (./kvroot, by default), and then re-run the kvlite utility with whatever options you desire. Refer to Start KVLite.

Alternatively, specify the -root command line option, making sure to specify a location other than your original KVROOT directory, as well as any other command line options that you want to change.

Note: If you choose to start over, all your previous data will be lost.

Oracle NoSQL Database Quick Start to KVLite, Release 12.2.4.5

E87605-02

Copyright © 2017, 2018, Oracle and/or its affiliates. All rights reserved.

Primary Author: Supriya Ananth

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.