Obtaining a NoSQL Handle

Learn how to access tables using Oracle NoSQL Database Drivers. Start developing your application by creating a NoSQL Handle. Use the NoSQLHandle to access the tables and execute all operations.

Non-secure data store

In your application, create a NoSQLHandle which will be your connection to the Oracle NoSQL Database Proxy. Using this NoSQLHandle you could access the Oracle NoSQL Database tables and execute Oracle NoSQL Database operations.

The NoSQLHandleConfig class allows an application to specify the security configuration information which is to be used by the handle. For non-secure access, create an instance of the StoreAccessTokenProvider class with the no-argument constructor. Provide the reference of StoreAccessTokenProvider class to the NoSQLHandleConfig class to establish the appropriate connection.

The following is an example of creating NoSQLHandle that connects to a non-secure proxy.

// Service URL of the proxy
String endpoint = "http://<proxy_host>:<proxy_http_port>";

// Create a default StoreAccessTokenProvider for accessing the proxy
StoreAccessTokenProvider provider = new StoreAccessTokenProvider();

// Create a NoSQLHandleConfig
NoSQLHandleConfig config = new NoSQLHandleConfig(endpoint);

// Setup authorization provider using StoreAccessTokenProvider
config.setAuthorizationProvider(provider);

// Create NoSQLHandle using the information provided in the config
NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);

where,

proxy_host is the hostname of the machine running the proxy service. This should match the host you configured earlier.
proxy_http_port is the port on which the proxy is listening for requests. This should match the http port you configured earlier.

A handle is created by first creating a borneo.NoSQLHandleConfig instance to configure the communication endpoint, authorization information, as well as default values for handle configuration.

An example of acquiring a NoSQLHandle for a non-secure Oracle NoSQL Database:

from borneo import NoSQLHandle, NoSQLHandleConfig
from borneo.kv import StoreAccessTokenProvider
endpoint = 'http://<proxy_host>:<proxy_http_port>'
# Create the AuthorizationProvider for a not secure store:
ap = StoreAccessTokenProvider()
# create a configuration object
config = NoSQLHandleConfig(endpoint).set_authorization_provider(ap)
# create a handle from the configuration object
handle = NoSQLHandle(config)

where,

proxy_host is the hostname of the machine running the proxy service. This should match the host you configured earlier.
proxy_http_port is the port on which the proxy is listening for requests. This should match the http port you configured earlier.

The first step in connecting a go application to the data store is to create a nosqldb.Client handle used to send requests to the service. In this case, the Endpoint config parameter should point to the NoSQL proxy host and port location.

cfg:= nosqldb.Config{
    Mode:     "onprem",
    Endpoint: "http://<proxy_host>:<proxy_http_port>",
}
client, err:=nosqldb.NewClient(cfg)
...

where,

proxy_host is the hostname of the machine running the proxy service. This should match the host you configured earlier.
proxy_http_port is the port on which the proxy is listening for requests. This should match the http port you configured earlier.

The NoSQLClient class represents the main access point to the service. To create instance of NoSQLClient you need to provide appropriate configuration information.

To connect to the proxy in non-secure mode, you need to specify communication endpoint.

Use the following code to connect to the proxy.

import { NoSQLClient, ServiceType } from 'oracle-nosqldb';
const client = new NoSQLClient({
    serviceType: ServiceType.KVSTORE,
    endpoint: '<proxy_host>:<proxy_http_port>'
});

where,

proxy_host is the hostname of the machine running the proxy service. This should match the host you configured earlier.
proxy_http_port is the port on which the proxy is listening for requests. This should match the http port you configured earlier.

You may also choose to store the same configuration in a file. Create file config.json with following contents:

{
    "serviceType": "KVSTORE",
    "endpoint": "<proxy_host>:<proxy_http_port>",
}

Then you can use this sample file to create a NoSQLClient instance:

import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient('</path/to/config.json>');

Note:

If a file path is supplied, the path can be absolute or relative to the current working directory of the application.

Class NoSQLClient represents the main access point to the service. To create instance of NoSQLClient you need to provide appropriate configuration information.

