Getting Started with Oracle NoSQL Database Cloud Service

Oracle NoSQL Database Cloud Service is a fully managed database cloud service that is designed for database operations that require predictable, single digit millisecond latency responses to simple queries.

NoSQL Database Cloud Service allows developers to focus on application development rather than setting up cluster servers, or performing system monitoring, tuning, diagnosing, and scaling. NoSQL Database Cloud Service is suitable for applications such as Internet of Things, user experience personalization, instant fraud detection, and online display advertising.

Once you are authenticated against your Oracle Cloud account, you can create a NoSQL table, and specify throughput and storage requirements for the table. Oracle reserves and manages the resources to meet your requirements, and provisions capacity for you. Capacity is specified using read and write units for throughput and GB for storage units.

This article has the following topics:

Setting up Your Service

If you're setting up Oracle NoSQL Database Cloud Service for the first time, follow these tasks as a guide.

Task Reference Related Information
Place an order for Oracle NoSQL Database Cloud Service or sign up for the Oracle Free Trial. Signing Up for Oracle Cloud Infrastructure in Oracle Cloud Infrastructure Documentation.

To learn how to estimate the monthly cost of your Oracle NoSQL Database Cloud Service subscription, see Estimating Your Monthly Cost.

To upgrade your free account or to change your payment method, see Changing Your Payment Method in Oracle Cloud Infrastructure Documentation.

Activate your Oracle Cloud account and sign in for the first time. Signing In to the Console in Oracle Cloud Infrastructure Documentation.

To familiarize yourself with Oracle Cloud Infrastructure Console, see Using the Console in Oracle Cloud Infrastructure Documentation.

(Recommended) Create a compartment for your service. Creating a Compartment

If you're not familiar with compartments, see Understanding Compartments in Oracle Cloud Infrastructure Documentation.

Manage security for your service. About Oracle NoSQL Database Cloud Service Security Model To familiarize yourself with NoSQL Database Cloud Service security model, see About Oracle NoSQL Database Cloud Service Security Model.

Accessing the Service from the Infrastructure Console

Learn how to access the Oracle NoSQL Database Cloud Service service from the Infrastructure Console.

  1. Locate the service URL from the welcome email, and then sign in to your Oracle NoSQL Database Cloud Service.
  2. Open the navigation menu, click Databases, and then click NoSQL Database.
  3. Select the compartment created for your tables by the service administrator.
To view help for the current page, click the help icon Help Drawer icon at the top of the page.

Creating a Compartment

When you sign up for Oracle Cloud Infrastructure, Oracle creates your tenancy with a root compartment that holds all your cloud resources. You then create additional compartments within the tenancy (root compartment) and corresponding policies to control access to the resources in each compartment. Before you create an Oracle NoSQL Database Cloud Service table, Oracle recommends that you set up the compartment where you want the table to belong.

You create compartments in Oracle Cloud Infrastructure Identity and Access Management (IAM). See Setting Up Your Tenancy and Managing Compartments in Oracle Cloud Infrastructure Documentation.

Acquiring Credentials

Learn how to acquire credentials to connect your application to Oracle NoSQL Database Cloud Service.

You need an Oracle Cloud account to connect your application to the Oracle NoSQL Database Cloud Service. If you do not already have an Oracle Cloud account, you can start with Oracle Cloud. The credentials that are used for connecting your application are associated with a specific user. If you want to create a user for your application, see About Setting Up Users, Groups, and Policies.

Information Comprising the Credentials:

Table 1-1 Credentials

What is it? Where to find it?
Tenancy ID and User ID ( Both are OCID ) See Where to Get the Tenancy's OCID and User's OCID in Oracle Cloud Infrastructure Documentation.
API Signing Key

For the application user, an API signing key must be generated and uploaded. If this has already been done this step can be skipped.

To know more, see the following resources in Oracle Cloud Infrastructure Documentation:
Fingerprint for the Signing Key and (Optional) Pass Phrase for the Signing Key The fingerprint and pass phrase of the signing key are created while generating and uploading the API Signing Key. See How to Get the Key's Fingerprint in Oracle Cloud Infrastructure Documentation.

Tip:

Make a note of the location of your private key, optional pass phrase, and fingerprint of the public key while generating and uploading the API Signing Key.

After performing the tasks discussed above, collect the credentials information and provide them to your application.

Providing the Credentials to your Application:

The Oracle NoSQL Database SDKs allow you to provide the credentials to an application in multiple ways. The SDKs support a configuration file as well as one or more interfaces that allow direct specification of the information. See the documentation for the programming language driver that you are using to know about the specific credentials interfaces.

