Start KVLite

Perform the following steps to start a KVLite instance:

You could start KVLite in secure mode (the default option) or non-secure mode. If you start KVLite in a secure mode and you are using a to access it, configure and start a secure proxy. Similarly, if you start KVLite in non-secure mode, configure and start a non secure proxy.

Start KVLite in secure mode:

You can start KVLite in secure mode using one of the following options:
  • Open a terminal and navigate to $KVHOME, the directory where you have installed Oracle NoSQL Database distribution.
    $ cd $KVHOME$ 
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 store instance. The value of N is in GB and must be >= 1. By default, the created store has a size of 10GB, and this flag can be used to override that. The size cannot be changed after the instance has been created and use of the flag on an existing instance is ignored.
  • To start KVLite using the script:
    1. Download and extract the ZIP file (start_securekvlite.zip) into your $KVHOME directory. The ZIP file contains the script required to start KVLite in secure mode.
    2. The script (start_kvlite.sh) contains the following environment variables with default values to start KVLite. You can run the script as-is or set any of these variables before running it to override the defaults.

      Table - Environment Variables for KVLite

      Name of the variable Optional Description Sample values
      HOSTNAME Yes Identifies a host name associated with the node on which the script to configure kvlite is run. localhost
      KV_PORT Yes The TCP/IP port on which KVLite should be contacted. Sometimes referred to as the registry port. 5000
      KV_ADMIN_WEB_PORT Yes The TCP/IP port on which the admin service should be started. -1
      KV_STORAGESIZE Yes The size of the storage directory in GB. 10
      RESTORE_SNAPSHOT Yes

      The full name of the snapshot of the store you want to restore.

      For example, 
      260311-053335 -mySnapshot
      		 null, there will be no restore

      Note:

      On macOS, the default KV_PORT value (5000), is not available. Set KV_PORT to an unused port before starting KVLite.
    3. Invoke the script (start_kvlite.sh) to start KVLite in secure mode. 
      $/bin/bash start_kvlite.sh
      You get an output as shown below:
      Waiting for kvstore to start...
Waiting for kvstore to start...
Generated password for user admin:*********
User login file: kvroot/security/user.security
Created new kvlite store with args:
-root kvroot -store kvstore -host localhost -port 5000 -admin-web-port -1 -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 system.
  • To ensure KVLite is running, see Verify your Installation.

To start Proxy in secure mode