In non-secure mode, the driver communicates with the proxy via the HTTP protocol. The only information required is the communication endpoint. For on-premise NoSQL Database, the endpoint specifies the url of the proxy, in the form http://proxy_host:proxy_http_port.

You can provide an instance of NoSQLConfig either directly or in a JSON configuration file.

var client = new NoSQLClient(
    new NoSQLConfig
    {
        ServiceType = ServiceType.KVStore,
        Endpoint = "<proxy_host>:<proxy_http_port>"
    });

where,

proxy_host is the hostname of the machine running the proxy service. This should match the host you configured earlier.
proxy_http_port is the port on which the proxy is listening for requests. This should match the http port you configured earlier.

You may also choose to provide the same configuration in JSON configuration file. Create file config.json with following contents:

{
    "ServiceType": "KVStore",
    "Endpoint": "<proxy_host>:<proxy_http_port>"
}

Then you may use this file to create NoSQLClient instance:

varclient = new NoSQLClient("</path/to/config.json>");

Note:

If a file path is supplied, the path can be absolute or relative to the current working directory of the application.

In non-secure mode, the driver communicates with the proxy via the HTTP protocol. The only information required is the communication endpoint. For on-premise NoSQL Database, the endpoint specifies the URL of the proxy, in the form http://proxy_host:proxy_http_port.


        let handle = Handle::builder()
        .mode(HandleMode::Onprem)?
        .endpoint("http://<proxy_host>:<proxy_http_port>")?
        .build().await?;

Secure data store

In your application, create a NoSQLHandle to connect to the secure data store through the proxy. Using theNoSQLHandle you could access the Oracle NoSQL Database tables and execute Oracle NoSQL Database operations. Before you start up the proxy, you need to create a bootstrap user (proxy_user) in the secure data store for the proxy to bootstrap its security connection. See Create a user and start proxy for a secure data store for more details.

You also need to create an application user for your application to access the secure data store. The application user will connect to the data store and perform various database operations.

sql-> CREATE USER <appln_user> IDENTIFIED BY "<applnuser_password>"

Your application user should be given a role based on the least privilege access, carefully balancing the needs of the application with security concerns. See Configuring privileges and roles for more details.

The first step for a Java application is to create a NoSQLHandle which will be used to send requests to the secure data store. The handle is configured using your credentials and other authentication information.

You can connect to a secure data store using the following steps.

Create an application user (appln_user) to access the data store through the secure proxy as discussed above.
Install the Oracle NoSQL Database Java Driver in the application's classpath.
For secure access, create an instance of the StoreAccessTokenProvider class with the parameterized constructor, and configure the NoSQL handle to use it. Use the following code to connect to the proxy.
```
String endpoint = "https://<proxy_host>:<proxy_https_port>";
StoreAccessTokenProvider atProvider = 
    new StoreAccessTokenProvider("<appln_user>","<applnuser_password>".toCharArray());
NoSQLHandleConfig config = new NoSQLHandleConfig(endpoint);
config.setAuthorizationProvider(atProvider);
NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);
```
where,
- proxy_host is the hostname of the machine running the proxy service. This should match the proxy host you configured earlier.
- proxy_https_port is the port on which the proxy is listening for requests. This should match the proxy https port configured earlier.
- appln_user is the user created to connect to the secure store. This should match the user created in the above section.
- applnuser_password is the password of the appln_user.
You can specify the details of the trust store containing the SSL certificate for the proxy in one of the following two ways.
You can set it as part of your Java code as shown below:
```
/* the trust store containing SSL cert for the proxy */ 
System.setProperty("javax.net.ssl.trustStore", trustStore);
if (trustStorePassword != null) {     
   System.setProperty("javax.net.ssl.trustStorePassword",trustStorePassword); 
} 
```
Alternatively, you can start-up the application program and set the driver.trust file's path to the Java trust store by using the following command. This is required as the proxy is already set up using the certificate.pem and key-pkcs8.pem files.
```
java -Djavax.net.ssl.trustStore=<fullpath_driver.trust> \
-Djavax.net.ssl.trustStorePassword=<password of driver.trust> \
-cp .:lib/nosqldriver.jar application_program
```
The driver.trust contains the certificate.pem or rootCA.crt certificate. If the certificate certificate.pem is in a chain signed by a trusted CA that is listed in JAVA_HOME/jre/lib/security/cacerts, then you don't need to append Java environment parameter -Djavax.net.ssl.trustStore in the Java command.

