Difficulty: beginner
Estimated Time: 35 minutes

The OCI NoSQL Database Service offers a fully managed, on-demand throughput and storage based provisioning that supports JSON, Table and Key-Value datatypes, all with flexible transaction guarantees. It is designed for database operations that require predictable, single digit millisecond latency responses to simple queries. NoSQL Database Cloud Service is suitable for applications such as Internet of Things, user experience personalization, instant fraud detection, and online display advertising.

Data is held in tables that can contain a mix of structured columns - in a relational style - and columns of JSON document type. Data - both structured and unstructured - can be queried schema-less JSON data by using the familiar SQL syntax. It is possible to update (change, add, and remove) parts of a JSON document. Because these updates occur on the server, the need for a read-modify-write cycle is eliminated, which would consume throughput capacity. ACID transactions are supported for full consistency. If required, consistency can be relaxed in favor of lower latency.

In addition to the NoSQL SDKs (Java and Python at the time of writing), Oracle NoSQL Database Cloud Service also provides Oracle Cloud Infrastructure Console for you to access, manage, and use the NoSQL Database Cloud Service. The Oracle Cloud Infrastructure Console lets you create and manage NoSQL tables and indexes declaratively. You can also manipulate the data in your NoSQL tables and monitor your Oracle NoSQL Database Cloud Service from the console. All operations on tables, indexes and data in NoSQL Database service can be performed through the OCI Command Line Interface and the REST APIs. Oracle NoSQL Database Cloud Service provides easy-to-use CRUD (Create Read Update Delete) APIs.

The managed aspect of this services results among other things in data safety: The Oracle NoSQL Database Cloud Service stores data across multiple Availability Domains (ADs) or Fault Domains (FDs) in single AD regions. If an AD or FD becomes unavailable, user data is still accessible from another AD or FD. Also encryption: Data is encrypted at rest (on disk) with Advanced Encryption Standard (AES). Data is encrypted in motion (transferring data between the application and Oracle NoSQL Database Cloud Service) with HTTPS.

In this scenario, you will take your first steps with OCI NoSQL Database Service. You will create a structured table, insert several records, query these records - working both from the command line and from the console. You will also work with schemaless (JSON) documents. In the last step, you will create and run a Node application that uses the Node SDK for NoSQL Dataase to query and create records. Finally, you will turn this Node application into a function that is deployed to OCI.

The scenario uses an Ubuntu 20.04 environment with Docker, OCI CLI and Fn CLI. Before you can start the steps in the scenario, the two Command Line interfaces are downloaded and installed. This will take about one minute.

The assumption is that you have already completed the the REAL OCI Handson Tenancy Preparation Scenario.

Resources

OCI Documentation on NoSQL Database

Summary

This completes your introduction to OCI NoSQL Database Service.

One topic you may want to take a look at is the Oracle NoSQL Database Cloud Simulator, a standalone tool that simulates the cloud service and lets you write and test applications locally without accessing Oracle NoSQL Database Cloud Service. See documentation on this simulator.

Resources

OCI Documentation on NoSQL Database Service

SQL Language Reference for Oracle NoSQL Database

New Features in Oracle NoSQL Database Service

First steps with NoSQL Database on Oracle Cloud Infrastructure

Step 1 of 7

Step 1 - Preparing the lab environment

Some of the steps in this scenario require the use of the OCI Command Line Interface.

Execute the following command to install the OCI CLI:

curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh > install-oci-cli.sh
chmod +777 install-oci-cli.sh
sudo ./install-oci-cli.sh --accept-all-defaults

# add this line to ~/.profile - to make oci a recognized shell command
echo 'oci() { /root/bin/oci "[email protected]"; }' >> ~/.profile
# reload ~/.profile
. /root/.profile

You need to provide details on the OCI tenancy you will work in and the OCI user you will work as. Please open the IDE tab and edit these two files:

  • ~/.oci/config
  • ~/.oci/oci_api_key.pem

Paste the contents that you prepared in the OCI Tenancy preparation scenario.

Finalizing the Environment

Set the environment variable LAB_ID to 1 - unless you are in a workshop with multiple participants and each uses their own number.

export LAB_ID=1

Try out the following command to get a list of all namespaces you currently have access to - based on the OCI Configuration defined above.

oci os ns get