If you are using a configuration file, the default location is ~/.oci/config. The SDKs allow the file to reside in alternative locations. It's content looks like this:
[DEFAULT]
user=ocid1.user.oc1..aaaaaaaas...7ap
fingerprint=d1:b2:32:53:d3:5f:cf:68:2d:6f:8b:5f:77:8f:07:13
key_file=~/.oci/oci_api_key_private.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaap...keq
pass_phrase=mysecretphrase
The [DEFAULT] line indicates that the lines that follow specify the DEFAULT profile. A configuration file can include multiple profiles, prefixed with [PROFILE_NAME]. For example:
[DEFAULT]
user=ocid1.user.oc1..aaaaaaaas...7us
fingerprint=d1:b2:32:53:d3:5f:cf:68:2d:6f:8b:5f:77:8f:07:15
key_file=~/.oci/oci_api_key_private.pem
tenancy=ocid1.tenancy.oc1..aaaaabbap...keq
pass_phrase=mysecretphrase

[MYPROFILE]
user=ocid1.user.oc1..aaaaaaaas...7ap
fingerprint=d1:b2:32:53:d3:5f:cf:68:2d:6f:8b:5f:77:8f:07:13
key_file=~/.oci/oci_api_key_private.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaap...keq
pass_phrase=mysecretphrase

Connecting your Application to NDCS

Learn how to connect your application to Oracle NoSQL Database Cloud Service.

Your application connects to Oracle NoSQL Database Cloud Service by specifying credentials and a target region for the connection. See Acquiring Credentials for the required credentials information.

You provide credentials in your application using either:
  • An API that allows you to directly provide the credentials, or
  • A configuration file

You can connect to NDCS using one of the following methods:

  • Directly providing credentials in the code:
    /* Use the SignatureProvider to supply your credentials to NoSQL Database.
     * By default, the SignatureProvider will read your OCI configuration file 
     * from the default location, ~/.oci/config. See SignatureProvider for 
     * additional options for reading configurations in other ways.*/
    SignatureProvider sp = new SignatureProvider(
     tenantId,     // a string, OCID
     userId,       // a string, OCID
     fingerprint , // a string
     privateKey,   // a string, content of private key
     passPhrase    // optional, char[]
    );
    //Create an handle to access the cloud service in the us-ashburn-1 region.
    NoSQLHandleConfig config = new NoSQLHandleConfig(Region.US_ASHBURN_1);
    config.setAuthorizationProvider(sp);
    NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);
    
    //At this point, your handle is set up to perform data operations. 
  • Connecting Using a Configuration File with a default profile:
    /* Use the SignatureProvider to supply your credentials to NoSQL Database.
     * By default, the SignatureProvider will read your OCI configuration file 
     * from the default location, ~/.oci/config. See SignatureProvider for 
     * additional options for reading configurations in other ways. */
    SignatureProvider sp = new SignatureProvider();
  • Connecting Using a Configuration File with non-default profile:
    /* Use the SignatureProvider to supply your credentials to NoSQL Database. 
    * Specify the full location of the configuration file in the construtor for SignatureProvider. 
    */
    final String config_file = "<path_to_config_file>";
    SignatureProvider sp = new SignatureProvider(config_file);
  • Connecting using an Instance Principal :

    Instance Principal is an IAM service feature that enables instances to be authorized actors (or principals) to perform actions on service resources. Each compute instance has its own identity, and it authenticates using the certificates that are added to it.
    SignatureProvider authProvider = new SignatureProvider();
    authProvider = SignatureProvider.createWithInstancePrincipal();
  • Connecting using a Resource Principal :

    Resource Principal is an IAM service feature that enables the resources to be authorized actors (or principals) to perform actions on service resources.
    SignatureProvider authProvider = new SignatureProvider();
    authProvider = SignatureProvider.createWithResourcePrincipal();

Creating a handle :

You create a handle to access the cloud service in the us-ashburn-1 region.
NoSQLHandleConfig config = new NoSQLHandleConfig(Region.US_ASHBURN_1); 
config.setAuthorizationProvider(sp);
NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config); 

At this point, your handle is set up to perform data operations. See SignatureProvider for more details on the Java classes used.