A handle is created by first creating a borneo.NoSQLHandleConfig instance to configure the communication endpoint, authorization information, as well as default values for handle configuration.

You can connect to a secure data store using the following steps.

Create an application user (appln_user) to access the data store through the secure proxy as discussed above.
If running a secure store, a certificate path should be specified through the REQUESTS_CA_BUNDLE environment variable:
```
$ export REQUESTS_CA_BUNDLE=
<full-qualified-path-to-certificate/certificate.pem:$REQUESTS_CA_BUNDLE
```
or borneo.NoSQLHandleConfig.set_ssl_ca_certs().
Use the following code to connect to the proxy.
```
from borneo import NoSQLHandle, NoSQLHandleConfig
from borneo.kv import StoreAccessTokenProvider
endpoint = 'https://<proxy_host>:<proxy_https_port>'
# Create the AuthorizationProvider for a secure store:
ap = StoreAccessTokenProvider(<appln_user>, <applnuser_password>)
# create a configuration object
config = NoSQLHandleConfig(endpoint).set_authorization_provider(ap)
# set the certificate path if running a secure store
config.set_ssl_ca_certs(<ca_certs>)
# create a handle from the configuration object
handle = NoSQLHandle(config)
```
where,
- proxy_host is the hostname of the machine running the proxy service. This should match the proxy host you configured earlier.
- proxy_https_port is the port on which the proxy is listening for requests. This should match the proxy https port configured earlier.
- appln_user is the user created to connect to the secure store. This should match the user created in the above section.
- applnuser_password is the password of the appln_user.

The first step in Oracle NoSQL Database go application is to create a nosqldb.Client handle used to send requests to the service. The handle is configured using your credentials and other authentication information:

You can connect to a secure data store using the following steps.

Create an application user (appln_user) to access the data store through the secure proxy as discussed above.

Use the following code to connect to the proxy.

import (
    "fmt"     
    "github.com/oracle/nosql-go-sdk/nosqldb"
    "github.com/oracle/nosql-go-sdk/nosqldb/httputil"
)
...cfg:= nosqldb.Config{
    Endpoint: "https://<proxy_host>:<proxy_https_port>",
    Mode:     "onprem",
    Username: "<appln_user>",
    Password: "<applnuser_password>",
   },
    // Specify the CertPath and ServerName
    // ServerName is used to verify the hostname for self-signed certificates.
    // This field is set to the "CN" subject value from the certificate specified by CertPath.
    HTTPConfig: httputil.HTTPConfig{
       CertPath: "<fully_qualified_path_to_cert>",
       ServerName: "<server_name>", 
    },
}
client, err:=nosqldb.NewClient(cfg)
iferr!=nil {
    fmt.Printf("failed to create a NoSQL client: %v\n", err)
    return
}
deferclient.Close()
// Perform database operations using client APIs.
// ...

where,

proxy_host is the hostname of the machine running the proxy service. This should match the proxy host you configured earlier.
proxy_https_port is the port on which the proxy is listening for requests. This should match the proxy https port configured earlier.
appln_user is the user created to connect to the secure store. This should match the user created in the above section.
applnuser_password is the password of the appln_user.

To create instance of NoSQLClient you need to provide appropriate configuration information. You can connect to a secure data store using the following steps.