The proxy is required only for SDK-based clients (such as Java, Python, Node.js, C#, Rust, or Go SDKs). It is not required when using the Java Direct Driver.

You can start proxy in secure mode using one of the following two options:
  • To manually start a proxy in secure mode, follow the steps in Using the Proxy in a secure data store.
  • To start proxy using the script, first configure the proxy, then start it:
    1. Open a new terminal and navigate to $KVHOME directory.
    2. Invoke the script (setup-http-proxy-sec.sh) to configure the following:
      • Create a user (proxy_user) as the proxy needs an identity to connect to the secure data store.
      • Create a new password file to store the credentials needed to login as the proxy user.
      • Create a login file proxy.login for the proxy user.
      • Create self-signed certificates that can be used to securely connect to the Oracle NoSQL Database Proxy.
      For more information, see .Using the Proxy in a secure data store

      Note:

      If you have started KVLite with a nondefault value for KV_PORT, ensure that you set the same port value before configuring the proxy. 
      $/bin/bash setup-http-proxy-sec.sh
      You get an output as shown below:
      Creating password
Creating USER proxy_user
Dec 30, 2025 6:48:23 AM org.jline.utils.Log logr
WARNING: Unable to create a system terminal, creating a dumb terminal (enable debug logging for more information)
sql-> Statement completed successfully
sql-> Creating proxy secfiles
Created
Secret created
Creating certificate
Generating a RSA private key
..........................................................................................................................................................................................++++
............................................++++
writing new private key to 'kvroot/proxy/key.pem'
-----
Certificate was added to keystore
    3. Open a new terminal and navigate to $KVHOME directory.
    4. The script, start_proxy.sh, contains the following environment variables with default values to start proxy. You can run the script as-is or set any of these variables before running the script to override the defaults.

      Note:

      If you have started KVLite with a non-default value for KV_PORT, ensure that you set the same port value before starting the proxy.

      Table - Environment Variables for Proxy

      Name of the variable Optional Description Sample values
      HOSTNAME Yes Identifies a host name associated with the node on which the script to configure kvlite is run. localhost
      KV_PORT Yes The TCP/IP port on which KVLite should be contacted. Sometimes referred to as the registry port. 5000
      KV_PROXY_PORT Yes The TCP/IP port on which proxy should be contacted.

      Non-Secure proxy: Use 80 if root privilege is there, else 8080

      Secure proxy: Use 443 if root privilege is there, else 8443
    5. Invoke the script start_proxy.sh
      $/bin/bash start_proxy.sh
      You get an output as shown below:
      Starting Proxy
Proxy creating SSL channel
Proxy started:
async=false
helperHosts=localhost:5000
httpPort=0
httpsPort=8443
idleReadTimeout=0
kvConsistency=NONE_REQUIRED
kvDurability=COMMIT_NO_SYNC
kvRequestTimeout=-1
monitorStatsEnabled=false
numAcceptThreads=3
numRequestThreads=32
proxyType=KVPROXY
sslCertificate=kvroot/proxy/certificate.pem
sslPrivateKey=kvroot/proxy/key-pkcs8.pem
sslPrivateKeyPass=iTO6aUCnh9XdsgkxFig=
sslProtocols=TLSv1.2,TLSv1.1,TLSv1
storeName=kvstore
storeSecurityFile=kvroot/proxy/proxy.login
verbose=true
proxyVersion=null
kvclientVersion=25.3.21

Start KVLite in non-secure mode:

You can start KVLite in non-secure mode using one of the following options:
  • Open a terminal and navigate to $KVHOME, the directory where you have installed Oracle NoSQL Database distribution.
    $ cd $KVHOME
$ 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 store instance. The value of N is in GB and must be >= 1. By default, the created store has a size of 10 GB, and this flag must be used to override that. The size cannot be changed after the instance has been created and use of the flag on an existing instance is ignored.

  • To start KVLite using the script:
    1. Download and extract the ZIP file (start_nonsecurekvlite.zip) into your $KVHOME directory. The ZIP file contains the script required to start KVLite in non-secure mode. The script, start_nonsecure_kvlite.sh, contains the environment variables with default values to start KVLite. You can run the script as-is or set any of these variables before running it to override the defaults. For details on the environment variables, see the table - Environment Variables for KVLite.
    2. Invoke the script (start_nonsecure_kvlite.sh) to start KVLite in non-secure mode.
      $/bin/bash start_nonsecure_kvlite.sh
      You get an output as shown below:
      Created new kvlite store with args: -root kvroot -store kvstore -host localhost
-port 5000 -admin-web-port 5999 - secure-config disable
  • To ensure KVLite is running, see Verify your Installation.

To start Proxy in a non-secure mode

The proxy is required only for SDK-based clients (such as Java, Python, Node.js, C#, Rust, or Go SDKs). It is not required when using the Java Direct Driver.

You can start proxy in non-secure mode using one of the two following options:
  • To manually start a proxy in non-secure mode, follow the steps from Using the Proxy in a non-secure data store.
  • Use the script (start_nonsecure_proxy.sh) to start the proxy for a non-secure data store. It contains the environment variables with default values to start a non-secure proxy. You can run the script as-is or set any of the variables before running the script to override the defaults. For details on the environment variables, see the table - Environment Variables for Proxy. 
    $/bin/bash start_nonsecure_proxy.sh
    You get an output as shown below:
    Starting Proxy
Proxy started:
async=false
helperHosts=localhost:5000
httpPort=8080
httpsPort=0
idleReadTimeout=0
kvConsistency=NONE_REQUIRED
kvDurability=COMMIT_NO_SYNC
kvRequestTimeout=-1
monitorStatsEnabled=false
numAcceptThreads=3
numRequestThreads=32
proxyType=KVPROXY
sslProtocols=TLSv1.2,TLSv1.1,TLSv1
storeName=kvstore
verbose=true
proxyVersion=null
kvclientVersion=25.1.13

For a complete list of command line options that can be provided with the kvlite utility, see kvlite.

To connect KVLite with the SQL Shell, see Running the SQL Shell.