You can connect to NDCS using one of the following methods:
  • Directly providing credentials in the code:
    from borneo.iam import SignatureProvider
    #
    # Use SignatureProvider directly via API. Note that the
    # private_key argument can either point to a key file or be the
    # string content of the private key itself.
    #
    at_provider = SignatureProvider(tenant_id='ocid1.tenancy.oc1..tenancy',
                                    user_id='ocid1.user.oc1..user',
                                    private_key=key_file_or_key, 
                                    fingerprint='fingerprint',   
                                    pass_phrase='mypassphrase')
  • Connecting Using a Configuration File with a default profile:
    from borneo.iam import SignatureProvider
    #
    # Use SignatureProvider with a default credentials file and
    # profile $HOME/.oci/config
    #
    at_provider = SignatureProvider()
  • Connecting Using a Configuration File with non-default profile:
    from borneo.iam import SignatureProvider
    #
    # Use SignatureProvider with a non-default credentials file and profile
    #
    at_provider = SignatureProvider(config_file='myconfigfile', 
                                    profile_name='myprofile')
  • Connecting using an Instance Principal:

    Instance Principal is an IAM service feature that enables instances to be authorized actors (or principals) to perform actions on service resources. Each compute instance has its own identity, and it authenticates using the certificates that are added to it.
    at_provider =
    SignatureProvider.create_with_instance_principal(region=my_region)
  • Connecting using a Resource Principal :

    Resource Principal is an IAM service feature that enables the resources to be authorized actors (or principals) to perform actions on service resources.
    at_provider = SignatureProvider.create_with_resource_principal()

Creating a handle :

The first step in any Oracle NoSQL Database Cloud Service application is to create a handle used to send requests to the service. The handle is configured using your credentials and other authentication information as well as the endpoint to which the application will connect. An example endpoint is to use the region Regions.US_ASHBURN_1.
from borneo import NoSQLHandle, NoSQLHandleConfig, Regions
from borneo.iam import SignatureProvider
# the region to which the application will connect
region = Regions.US_ASHBURN_1
# create a configuration object
config = NoSQLHandleConfig(region, at_provider)
# create a handle from the configuration object
handle = NoSQLHandle(config)

See SignatureProvider for more details on the Python classes used.

You can connect your application to NDCS using any of the following methods:
  • Directly providing credentials in the code:
    privateKeyFile := "/path/to/privateKeyFile"
    passphrase := "examplepassphrase"
    sp, err := iam.NewRawSignatureProvider("ocid1.tenancy.oc1..tenancy",
                                           "ocid1.user.oc1..user",
                                           "us-ashburn-1", 
                                           "fingerprint", 
                                           "compartmentID", 
                                           privateKeyFile ,
                                           &passphrase )
    if err != nil {
        return
    }
    cfg := nosqldb.Config{
        AuthorizationProvider: sp,
        // This is only required if the "region" property is not 
        //specified in the config file.
        Region: "us-ashburn-1",
    }
  • Connecting Using a Configuration File with a default profile:
    cfg := nosqldb.Config{
    // This is only required if the "region" property is not 
    //specified in ~/.oci/config.
    // This takes precedence over the "region" property when both are specified.
        Region: "us-ashburn-1", 
    }
    client, err := nosqldb.NewClient(cfg)
  • Connecting Using a Configuration File with non-default profile:
    sp, err := iam.NewSignatureProviderFromFile("your_config_file_path", 
               "your_profile_name", "", "compartment_id")
    if err != nil {
        return
    }
    cfg := nosqldb.Config{
        AuthorizationProvider: sp,
        // This is only required if the "region" property is not specified in the config file.
        Region: "us-ashburn-1",
    }
    client, err := nosqldb.NewClient(cfg)
  • Connecting using an Instance Principal:

    Instance Principal is an IAM service feature that enables instances to be authorized actors (or principals) to perform actions on service resources. Each compute instance has its own identity, and it authenticates using the certificates that are added to it.
    sp, err := iam.NewSignatureProviderWithInstancePrincipal("compartment_id")
    if err != nil {
        return
    }
    cfg := nosqldb.Config{
        AuthorizationProvider: sp,
        Region: "us-ashburn-1",
    }
    client, err := nosqldb.NewClient(cfg)
  • Connecting using a Resource Principal :

    Resource Principal is an IAM service feature that enables the resources to be authorized actors (or principals) to perform actions on service resources.
    sp, err := iam.NewSignatureProviderWithResourcePrincipal("compartment_id")
    if err != nil {
        return
    }
    cfg := nosqldb.Config{
        AuthorizationProvider: sp,
        Region: "us-ashburn-1",
    }
    client, err := nosqldb.NewClient(cfg)