Create an application user (appln_user) to access the data store through the secure proxy as discussed above.
In secure mode the proxy requires the SSL Certificate and Private key If the root certificate authority (CA) for your proxy certificate is not one of the trusted root CAs , the driver needs the certificate chain file (e.g. certificates.pem) or a root CA certificate file (e.g. rootCA.crt) in order to connect to the proxy. If you are using self-signed certificate instead, the driver will need the certificate file (e.g. certificate.pem) for the self-signed certificate in order to connect.
To provide the certificate or certificate chain to the driver, you have two options , either specifying in the code or setting as environment variables.
You can specify the certificates through httpOpt property while creating the NoSQL handle. Inside httpOpt you can use ca property to specify the CA as shown below.
```
const client = new NoSQLClient({ .....,     
  httpOpt: {                     
    ca: fs.readFileSync(<caCertFile>)                                    
  },..... 
});
```
Note:
If a file path is supplied, the path can be absolute or relative to the current working directory of the application.
Alternatively, before running your application, set the environment variable NODE_EXTRA_CA_CERTS as shown below.
```
export NODE_EXTRA_CA_CERTS="<fully_qualified_path_to_driver.trust>"
```
where driver.trust is either a certificate chain file (certificates.pem) for your CA, your root CA's certificate (rootCA.crt) or a self-signed certificate (certificate.pem).
To connect to the proxy in secure mode, in addition to communication endpoint, you need to specify user name and password of the driver user. This information is passed in Config#auth object under kvstore property and can be specified in one of 3 ways as described below.
You may choose to specify user name and password directly:
```
const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
const client = new NoSQLClient({
    endpoint: 'https://<proxy_host>:<proxy_https_port>',
    auth: {
        kvstore: {
            user: '<appln_user>',
            password: '<applnuser_password>'
        }
    }
});
```
where,
- proxy_host is the hostname of the machine running the proxy service. This should match the proxy host you configured earlier.
- proxy_https_port is the port on which the proxy is listening for requests. This should match the proxy https port configured earlier.
- appln_user is the user created to connect to the secure store. This should match the user created in the above section.
- applnuser_password is the password of the appln_user.
This option is less secure because the password is stored in plain text in memory.
You may choose to store credentials in a separate file which is protected by file system permissions, thus making it more secure than previous option, because the credentials will not be stored in memory, but will be accessed from this file only when login is needed. Credentials file should have the following format:
```
{
    "user":     "<appln_user>",
    "password": "<applnuser_password>"
}
```
Then you may reference this credentials file as following:
```
const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
const client = new NoSQLClient({
    endpoint: 'https://<proxy_host>:<proxy_https_port>',
    auth: {
        kvstore: {
            credentials: '<path/to/credentials.json>'
        }
    }
});
```
Note:
If a file path is supplied, the path can be absolute or relative to the current working directory of the application.
You may also reference credentials.json in the configuration file used to create NoSQLClient instance.
```
{
    "endpoint": "https://<proxy_host>:<proxy_https_port>",
    "auth": {
        "kvstore": {
            "credentials": "<path/to/credentials.json>"
        }
    }
}
```
```
const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
const client = new NoSQLClient('</path/to/config.json>');
```
Note:
If a file path is supplied, the path can be absolute or relative to the current working directory of the application.

To create instance of NoSQLClient you need to provide appropriate configuration information. You can connect to a secure data store using the following steps.

Create an application user (appln_user) to access the data store through the secure proxy as discussed above.
To connect to the proxy in secure mode, in addition to communication endpoint, you need to specify user name and password of the driver user. This information is passed in the instance of KVStoreAuthorizationProvider and can be specified in any of the ways as described below.
You may choose to specify user name and password directly:
```
var client = new NoSQLClient(
    new NoSQLConfig
    {
        Endpoint = "https://<proxy_host>:<proxy_https_port>",
        AuthorizationProvider = new KVStoreAuthorizationProvider(
            <appln_user>, // user name as string
            <applnuser_password>) // password as char[]
    });
```
where,
- proxy_host is the hostname of the machine running the proxy service. This should match the proxy host you configured earlier.
- proxy_https_port is the port on which the proxy is listening for requests. This should match the proxy https port configured earlier.
- appln_user is the user created to connect to the secure store. This should match the user created in the above section.
- applnuser_password is the password of the appln_user.
This option is less secure because the password is stored in plain text in memory for the lifetime of NoSQLClient instance. Note that the password is specified as char[] which allows you to erase it after you are finished using NoSQLClient.
You may choose to store credentials in a separate file which is protected by file system permissions, thus making it more secure than the previous option, because the credentials will not be stored in memory, but will be accessed from this file only when the login to the store is required. Credentials file should have the following format:
```
{
    "UserName": "<appln_user>",
    "Password": "<applnuser_password>"
}
```
Then you may use this credentials file as following:
```
var client = new NoSQLClient(
    new NoSQLConfig
    {
        Endpoint: 'https://<proxy_host>:<proxy_https_port>',
        AuthorizationProvider = new KVStoreAuthorizationProvider(
            "<path/to/credentials.json>")
    });
```
Note:
If a file path is supplied, the path can be absolute or relative to the current working directory of the application.
You may also reference credentials.json in the JSON configuration file used to create NoSQLClient instance:
```
{
    "Endpoint": "https://<proxy_host>:<proxy_https_port>",
    "AuthorizationProvider": {
        "AuthorizationType": "KVStore",
        "CredentialsFile": "<path/to/credentials.json>"
    }
}
```
```
var client = new NoSQLClient("</path/to/config.json>");
```
Note that in config.json the authorization provider is represented as a JSON object with the properties for KVStoreAuthorizationProvider and an additional AuthorizationType property indicating the type of the authorization provider, which is KVStore for the secure on-premises store.

