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.

In your application, create 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. To instantiate NoSQLHandle, pass a reference of NoSQLHandleConfig class to the NoSQLHandleFactory.CreateNoSQLHandle method. Provide the Oracle NoSQL Database Proxy URL as a parameterized constructor to instantiate the NoSQLHandleConfig class.

You could configure the proxy in the Oracle NoSQL Database server in either non-secure or secure mode. 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. For secure access, create an instance of the StoreAccessTokenProvider class with the parameterized constructor. Provide the reference of StoreAccessTokenProvider class to the NoSQLHandleConfig class to establish the appropriate connection.

See Oracle NoSQL Java SDK API Reference for more details on the various classes and methods.

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

// Service URL of the proxy
String endpoint = "http://localhost:5000";

// 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);

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

// Service URL of the secure proxy
String endpoint = "https://localhost:5000";

// Username of kvstore
String userName = "driver_user";

// Password of the driver user
String password = "DriverPass@@123";

//Construct StoreAccessTokenProvider with username and password
StoreAccessTokenProvider provider = 
    new StoreAccessTokenProvider(userName, password.toCharArray());

// 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);

For secure access, the StoreAccessTokenProvider parameterized constructor takes the following arguments.

username is the username of the kvstore.
password is the password of the kvstore user.

User should generate driver.trust file for the java driver to access the secure proxy. See Generating Certificate and Private Key for the Oracle NoSQL Database Proxy in the Security Guide.

Following is an example of adding the driver.trust file to the client program:

java -Djavax.net.ssl.trustStore=driver.trust -cp .:/lib/nosqldriver.jar Example

A handle has memory and network resources associated with it. Therefore, invoke the NoSQLHandle.close method to free up the resources when the application finishes using the handle.

To minimize network activity, and resource allocation and deallocation overheads, it's best to avoid repeated creation and closing of handles. For example, creating and closing a handle around each operation would incur large resource allocation overheads resulting in poor application performance. A handle permits concurrent operations, so a single handle is sufficient to access tables in a multi-threaded application. The creation of multiple handles incurs additional resource overheads without providing any performance benefit.

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. borneo.NoSQLHandleConfig represents a connection to the service. Once created it must be closed using the method borneo.NoSQLHandle.close() in order to clean up resources. Handles are thread-safe and intended to be shared.

Configure for non-secure on-premise Oracle NoSQL Database

If running a non-secure store, use a http request and use localhost:8080.

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

from borneo import NoSQLHandle, NoSQLHandleConfig
from borneo.kv import StoreAccessTokenProvider
#
# Assume the proxy is running on localhost:8080
#
endpoint = 'http://localhost:8080'
# 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)

Configure for secure on-premise Oracle NoSQL Database

If running a secure store, a certificate path should be specified through the REQUESTS_CA_BUNDLE environment variable:

$ export
    REQUESTS_CA_BUNDLE=<path-to-certificate>/certificate.pem:$REQUESTS_CA_BUNDLE

In addition, a user identity must be created in the store (separately) that has permission to perform the required operations of the application, such as manipulated tables and data. The identity is used in the borneo.kv.StoreAccessTokenProvider. If the store is not secure, an empty instance of borneo.kv.StoreAccessTokenProvider is used.

See Oracle NoSQL Python SDK API Reference for more details on the various classes and methods.

An example of acquiring a NoSQL Handle for a secure Oracle NoSQL Database:

from borneo import NoSQLHandle, NoSQLHandleConfig
from borneo.kv import StoreAccessTokenProvider
#
# Assume the proxy is secure and running on localhost:443
#
endpoint = 'https://localhost:443'
#
# Create the AuthorizationProvider for a secure store:
#
ap = StoreAccessTokenProvider(user_name, password)
#
# Create the AuthorizationProvider for a not secure store:
#
ap = StoreAccessTokenProvider()
#
# 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)

The first step in Oracle NoSQL Database go application is to create a nosqldb.Client handle used to send requests to the service. Instances of the Client handle are safe for concurrent use by multiple goroutines and intended to be shared in a multi-goroutines application. The handle is configured using your credentials and other authentication information:

Configure for non-secure on-premise Oracle NoSQL Database

To connect an application to a non-secure NoSQL database, specify the endpoint at which the Proxy server is running, and specify onprem as configuration mode.

cfg:= nosqldb.Config{
    Mode:     "onprem",
    Endpoint: "http://exampleHostServer:8080",
}
client, err:=nosqldb.NewClient(cfg)
...

Configure for secure on-premise Oracle NoSQL Database

To connect an application to a secure NoSQL database, you need to provide user credentials used to authenticate with the server. If the Proxy server is configured with a self-signed certificate or a certificate that is not trusted by the default system CA, you also need to specifiy CertPath and ServerName for the certificate path and server name used to verify server's certificate.