You can connect to NDCS using one of the following methods:
  • Directly providing credentials in the code:

    You may specify credentials directly as part of auth.iam property in the initial configuration. Create NoSQLClient instance as follows:
    const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
    let client = new NoSQLClient({
        region: <your-service-region>
        auth: {
            iam: {
                tenantId: myTenancyOCID,
                userId: myUserOCID,
                fingerprint: myPublicKeyFingerprint,
                privateKeyFile: myPrivateKeyFile,
                passphrase: myPrivateKeyPassphrase
            }
        }
    });
  • Connecting Using a Configuration File with a default profile:

    You can store the credentials in an Oracle Cloud Infrastructure configuration file. The default path for the configuration file is ~/.oci/config, where ~ stands for user's home directory. On Windows, ~ is a value of USERPROFILE environment variable. The file may contain multiple profiles. By default, the SDK uses profile named DEFAULT to store the credentials.

    To use these default values, create file named config in ~/.oci directory with the following contents:
    [DEFAULT]
    tenancy=<your-tenancy-ocid>
    user=<your-user-ocid>
    fingerprint=<fingerprint-of-your-public-key>
    key_file=<path-to-your-private-key-file>
    pass_phrase=<your-private-key-passphrase>
    region=<your-region-identifier>
    Note that you may also specify your region identifier together with credentials in the OCI configuration file. The driver will look at the location above by default, and if a region is provided together with credentials, you do not need to provide initial configuration and can use the no-argument constructor:
    const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
    let client = new NoSQLClient();
    Alternatively, you may choose to specify the region in the configuration:
    const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
    let client = new NoSQLClient({ region: Region.US_ASHBURN_1 });
  • Connecting Using a Configuration File with non-default profile:

    You may choose to use different path for OCI configuration file as well as different profile within the configuration file. In this case, specify these within auth.iam property of the initial configuration. For example, if your OCI configuration file path is ~/myapp/.oci/config and you store your credentials under profile Jane:

    Then create NoSQLClient instance as follows:
    const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
    let client = new NoSQLClient({
        region: Region.US_ASHBURN_1,
        auth: {
            iam: {
                configFile: '~/myapp/.oci/config',
                profileName: 'Jane'
            }
        }
    });
  • Connecting using an Instance Principal:

    Instance Principal is an IAM service feature that enables instances to be authorized actors (or principals) to perform actions on service resources. Each compute instance has its own identity, and it authenticates using the certificates that are added to it.

    Once set up, create NoSQLClient instance as follows:
    const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
    const client = new NoSQLClient({
        region: Region.US_ASHBURN_1,
        compartment: 'ocid1.compartment.oc1..............'
        auth: {
            iam: {
                useInstancePrincipal: true
            }
        }
    });
    You may also use JSON config file with the same configuration as described above. Note that when using Instance Principal you must specify compartment id (OCID) as compartment property. This is required even if you wish to use default compartment. Note that you must use compartment id and not compartment name or path. In addition, when using Instance Principal, you may not prefix table name with compartment name or path when calling NoSQLClient APIs.
  • Connecting using a Resource Principal :

    Resource Principal is an IAM service feature that enables the resources to be authorized actors (or principals) to perform actions on service resources.

    Once set up, create NoSQLClient instance as follows:
    const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
    const client = new NoSQLClient({
        region: Region.US_ASHBURN_1,
        compartment: 'ocid1.compartment.oc1...........................'
        auth: {
            iam: {
                useResourcePrincipal: true
            }
        }
    });
    You may also use JSON config file with the same configuration as described above. Note that when using Resource Principal you must specify compartment id (OCID) as compartment property. This is required even if you wish to use default compartment. Note that you must use compartment id and not compartment name or path. In addition, when using Resource Principal, you may not prefix table name with compartment name or path when calling NoSQLClient APIs.
