Guest Post by:
Dave Rubin, Senior Director, NoSQL and Embedded Database Development, Oracle

In a previous post, The Oracle NoSQL Database development team is thrilled to have the Oracle NoSQL Database Cloud Service fully integrated on the native Oracle Cloud Infrastructure.

In a previous post,I showed how easy it was to write a simple Hello World application in Java using the recently introduced Oracle NoSQL Database Cloud Service.  In fact, I claimed that you could write your first HelloWorld application in Java in 15 minutes or less.  In this post, I will demonstrate the same HelloWorld application written in Python, and if you are a Python developer and already have access to the Oracle Cloud, I believe your first HelloWorld application can be written in less than 10 minutes.  In the first post, I also talked about why you might want to use a NoSQL Database for certain applications.   For that discussion, you can check out the post here 15-minutes-to-hello-world.  The remainder of this post will focus on writing Python code for your first Oracle NoSQL Database cloud application. 

Getting Started with the Oracle NoSQL Database Cloud Service

The Oracle NoSQL Database Cloud Service is a server-less, fully managed data store that delivers predictable single-digit response times and allows applications to scale on-demand via provisioning API calls.  There are four simple steps to getting started with the Oracle NoSQL Database Cloud Service.

  •  Download the Oracle NoSQL Database SDK. 

  • Create a compartment for your table (if you do not want your table in the root compartment).

  • Connect to the Oracle NoSQL Database cloud service.

  • Create a table with provisioned reads/sec, writes/sec, and GB storage.

  • Write data to the table and read data from the table.

Furthermore, you can use free cloud credits to do all of this and not pay a single penny. 

Once you have created a cloud account, you can either navigate to the Oracle NoSQL Database table management console or if you are like most developers, quickly move onto writing your first hello world code.  For this release of the Oracle NoSQL Database Cloud Service, you can write your first hello world program using Python, Node.js, Java, or Go.  Future releases of the service will support C++, C#, and other popular programming languages.  I will use Python for the remainder of this blog.

Download the Oracle NoSQL Database SDK

Since access to the Oracle NoSQL Cloud Service is via HTTP, you can run your application directly on your laptop and connect to the database service over the internet.  While I would never recommend using the internet as a network transport for performance-sensitive applications, it works perfectly for our hello world example.  In fact, it is likely that you would want to deploy a real application by running inside your own tenancy, co-located in the same Oracle Cloud Infrastructure region as your Oracle NoSQL table, and use the Oracle Cloud Infrastructure Service Gateway to connect to the NoSQL Cloud Service.

Like other open source Python packages, you can find the Oracle NoSQL Database Python SDK at PyPi.    

When you search for Oracle NoSQL, you will see the following results.  The latest Oracle NoSQL Driver that lets you connect to the cloud service or Oracle NoSQL Database running anywhere is called borneo, so I will choose to install this one locally on my laptop.                                        

Borneo

Below, I am running pip install borneo to install the Oracle NoSQL Database Python SDK on my laptop.

Since we will be connecting to the Oracle NoSQL Database Cloud service, we must also install the Oracle Cloud Infrastructure package.  Below, I am using pip install oci in the screenshot below to install the oci package on my laptop.  More detailed installation instructions can be found here https://nosql-python-sdk.readthedocs.io/en/latest/installation.html.

Create a Compartment for Your Table

If you would like your table to be created in your own compartment (e.g. namespace) rather than the root compartment, you can create a compartment by navigating to the compartments section of the Identity menu item in the cloud console.

Connect to the Oracle NoSQL Database Cloud Service