cfg:= nosqldb.Config{
    Mode:     "onprem",
    Endpoint: "https://exampleHostServer",
    Username: "driverUser",
    Password: []byte("ExamplePassword__123"),
    HTTPConfig: httputil.HTTPConfig{
        CertPath: "/path/to/server-certificate",
        ServerName: "exampleHostServer", // should match the CN subject value from the certificate
    },
}
client, err:=nosqldb.NewClient(cfg)

See Oracle NoSQL Go SDK API Reference for more details on the various classes and methods.

The NoSQLClient class represents the main access point to the service. To create instance of NoSQLClient you need to provide appropriate configuration information. This information is represented by a plain JavaScript object and can be supplied to the constructor of NoSQLClient as the object literal. Alternatively, you may choose to store this information in a JSON configuration file and the constructor of NoSQLClient with the path (absolute or relative to the application's current directory) to that file. For method details, see NoSQLClient class.

Connecting to a Non-Secure Store

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

For example, if using configuration JavaScript object:

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

Note:

Replace

myhost:8080

with the actual system/port for the endpoint in all the code samples.

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

{
    "serviceType": "KVSTORE",
    "endpoint": "myhost:8080",
}

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');

Connecting to a Secure Store

To connect to the proxy in secure mode, in addition to the communication endpoint, you need to specify user name and password of the driver user. This information is passed in the auth object under the kvstore property and can be specified in one of the three ways shown below.

Passing user name and password directly You may choose to specify user name and password directly. This option is less secure because the password is stored in plain text in memory.
```
import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient({
    endpoint: 'https://myhost:8081',
    auth: {
        kvstore: {
            user: 'John',
            password: 'johnsPassword'
        }
    }
});
```
Storing credentials in a file:
You may choose to store credentials in a separate file which is protected by file system permissions. The credentials file must have the following format:
```
{
    "user":     "<Driver user name>",
    "password": "<Driver user password>"
}
```
Then you may reference this sample credentials file as follows:
```
import { NoSQLClient } from 'oracle-nosqldb';

const client = new NoSQLClient({
    endpoint: 'https://myhost:8081',
    auth: {
        kvstore: {
            credentials: 'path/to/credentials.json'
        }
    }
});
```

Creating Your own KVStoreCredentialsProvider:

You may implement your own credentials provider for secure storage and retrieval of driver credentials as an instance of the KVStoreCredentialsProvider interface. The loadCredentials function returns a Promise and thus can be implemented as an async function.

import { NoSQLClient } from 'oracle-nosqldb';

class MyKVStoreCredentialsProvider {
    constructor() {
        // Initialize required state information if needed
    }

    async loadCredentials() {
        // Obtain client id, client secret, user name and user password somehow
        return { // Return credentials object as a result
            user: driverUserName,
            password: 'driverPassword'
        };
    }
}
let client = new NoSQLClient({
    endpoint: 'https://myhost:8081',
    auth: {
        kvstore: {
            credentials: new MyKVStoreCredentialsProvider(myArgs...)
        }
    }
});

Class NoSQLClient represents the main access point to the service. To create instance of NoSQLClient you need to provide appropriate configuration information. This information is represented by NoSQLConfig class which instance can be provided to the constructor of NoSQLClient. Alternatively, you may choose to store the configuration information in a JSON configuration file and use the constructor of NoSQLClient that takes the path (absolute or relative to current directory) to that file.

Connecting to a Non-Secure Store

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. To connect to the proxy in non-secure mode, you need to specify communication endpoint and the service type as ServiceType.KVStore.

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 = "myhost:8080"
    });

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

{
    "ServiceType": "KVStore",
    "Endpoint": "myhost:8080"
}

Then you may use this file to create NoSQLClient instance:

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

Connecting to a Secure Store :

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 one of the 3 ways shown below.

Passing user name and password directly

You may choose to specify user name and password directly. 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. Credentials file should have the following format:

{
    "user":     "<Driver user name>",
    "password": "<Driver user password>"
}

Then you may use this credentials file as following:

var client = new NoSQLClient(
    new NoSQLConfig
    {
        Endpoint: 'https://myhost:8081',
        AuthorizationProvider=newKVStoreAuthorizationProvider(
            "path/to/credentials.json")
    });

You may implement your own credentials provider for secure storage and retrieval of driver credentials. This is the most secure option because you are in control of how the credentials are stored and loaded by the driver. The credentials provider is a delegate function that returns Task<KVStoreCredentials> and thus may be implemented asynchronously.

var client = new NoSQLClient(
    newNoSQLConfig
    {
        "Endpoint": "https://myhost:8081",
        AuthorizationProvider=newKVStoreAuthorizationProvider(
           async (CancellationToken) => {
                // Retrieve the credentials in a preferred manner.await..........
                returnnewKVStoreCredentials(myUserName, myPassword);
           })
    });

See Oracle NoSQL Dotnet SDK API Reference for more details of all classes and methods.