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.

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:
Install KVLite
KVLite is bundled with the Oracle NoSQL Database software. To install KVLite, follow the steps below:
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:
-
Open a terminal and
cd
into thekv-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, andkvroot
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.
-
In a second shell,
cd
into thekv-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:
-
Open a terminal and
cd
into thekv-23.1.21
directory.$ cd kv-23.1.21
-
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. -
In a second shell,
cd
into thekv-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:
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 .
Oracle NoSQL Database Quick Start to KVLite, Release 23.1
E87605-20
May 2023
Copyright © 2011, 2023, Oracle and/or its affiliates.