If you get a proper response, the OCI is configured correctly and you can proceed. If you run into an error, ask for help from your instructor.

You need to perform one more edit action on file ~/.oci/config. Open this file in the editor. Copy the entire contents and paste it below the current contents. Now change [DEFAULT] to [FN] in the duplicate block. The file will now look something like:

[DEFAULT]
user=ocid1.user.oc1..aaaaaaaazr7eselv5q
fingerprint=fd:db:13:bd:31
tenancy=ocid1.tenancy.oc1..aaaaaaaaggg6okq
region=us-ashburn-1
key_file=/root/.oci/oci_api_key.pem
[FN]
user=ocid1.user.oc1..aaaaaaaazr7eselv5q
fingerprint=fd:db:13:bd:31
tenancy=ocid1.tenancy.oc1..aaaaaaaaggg6okq
region=us-ashburn-1
key_file=/root/.oci/oci_api_key.pem

Environment Preparation

Check the installed version of Fn CLI. Note: we do not need the Fn server at this stage.

fn version

Configure and set remote context

List the currently available Fn contexts

fn list contexts

Create an appropriate Fn context for working with OCI as provider (see OCI Docs on Functions).

fn create context lab-fn-context --provider oracle

fn use context lab-fn-context

Prepare a number of environment variables. Note: the assumptions here are that you are working in a tenancy in the Ashburn region and a compartment called lab-compartment exists as well as an API Gateway lab-apigw in that same compartment as well as an API Deployment called MY_API_DEPL# on the API Gateway. We need to get references to these resources in order to create new resources in the right place.

export REGION=$(oci iam region-subscription list | jq -r '.data[0]."region-name"')
export REGION_KEY=$(oci iam region-subscription list | jq -r '.data[0]."region-key"')
export USER_OCID=$(oci iam user list --all | jq -r  '.data |sort_by(."time-created")| .[0]."id"')
export TENANCY_OCID=$(oci iam user list --all | jq -r  '.data[0]."compartment-id"') 
cs=$(oci iam compartment list)
export compartmentId=$(echo $cs | jq -r --arg display_name "lab-compartment" '.data | map(select(."name" == $display_name)) | .[0] | .id')

apigws=$(oci api-gateway gateway list -c $compartmentId)
export apiGatewayId=$(echo $apigws | jq -r --arg display_name "lab-apigw" '.data.items | map(select(."display-name" == $display_name)) | .[0] | .id')
depls=$(oci api-gateway deployment list -c $compartmentId)
deploymentEndpoint=$(echo $depls | jq -r --arg display_name "MY_API_DEPL_$LAB_ID" '.data.items | map(select(."display-name" == $display_name)) | .[0] | .endpoint')
apiDeploymentId=$(echo $depls | jq -r --arg display_name "MY_API_DEPL_$LAB_ID" '.data.items | map(select(."display-name" == $display_name)) | .[0] | .id')
# get namespace
nss=$(oci os ns get)
export ns=$(echo $nss | jq -r '.data')

Update the context with the settings relevant for this workshop.

fn update context oracle.compartment-id $compartmentId

fn update context api-url https://functions.$REGION.oci.oraclecloud.com

fn update context registry ${REGION_KEY,,}.ocir.io/$ns/cloudlab-repo

fn update context oracle.profile FN

You can list the currently available Fn contexts again and see whether your changes had an effect (of course they did)

fn list contexts

Login Docker to OCI Container Registry

Next and finally, login to the private Docker Registry that is prepared for you on OCI.

The username you have to provide is composed of <tenancy-namespace>/<username>.

NAMESPACE=$(oci os ns get| jq -r  '.data')
USER_USERNAME=$(oci iam user list --all | jq -r  '.data |sort_by(."time-created")| .[0]."name"')
echo "Username for logging in into Container Registry is $NAMESPACE/$USER_USERNAME"

The password is an Authentication Token generated for the specified user, in the OCI Tenancy preparation scenario. If you do not remember the authentication token, you can generate another one in the OCI Console: https://console.REGION.oraclecloud.com/identity/users//swift-credentials or using the instructions in the preparation scenario.

echo "Open the console at https://console.${REGION,,}.oraclecloud.com/identity/users/$USER_OCID/swift-credentials"

Now you can perform the login. Type the username and press enter, then type or paste the authentication token and press enter again.

docker login ${REGION_KEY,,}.ocir.io