You can connect to NDCS using one of the following methods:
  • Directly providing credentials in the code:

    You may specify credentials directly as IAMCredentials when creating IAMAuthorizationProvider. Create NoSQLClient as follows:
    var client = new NoSQLClient(
        new NoSQLConfig
        {
            Region=<your-service-region>,
            AuthorizationProvider = new IAMAuthorizationProvider(
                new IAMCredentials
                {
                    TenantId=myTenancyOCID,
                    UserId=myUserOCID,
                    Fingerprint=myPublicKeyFingerprint,
                    PrivateKeyFile=myPrivateKeyFile
                })
        });
  • Connecting Using a Configuration File with a default profile:

    You can store the credentials in an Oracle Cloud Infrastructure configuration file. The default path for the configuration file is ~/.oci/config, where ~ stands for user's home directory. On Windows, ~ is a value of USERPROFILE environment variable. The file may contain multiple profiles. By default, the SDK uses profile named DEFAULT to store the credentials

    To use these default values, create file named config in ~/.oci directory with the following contents:
    [DEFAULT]
    tenancy=<your-tenancy-ocid>
    user=<your-user-ocid>
    fingerprint=<fingerprint-of-your-public-key>
    key_file=<path-to-your-private-key-file>
    pass_phrase=<your-private-key-passphrase>
    region=<your-region-identifier>
    Note that you may also specify your region identifier together with credentials in the OCI configuration file. By default, the driver will look for credentials and a region in the OCI configuration file at the default path and in the default profile. Thus, if you provide region together with credentials as shown above, you can create NoSQLClient instance without passing any configuration:
    var client = new NoSQLClient();
    Alternatively, you may specify the region (as well as other properties) in NoSQLConfig:
    var client = new NoSQLClient(
        new NoSQLConfig(
        {
            Region = Region.US_ASHBURN_1,
            Timeout = TimeSpan.FromSeconds(10),
        });
  • Connecting Using a Configuration File with non-default profile:

    You may choose to use different path for OCI configuration file as well as different profile within the configuration file. In this case, specify these within auth.iam property of the initial configuration. For example, if your OCI configuration file path is ~/myapp/.oci/config and you store your credentials under profile Jane:

    Then create NoSQLClient instance as follows:
    var client = new NoSQLClient(
        new NoSQLConfig
        {
            Region = Region.US_ASHBURN_1,
            AuthorizationProvider = new IAMAuthorizationProvider(
                "~/myapp/.oci/config", "Jane")
        });
  • Connecting using an Instance Principal:

    Instance Principal is an IAM service feature that enables instances to be authorized actors (or principals) to perform actions on service resources. Each compute instance has its own identity, and it authenticates using the certificates that are added to it. Once set up, create NoSQLClient instance as follows:
    var client = new NoSQLClient(
        new NoSQLConfig
        {
            Region=<your-service-region>,
            Compartment="ocid1.compartment.oc1.............................",
            AuthorizationProvider=IAMAuthorizationProvider.CreateWithInstancePrincipal()
        });
    You may also represent the same configuration in JSON as follows:
    {
        "Region": "<your-service-region>",
        "AuthorizationProvider":
        {
            "AuthorizationType": "IAM",
            "UseInstancePrincipal": true
        },
        "Compartment": "ocid1.compartment.oc1.............................",
    }

    Note that when using Instance Principal you must specify compartment id (OCID) as compartment property. This is required even if you wish to use default compartment. Note that you must use compartment id and not compartment name or path. In addition, when using Instance Principal, you may not prefix table name with compartment name or path when calling NoSQLClient APIs.

  • Connecting using a Resource Principal :

    Resource Principal is an IAM service feature that enables the resources to be authorized actors (or principals) to perform actions on service resources. Once set up, create NoSQLClient instance as follows:
    var client = new NoSQLClient(
        new NoSQLConfig
        {
            Region = <your-service-region>,
            Compartment =
                "ocid1.compartment.oc1.............................",
            AuthorizationProvider =
                IAMAuthorizationProvider.CreateWithResourcePrincipal()
        });
    You may also represent the same configuration in JSON as follows:
    {
        "Region": "<your-service-region>",
        "AuthorizationProvider":
        {
            "AuthorizationType": "IAM",
            "UseResourcePrincipal": true
        },
        "Compartment": "ocid1.compartment.oc1.............................",
    }

    Note that when using Resource Principal you must specify compartment id (OCID) as compartment property. This is required even if you wish to use default compartment. Note that you must use compartment id and not compartment name or path. In addition, when using Resource Principal, you may not prefix table name with compartment name or path when calling NoSQLClient APIs.

Typical Workflow

Typical sequence of tasks to work with Oracle NoSQL Database Cloud Service.

If you're developing applications using Oracle NoSQL Database Cloud Service for the first time, follow these tasks as a guide.

Task Description More Information
Connect your application Connect your application to use Oracle NoSQL Database Cloud Service tables. Connecting your Application to NDCS
Develop your application Develop your application after connecting to Oracle NoSQL Database Cloud Service tables. Developing in Oracle Cloud

Developing in Oracle NoSQL Database Cloud Simulator

If you're setting up Oracle NoSQL Database Cloud Service for the first time, see Setting up Your Service.

Quick Start Tutorials

Access the quick start tutorials and get started with the service.

  1. Get access to the service.

    Sign up for a Cloud promotion or purchase an Oracle Cloud subscription. Activate your order, create users (optional). See Setting up Your Service.

  2. Acquire credentials to connect your application. See Acquiring Credentials.

  3. Create a table in Oracle NoSQL Database Cloud Service.