You need to provide trusted root certificate to the driver if the certificate chain for your proxy certificate is not rooted in one of the well known CAs. The provided certificate may be either your custom CA or self-signed proxy certificate. It must be specified using TrustedRootCertificateFile property, which sets a file path (absolute or relative) to a PEM file containing one or more trusted root certificates (multiple roots are allowed in this file). This property is specified as part of ConnectionOptions in NoSQLConfig.

var client = new NoSQLClient(
    new NoSQLConfig {
       Endpoint: 'https://<proxy_host>:<proxy_https_port>',
       AuthorizationProvider = new KVStoreAuthorizationProvider( "<path/to/credentials.json>"),
       ConnectionOptions: { "TrustedRootCertificateFile": "<path/to/certificates.pem>" }
});

Note:

If a file path is supplied, the path can be absolute or relative to the current working directory of the application.

You can connect to a secure data store using the following steps.

Create an application user (appln_user) to access the data store through the secure proxy as discussed above.
To connect to the proxy in secure mode, in addition to communication endpoint, you need to specify the user name and password of the driver user. This information is passed as shown below.
```
    {
        let handle = Handle::builder()
        .endpoint("https://<proxy_host>:<proxy_https_port>")?  
        .mode(HandleMode::Onprem)?
        .onprem_auth("<appln_user>", "<applnuser_password>")?
        .build().await?;       
    }
```
where
- proxy_host is the host name of the machine running the proxy service. This should match the proxy host you configured earlier.
- proxy_https_port is the port on which the proxy is listening for requests. This should match the proxy https port configured earlier.
- appln_user is the user created to connect to the secure store. This should match the user created in the above section.
- applnuser_password is the password of the appln_user.

Instead of providing the credentials directly, you can also store the credentials in a separate file which is protected by file system permissions. Credentials file should have the following format:

{
    "UserName": "<appln_user>",
    "Password": "<applnuser_password>"
}

Then you may use this credentials file as following:


    {
        let handle = Handle::builder()
        .endpoint("https://<proxy_host>:<proxy_https_port>")?  
        .mode(HandleMode::Onprem)?
        .onprem_auth_from_file("/path/to/user_pass_file")?
        .build().await?;       
    }

Note:

If a file path is supplied, the path can be absolute or relative to the current working directory of the application.

You need to provide trusted root certificate to the driver if the certificate chain for your proxy certificate is not rooted in one of the well known certificate authorities (CA). The provided certificate may be either your custom certificate authority or self-signed proxy certificate.


{
        let handle = Handle::builder()
        .endpoint("https://<proxy_host>:<proxy_https_port>")?
        .mode(HandleMode::Onprem)?
        .onprem_auth_from_file("/path/to/user_pass_file")?
        .add_cert_from_pemfile("/path/to/certificate.pem")?
        .build().await?;
}

Note:

If a file path is supplied, the path can be absolute or relative to the current working directory of the application.

If you want to instruct the client to skip verifying the server’s certificate, you can specify as follows:


{
        let handle = Handle::builder()
        .endpoint("https://<proxy_host>:<proxy_https_port>")?
        .mode(HandleMode::Onprem)?
        .onprem_auth_from_file("/path/to/user_pass_file")?
        .danger_accept_invalid_certs(true)?
        .build().await?;
}