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

In previous posts, I showed how easy it was to write a simple Hello World application in Javascript and Python using the recently introduced Oracle NoSQL Database Cloud Service.  In this post, I will demonstrate the same HelloWorld application written in Go, and if you are a Go developer and already have access to the Oracle Cloud, I believe your first HelloWorld application can be written in less than 15 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 Go 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 the application to scale on-demand via provisioning API calls.  There are four simple steps to getting started with the Oracle NoSQL Database Cloud Service.

• Reference the Oracle NoSQL Database Go SDK from your Go application

• 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 Go, Python, Node.js, or Java.  Future releases of the service will support C++, C#, and other popular programming languages.  I will use Go for the remainder of this blog.

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.

Reference the Oracle NoSQL Database SDK from Your Go Application

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, most likely 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 Go packages, the Oracle NoSQL Database Go SDK is hosted on GitHub and is automatically downloaded by the Go environment when it detects an import of any of the SDK packages.  In your application, you simply need to import the SDK directly from GitHub as follows:

               import “github.com/oracle/nosql-go-sdk/nosqldb

 You can find the Oracle NoSQL Database Go SDK on GitHub at NoSQL Go SDK.  The README.md, depicted in Figure 1, contains the following important information for you to get started:

• Version dependencies – Dependencies for the Go runtime as well as specific instructions for the specific version of the runtime that you might be using.
• Installation instructions for the SDK, and if you are running the NoSQL Database in your own datacenter, instructions on installing the Oracle NoSQL Database proxy server.
• Instructions on how to configure your application for whatever environment you are using (server-less cloud service, your own cluster, or CloudSim, a single node-local instance of the cloud service that runs on your laptop).  In this blog, we will focus exclusively on connecting to the cloud service.

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 Go API documentation,  (https://godoc.org/github.com/oracle/nosql-go-sdk/nosqldb) for the SDK, you will notice a link entitled directories.  Clicking on that link will yield the list of Go packages that encompass the NoSQL Database Go SDK.

Clicking on the iam package will display the APIs in this package along with a link to the iam subdirectory.  Clicking there will yield the APIs in the iam package as seen below:

We will be using the SignatureProvider type and the NewSignatureProvider function from the iam package to pass our credentials to the cloud service for authentication.

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:

• Tenancy and user OCID – This page (https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm#Other) will help you locate your tenancy and user OCIDs.
• Private key file and fingerprint – The file holding your private key should be safely stored in a location known only to you and would have been generated when you created the API signing key.  To find out how to retrieve the fingerprint of the private key, see https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm#four
• Passphrase – If you have provided a password for your key then you must supply it to the SignatureProvider.

The code below is structured as follows:

1. The function getConnection – 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 createTable  – 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 writeARecord – This method will write a single record to the hello world table.
4. The method readARecord – 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.

package main

import (
	"encoding/json"
	"fmt"
	"os"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/auth/iam"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

// HelloWorldTableName is the nae of our table
const HelloWorldTableName = "hello_world"

func getConnection(compartment string,
	region string) (*nosqldb.Client, error) {

	tenancyOCID := "The OCI of you tenancy goes here"
	userOCID := "Your user OCID goes here"
	fingerprint := "The fingerprint for your key pair goes here"
	pathToPrivateKey := "I fully qualified path to your key file goes here"
	// If passphrase is not required, use an empty string
	privateKeyPassphrase := "The passphrase you used to create "

	sp, err := iam.NewRawSignatureProvider(tenancyOCID, userOCID,
		region, fingerprint, compartment, pathToPrivateKey,
		&privateKeyPassphrase)
	if err != nil {
		return nil, fmt.Errorf("cannot create a Signature Provider: %v", err)
	}

	reg, err := nosqldb.StringToRegion(region)

	cfg := nosqldb.Config{
		Mode:                  "cloud",
		Region:                reg,
		AuthorizationProvider: sp,
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		return nil, fmt.Errorf("failed to create a NoSQL client: %v", err)
	}
	return client, err

}

func createTable(handle *nosqldb.Client, tableName string) error {
	stmt := fmt.Sprintf("CREATE TABLE IF NOT EXISTS %s ("+
		"id LONG, "+
		"content JSON, "+
		"PRIMARY KEY(id))",
		tableName)

	tableReq := &nosqldb.TableRequest{
		Statement: stmt,
		TableLimits: &nosqldb.TableLimits{
			ReadUnits:  1,
			WriteUnits: 1,
			StorageGB:  1,
		},
	}
	tableRes, err := handle.DoTableRequest(tableReq)
	if err != nil {
		return fmt.Errorf("An error occurred while trying execute %s: %v",
			stmt, err)
	}

	// The create table request is asynchronous, wait for table
	// creation to complete.
	_, err = tableRes.WaitForCompletion(handle,
		60*time.Second, time.Second)

	if err != nil {
		return fmt.Errorf("Error finishing CREATE TABLE request: %v",
			err)
	}

	return nil
}

func writeARecord(handle *nosqldb.Client, tableName string,
	record types.MapValue) error {
	putReq := &nosqldb.PutRequest{
		TableName: tableName,
		Value:     &record,
	}

	_, err := handle.Put(putReq)
	if err != nil {
		return fmt.Errorf("Failed to put single row: %v", err)
	}
	return nil
}

func readARecord(handle *nosqldb.Client, key types.MapValue,
	tableName string) (*types.MapValue, error) {
	getReq := &nosqldb.GetRequest{
		TableName: tableName,
		Key:       &key,
	}
	result, err := handle.Get(getReq)
	if err != nil {
		return nil, fmt.Errorf("An error occurred while trying to read "+
			"record with PK %v.  Error = %v", key, err)
	}
	return result.Value, nil
}

func main() {
	handle, err := getConnection("Your compartment name goes here",
		"us-ashburn-1")
	if err != nil {
		fmt.Printf("%v\n", err)
		os.Exit(-1)
	}
	defer handle.Close()

	err = createTable(handle, HelloWorldTableName)
	if err != nil {
		fmt.Printf("%v\n", err)
		os.Exit(-1)
	}

	fmt.Println("Created table ", HelloWorldTableName)
	record, err := types.NewMapValueFromJSON(
		"{\"id\": 1, \"content\" : {\"hello\":\"world\"}}")
	if err != nil {
		fmt.Printf("%v\n", err)
		os.Exit(-1)
	}

	err = writeARecord(handle, HelloWorldTableName, *record)
	if err == nil {
		chars, err := json.Marshal(record.Map())
		if err == nil {
			fmt.Printf("Wrote the following record %s\n", chars)
		}
	} else {
		fmt.Printf("%v\n", err)
		os.Exit(-1)
	}

	key, err := types.NewMapValueFromJSON("{\"id\" : 1}")
	if err != nil {
		fmt.Printf("%v\n", err)
		os.Exit(-1)
	}

	record, err = readARecord(handle, *key, HelloWorldTableName)
	if err == nil {
		chars, err := json.Marshal(record.Map())
		if err == nil {
			fmt.Printf("Read the following record %s\n", chars)
		} else {
			fmt.Printf("An error occurred while trying convert the "+
				"record to JSON: %v\n", err)
		}
	} else {
		fmt.Printf("An error occurred while trying to read the record: %v\n",
			err)
	}
}

If you take the code above and place it in a file entitled HelloWorld.go 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 go run HelloWorld.go as specified below:

For more information about the Go SDK and pointers to more example code, take a look here https://github.com/oracle/nosql-go-sdk.

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 oraclenosql-info_ww@oracle.com with “Hello World – Go” in the subject line, and someone will get back to you as soon as possible.