The Oracle NoSQL Database Cloud Service uses the Oracle Cloud Infrastructure native cloud Identity Access Manager (IAM) for authentication and authorization.  In the Python API documentation,  (https://nosql-python-sdk.readthedocs.io/en/latest/api.html) for the SDK, you will notice a borneo.iam package, which currently contains a single class, SignatureProvider.    We will use this class to provide our authentication information to the cloud service. 

 

Before you can authenticate your application with the cloud service, you must generate a key pair and upload your public key to the Oracle Cloud.  The instructions here will guide you through generating an API signing key and uploading the public portion of that key to the Oracle Cloud https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm#How

The following information will be needed for you to successfully authenticate with the cloud service:

The code below is structured as follows: 

  1. The function get_connection – This is where you will fill in your specific credentials.  This method will perform authentication with the Oracle NoSQL Cloud Service and return a handle to the service. 
  2. The function create_table  – This function will create a table with two columns; an ID column of type LONG and a content column of type JSON.
  3. The method write_a_record – This method will write a single record to the hello world table.
  4. The method read_a_record – This method will read a single record from the hello world table and return this record as a JSON string.
  5. The main entry point – Will first get a connection to the service, create the table, write a single record, read that record back, and finally print that record to stdout.

 


import os

from borneo import (Regions, NoSQLHandle, NoSQLHandleConfig,
                    PutRequest, TableRequest,
                    GetRequest, TableLimits, State)
from borneo.iam import SignatureProvider

# Given a region, and compartment, instantiate a connection to the
# cloud service and return it
def get_connection(region, compartment):
    print("Connecting to the Oracle NoSQL Cloud Service")
    provider = SignatureProvider(
        tenant_id='Your tenant OCI goes here',
        user_id='Your user OCID goes here',
        private_key='A fully qualified path to your key file goes here',
        fingerprint='The fingerprint for your key pair goes here',
        pass_phrase='The pass phrase for your key goes here')

    config = NoSQLHandleConfig(region, provider)
    config.set_default_compartment(compartment)
    return(NoSQLHandle(config))

# Given a handle to the Oracle NoSQL Database cloud service,
# this function will create the hello_world table with two columns
# and set the read units to 1, write units to 1, and GB storage to 1
def create_table(handle):
    statement = 'create table if not exists hello_world (id long, ' +\
                'content JSON, primary key(id))'

    print('Creating table: ' + statement)
    request = TableRequest().set_statement(statement)\
        .set_table_limits(TableLimits(1, 1, 1))

    # Ask the cloud service to create the table, waiting for a total of
    # 40000 milliseconds and polling the service every 3000
    # milliseconds to see if the table is active
    table_result = handle.do_table_request(request, 40000, 3000)

    if (table_result.get_state() != State.ACTIVE):
        table_result.wait_for_completion(handle, 40000, 3000)

    # Check to see if the table is in the ACTIVE state
    if (table_result.get_state() != State.ACTIVE):
        raise NameError('Table hello_world is in an unexpected state ' +
                    str(table_result.get_state()))


# Given a handle to the Oracle NoSQL Database cloud service, the
# name of the table to write the record to, and an instance of a dictionary,
# formatted as a record for the table, this function will write the record to
# the table
def write_a_record(handle, table_name, record):
    request = PutRequest().set_table_name(table_name)
    request.set_value(record)
    handle.put(request)


# Given a handle to the Oracle NoSQL Database cloud service, the name of
# the table to read from, and the primary key value for the table,
# this function will read the record from the table and return it
def read_a_record(handle, table_name, pk):
    request = GetRequest().set_table_name(table_name)
    request.set_key({'id' : pk})
    return(handle.get(request))

def main():
    handle = get_connection(Regions.US_ASHBURN_1,
                            'Your compartment name goes here')
    create_table(handle)

    record = {'id' : 1, 'content' : {'hello' : 'world'}}
    write_a_record(handle, 'hello_world', record)
    print('Wrote record: \n\t'  + str(record))

    the_written_record = read_a_record(handle, 'hello_world', 1)
    print('Read record: \n\t' + str(record))
    os._exit(os.EX_OK)

if __name__ == "__main__":
    main()

If you take the code above and place it in a file entitled HelloWorld.py and fill in your credentials in the get_connection()function as well as the fully qualified name to the compartment where you want your table created,  you can run this file using python HelloWorld.py as specified below:

For more information about the Python SDK and pointers to more example code on Github, take a look here https://pypi.org/project/borneo/.  

Using the Native Oracle Cloud Infrastructure Console

You can also explore your tables using the Oracle Cloud Infrastructure console.  On the left-hand menu, simply navigate to the NoSQL Database menu item.

Once you click on the hello_world table link, you will see the following page:

Clicking on the Table rows control and then the clicking the Run query button control will display the record that you just inserted into the table:

If you have questions regarding this exercise, please send an email to oraclenosq-info_ww@oracle.com with “Hello World – Python” in the subject line, and someone will get back to you as soon as possible.