Getting Started with the Go OJAI Client

This section describes the software required to run the Go OJAI client, client/server security, and how to specify your connection string. It also provides links to documentation that shows you how to write Go OJAI applications.

The Go OJAI client is available starting in the EEP 6.0.0 release.

Software Requirements

You must have the following software installed to run the client:

Client Software	Installation Notes
Golang 1.10 (or later)
Go OJAI client	Install the client using the following command: `go get github.com/mapr/maprdb-go-client`

You also must have access to the following software:

Data-fabric cluster 6.1 or later
MapR Data Access Gateway 2.0 or later

To run a Go OJAI application, you must install and configure the Data Access Gateway:

For some sample code, see https://github.com/magpierre/mapr_go_client_mqtt. main.go shows a simple Go client that reads from an MQTT messaging protocol and writes to a data-fabric JSON database.

Go OJAI Client Security

The client supports username/password authentication. The initial connection (and token renewal) use these credentials. Subsequent communication uses JWT.

When connecting to a secure MapR cluster, the client uses:

X.509 certificates to authenticate with the MapR Data Access Gateway
TLS v1.2 to encrypt communication between the client and the Data Access Gateway

Go OJAI Client Connection String

The string you use to connect your OJAI client to the cluster must have the following format:

"[ojai:mapr:thin:v1@]<hostname>[:<port>][?<option_name>=<option_value>;...]"

The prefix ojai:mapr:thin:v1@ is optional.

<hostname>: Name of the MapR Data Access Gateway host
<port>: Port number (see Ports Used by MapR Data Platform Software) that gRPC clients use to connect to the MapR Data Access Gateway
Default: 5678

auth=<scheme_name>

The authentication scheme for the current connection; currently, only basic

user=<username>

The user name for basic authentication

password=<password>

The password for basic authentication

ssl=true|false

Whether to establish a secure connection using SSL/TLS

An error is returned if there is a mismatch between your client and Data Access Gateway security settings. The default for this option is true, which is the required setting if connecting to a secure Data Access Gateway. If connecting to a nonsecure Data Access Gateway, set it to false.

If set to false, the other SSL parameters are ignored.

Note that the grpc.service.ssl.enabled property controls the SSL setting for the Data Access Gateway. For more information, see Administering the MapR Data Access Gateway.

sslCA=<path to PEM file containing CA certificate>

Path to a local file containing Certificate Authority (CA) signed certificates in PEM format. For information about the PEM format, see Configuring SSL for OJAI Clients.

Must be set if the ssl option is true.

sslTargetNameOverride=<CA certificate common name>

Fully qualified domain name specified in the SSL server certificate, which is different from the <hostname> in the connection string.

For example, imagine that you are using the following:

Public network host name is ec2-203-0-113-25.compute-1.amazonaws.com.
Internal DNS is node1.mydomain.com.
CA signed certificate is issued to node1.mydomain.com.

Using these names, you must specify the following connection string:

"ec2-203-0-113-25.compute-1.amazonaws.com:5678?ssl=true;sslCA=/opt/app/conf/rootca.pem;sslTargetNameOverride=node1.mydomain.com"

Other examples of connection strings are the following:

"ojai:mapr:thin:v1@localhost:5678?auth=basic;user=fred;password=george;sslCA=/opt/app/conf/rootca.pem"
"localhost:5678?ssl=false;auth=basic;user=fred;password=george"

sslValidate=true|false

When ssl=true, indicates whether or not the client should validate the server certificate against a list of CA certificates. The default is true.

Go OJAI Connection Retry Options

If your OJAI client cannot connect to your data-fabric cluster, it waits 10 ms. After 10 ms, it makes a second connection attempt. If that fails, it continues the attempts up to a configurable number of retries. The following parameters control the number of retries and the wait time between attempts:

Connection Option Parameter	Description	Default Value
`MaxAttempt`	Maximum number of retry attempts	9
`WaitBetweenSeconds`	Maximum wait time between attempts	12 s
`CallTimeoutSeconds`	Maximum call timeout	60 s

To set these retry options, you must pass them in the client.MakeConnectionWithRetryOptions call:

	connectionString := "localhost:5678?" +
		"auth=basic;" +
		"user=mapr;" +
		"password=mapr;" +
		"ssl=true;" +
		"sslCA=/opt/mapr/conf/ssl_truststore.pem;" +
		"sslTargetNameOverride=node1.cluster.com"
	options := &client.ConnectionOptions{MaxAttempt:3, WaitBetweenSeconds:10, CallTimeoutSeconds:60}
	connection, _ := client.MakeConnectionWithRetryOptions(connectionString, options)

Writing a Go OJAI Application

For information about writing a Go OJAI application, see the Go sections in the following topics:

Querying in OJAI Applications: Provides an introduction to the basic flow of an OJAI application that queries a MapR Database JSON table
Examples: Querying JSON Documents: Contains code samples of OJAI applications that query MapR Database JSON tables
Managing JSON Documents: Describes how to perform CRUD (create, query, update, and delete) operations on JSON documents in MapR Database JSON tables