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 want to run KVLite in unsecure mode, you will have to explicitly provide parameters to disable security while installing KVLite as demonstrated in this guide.

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
  5. About the Oracle NoSQL Database Proxy

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 23.1.21 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).

    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 11 in your machine.

    • Maintain a minimum disk space of 5GB.

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

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

Start KVLite

Perform the following steps to start a KVLite instance:

To start KVLite in secure mode:

  1. Open a terminal and cd into the kv-23.1.21 directory to start the NoSQL Database server.

    $ cd kv-23.1.21
    $ java -Xmx64m -Xms64m -jar lib/kvstore.jar kvlite
                                 [-storagedirsizegb N]

    The storagedirsizegb is an optional parameter. This parameter can be used to control the size of the storage directory for a new instance. The value of N is in GB and must be >= 1. By default the store created has a size of 10GB and this flag must be used to override that. The size cannot be changed once the instance has been created and use of the flag on an existing instance is ignored.

    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 
    -storagedirsizegb 15 -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-23.1.21 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-23.1.21
    $ java -Xmx64m -Xms64m -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: 2023-05-23 06:15:34 UTC   Version: 23.1.21
    Shard Status: healthy: 1 writable-degraded: 0 read-only: 0 offline: 0 total: 1
    Admin Status: healthy
    Zone [name=KVLite id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]   RN Status: online: 1 read-only: 0 offline: 0
    Storage Node [sn1] on phoenix126166: 5000    Zone: [name=KVLite id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 23.1.21 2023-05-19 18:31:46 UTC  Build id: 477e7f102ab4 Edition: Community    isMasterBalanced: true	serviceStartTime: 2023-05-23 06:13:24 UTC
    	Admin [admin1]		Status: RUNNING,MASTER	serviceStartTime: 2023-05-23 06:13:29 UTC	stateChangeTime: 2023-05-23 06:13:29 UTC	availableStorageSize: 2 GB
    	Rep Node [rg1-rn1]	Status: RUNNING,MASTER sequenceNumber: 322 haPort: 5003 availableStorageSize: 9 GB storageType: HD	serviceStartTime: 2023-05-23 06:13:32 UTC	stateChangeTime: 2023-05-23 06:13:32 UTC
    

    The status indicates that the KVLite is up and running.

To start KVLite in unsecure mode:

  1. Open a terminal and cd into the kv-23.1.21 directory.

    $ cd kv-23.1.21
  2. Execute the kvstore.jar file using the -enable-secure disable flag to disable security and start KVLite in unsecure mode.

    $   java -jar lib/kvstore.jar kvlite 
    [-storagedirsizegb N ] -secure-config disable

    The storagedirsizegb is an optional parameter. This parameter can be used to control the size of the storage directory for a new instance. The value of N is in GB and must be >= 1. By default the store created has a size of 10GB and this flag must be used to override that. The size cannot be changed once the instance has been created and use of the flag on an existing instance is ignored.

  3. In a second shell, cd into the kv-23.1.21 directory and ping your KVLite instance to test that it's alive. You should see a running store.

    $ cd kv-23.1.21
    $ java -jar lib/kvstore.jar ping -host localhost -port 5000 

    Expected output:

    Pinging components of store kvstore based upon topology sequence #14
    10 partitions and 1 storage nodes
    Time: 2023-05-23 08:30:00 UTC   Version: 23.1.21
    Shard Status: healthy: 1 writable-degraded: 0 read-only: 0 offline: 0 total: 1
    Admin Status: healthy
    Zone [name=KVLite id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]   RN Status: online: 1 read-only: 0 offline: 0
    Storage Node [sn1] on phoenix126166: 5000    Zone: [name=KVLite id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 23.1.21 2023-05-19 18:31:46 UTC  Build id: 477e7f102ab4 Edition: Community    isMasterBalanced: true	serviceStartTime: 2023-05-23 08:29:14 UTC
    	Admin [admin1]		Status: RUNNING,MASTER	serviceStartTime: 2023-05-23 08:29:17 UTC	stateChangeTime: 2023-05-23 08:29:17 UTC	availableStorageSize: 2 GB
    	Rep Node [rg1-rn1]	Status: RUNNING,MASTER sequenceNumber: 51 haPort: 5003 availableStorageSize: 9 GB storageType: HD	serviceStartTime: 2023-05-23 08:29:19 UTC	stateChangeTime: 2023-05-23 08:29:19 UTC
    

    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-23.1.21 directory and ping your KVLite instance. The details of the output will vary but you should see a running store.
    $ cd kv-23.1.21
    $ java -Xmx64m -Xms64m -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: 2023-05-23 06:15:34 UTC   Version: 23.1.21
    Shard Status: healthy: 1 writable-degraded: 0 read-only: 0 offline: 0 total: 1
    Admin Status: healthy
    Zone [name=KVLite id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]   RN Status: online: 1 read-only: 0 offline: 0
    Storage Node [sn1] on phoenix126166: 5000    Zone: [name=KVLite id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 23.1.21 2023-05-19 18:31:46 UTC  Build id: 477e7f102ab4 Edition: Community    isMasterBalanced: true	serviceStartTime: 2023-05-23 06:13:24 UTC
    	Admin [admin1]		Status: RUNNING,MASTER	serviceStartTime: 2023-05-23 06:13:29 UTC	stateChangeTime: 2023-05-23 06:13:29 UTC	availableStorageSize: 2 GB
    	Rep Node [rg1-rn1]	Status: RUNNING,MASTER sequenceNumber: 322 haPort: 5003 availableStorageSize: 9 GB storageType: HD	serviceStartTime: 2023-05-23 06:13:32 UTC	stateChangeTime: 2023-05-23 06:13:32 UTC
    
    If you have started KVLite in an unsecured mode, ping the KVLite instance without using the -security parameter:
    $ cd kv-23.1.21
    $ java -Xmx64m -Xms64m -jar lib/kvstore.jar ping -host localhost -port 5000
  • Or, run the kvclient test application using the following commands:
    $ cd kv-23.1.21
    $ java -Xmx64m -Xms64m -jar lib/kvclient.jar

    This should write a similar release output to stdout:

    23.1.21 2023-05-19 18:31:46 UTC  Build id: 477e7f102ab4 Edition: Client
  • 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 -Xmx64m -Xms64m -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 -Xmx64m -Xms64m -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 -Xmx64m -Xms64m -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 -Xmx64m -Xms64m -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.

About the Oracle NoSQL Database Proxy

The Oracle NoSQL Database Proxy is a middle-tier component that lets the Oracle NoSQL Database SDK communicate with the Oracle NoSQL Database(kvlite configuration).


The Oracle NoSQL Database drivers are available in various programming languages that are used in the client application. Currently, Java, Python, Go, Node.js and .NET language and Spring Data SDKs are supported. The JAR file for the Oracle NoSQL Database Proxy is included in the Enterprise Edition distribution and the Community Edition distribution of Oracle NoSQL Database that you downloaded. For more information, see Oracle NoSQL Database Proxy and Driver .