Getting Started with Oracle NoSQL Database Cloud Service (2023)

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

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.

  (Video) 15 minutes to HelloWorld with Oracle NoSQL Database Cloud Service

  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()

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, Regionsfrom borneo.iam import SignatureProvider# the region to which the application will connectregion = Regions.US_ASHBURN_1# create a configuration objectconfig = NoSQLHandleConfig(region, at_provider)# create a handle from the configuration objecthandle = NoSQLHandle(config)

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.

  (Video) Connecting to Oracle NoSQL Database Cloud Service (NDCS) from IntelliJ Plugin

• 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:

  (Video) Oracle NoSQL Database Cloud Service: Most flexible NoSQL Database

  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.

You can use one of these methods to connect to the Oracle NoSQL Database Cloud Service.

1. Use the SignatureProvider instance as a constructor in the NosqlDbConfig class to configure the Spring Data Framework to connect and authenticate with the Oracle NoSQL Database Cloud Service. See SignatureProvider in the Java SDK API Reference.

   import oracle.nosql.driver.iam.SignatureProvider ( <tenantID>, //The Oracle Cloud Identifier (OCID) of the tenancy. <userID>, //The Oracle Cloud Identifier (OCID) of a user in the tenancy. <fingerprint>, //The fingerprint of the key pair used for signing. new File(<privateKeyFile>), //Full path to the key file. char[] passphrase //Optional. A passphrase for the key, if it is encrypted.)

2. Use the SignatureProvider with the Instance principal authentication to connect to the Oracle NoSQL Database Cloud Service. This requires a one-time setup. For more details, see Instance principal authentication.

   SignatureProvider.createWithInstancePrincipal()

3. Use the Cloud Simulator, which requires either an AuthorizationProvider instance from the NosqlDbConfig class or a helper method such as NosqlDbConfig.createCloudSimConfig().

   com.oracle.nosql.spring.data.NosqlDbFactory.CloudSimProvider.getProvider()