oracle-nosql-rust-sdk

Oracle NoSQL Database Rust SDK

This is the Rust SDK for Oracle NoSQL Database. The SDK provides APIs and examples to help developers write Rust applications that connect to the Oracle NoSQL Database Cloud Service, the Oracle NoSQL Database on-premises server and to the Oracle NoSQL Cloud Simulator.

This SDK supplies and uses Rust async methods throughout. There is currently no blocking support.

The general flow for an application using the Oracle NoSQL Database is:

Create a [HandleBuilder] with all needed parameters
Create a [Handle] from the [HandleBuilder] that will be used throughout the application, across all threads
Interact with the NoSQL Database using the [Handle] and Request structs such as [GetRequest], [PutRequest], [QueryRequest], etc.

Simple Example

The following code creates a NoSQL [Handle] from values in the the current environment and then reads a single record from a table in the database. For a more complete example, see the Quickstart below.

use oracle_nosql_rust_sdk::{Handle, GetRequest};
use oracle_nosql_rust_sdk::types::MapValue;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let handle = Handle::builder()
        .from_environment()?
        .build().await?;
    let getres = GetRequest::new("test_table")
        .key(MapValue::new().i32("id", 10))
        .execute(&handle)
        .await?;
    println!("GetResult={:?}", getres);
    Ok(())
}

Prerequisites

Rust 1.78 or later
- Download and install a Rust binary release suitable for your system. See the install and setup instructions on that page.
Oracle NoSQL Database. Use one of the options:
- Subscribe to the Oracle NoSQL Database Cloud Service.
- Download the Oracle NoSQL Cloud Simulator.
- Download the Oracle NoSQL Database Server (on-premise) and the Oracle NoSQL Database Proxy (aka HTTP Proxy) at here. NOTE: The on-premise configuration requires a running instance of the HTTP Proxy, see the Oracle NoSQL Database Proxy and Driver for HTTP proxy configuration information.

Installation

The Rust SDK for Oracle NoSQL Database is published as a Rust crate. It is recommended to use the crates.io standard Rust mechanism for usage of this crate.

To do so, add the following dependency to your Cargo.toml file:

[dependencies]
oracle-nosql-rust-sdk = "0.1.0"

Configuring the SDK

This section describes configuring the SDK for the 3 environments supported:

NoSQL DB Cloud Service
Cloud Simulator
NoSQL DB On-Premise

The areas where the environments and use differ are:

Authentication and authorization.
- The Cloud Service is secure and requires a Cloud Service identity as well as authorization for desired operations.
- The Cloud Simulator is not secure at all and requires no identity.
- The On-Premises configuration can be either secure or not, and also requires an instance of the NoSQL DB Proxy service to access the on-premise database.
API differences. Some types and methods are specific to an environment. For example, the on-premise configuration includes methods to create namespaces and users and these concepts don’t exist in the cloud service. Similarly, the cloud service includes interfaces to specify and acquire throughput information on tables that is not relevant on-premise. Such differences are noted in the API documentation.

Before using the Cloud Service, it is recommended that users start with the Cloud Simulator to become familiar with the interfaces supported by the SDK.

Configure for the Cloud Service

The SDK requires an Oracle Cloud account and a subscription to the Oracle NoSQL Database Cloud Service. If you do not already have an Oracle Cloud account you can start here.

There are several ways of specifying the cloud service credentials to use, including:

Instance Principals
Resource Principals
User Config File

Using Instance Principal Credentials

Instance Principal is an IAM service feature that enables instances to be authorized actors (or principals) to perform actions on service resources. If the application is running on an OCI compute instance in the Oracle Cloud, the SDK can make use of the instance environment to determine its credentials (no config file is required). Each compute instance has its own identity, and it authenticates using the certificates that are added to it. See Calling Services from an Instance for prerequisite steps to set up Instance Principal.

To configure NoSQL in this mode, use the [HandleBuilder::cloud_auth_from_instance()] method on the config struct.

Using Resource Principal Credentials

Resource Principal is an IAM service feature that enables the resources to be authorized actors (or principals) to perform actions on service resources. You may use Resource Principal when calling Oracle NoSQL Database Cloud Service from other Oracle Cloud service resource such as Functions. See Accessing Other Oracle Cloud Infrastructure Resources from Running Functions for how to set up Resource Principal.

To configure NoSQL in this mode, use the [HandleBuilder::cloud_auth_from_resource()] method on the config struct.

Using User Config File to Specify OCI Credentials

Several pieces of information comprise your credentials used by the Oracle NoSQL Database Cloud Service:

Tenancy ID
User ID
Fingerprint
Private Key File
Passphrase (optional)
Region (optional)

Information about how to acquire this information is found in the Required Keys and OCIDs page. Specifically, these topics can be found on that page:

The way to supply the credentials is to use a credentials file, which by default is found in $HOME/.oci/config but the location can be specified in the API calls (see below).

The format of the file is that of a properties file with the format of key=value, with one property per line. The contents and format are:

[DEFAULT]
tenancy=<your-tenancy-id>
user=<your-user-id>
fingerprint=<fingerprint-of-your-public-key>
key_file=<path-to-your-private-key-file>
pass_phrase=<optional-passphrase>
region=<optional-region-identifier>

Details of the configuration file can be found on the SDK and Configuration File page. Note that multiple profiles can exist (using the [PROFILENAME] properties file convention) and can be selected using the API (see example below).

The Tenancy ID, User ID and fingerprint should be acquired using the instructions above. The path to your private key file is the absolute path of the RSA private key. The order of the properties does not matter.

The region is only required if [HandleBuilder::cloud_region()] is not used. It should specify the region of the NoSQL cloud service you are connecting to (for example: us-phoenix-1). For more information on regions, see Regions and Availability Domains.

The pass_phrase is only required if the RSA key file itself requires a passphrase.

Using the Config to Connect an Application to the Cloud Service

The first step in any Oracle NoSQL Database Cloud Service rust application is to create a [Handle] used to send requests to the service, based on the configuration given in a [HandleBuilder] struct. Instances of the Handle are safe for concurrent use by multiple goroutines and intended to be shared in a multi-threaded / async application.

The following code example shows how to connect to the cloud service, using a user config file:

    let handle = Handle::builder()
	    .cloud_auth_from_file("~/.oci/config")?
        .build().await?;
    // use handle for all NoSQL DB operations
    // ...

Configure for the Cloud Simulator

The Oracle NoSQL Cloud Simulator is a useful way to use this SDK to connect to a local server that supports the same protocol.

See Download the Oracle NoSQL Cloud Simulator to download and start the Cloud Simulator.

The Cloud Simulator should not be used for deploying production applications or important data, but it does allow for rapid development and testing.

The Cloud Simulator does not require the credentials and authentication information required by the Oracle NoSQL Database Cloud Service, but the SDK does require an endpoint and the auth mode specifying Cloudsim:

    let handle = Handle::builder()
	    .mode(HandleMode::Cloudsim)?
	    .endpoint("http://localhost:8080")?
        .build().await?;
    // use handle for all NoSQL DB operations
    // ...

Configure for the On-Premise Oracle NoSQL Database

The on-premise configuration requires a running instance of the Oracle NoSQL database. In addition a running proxy service is required. See Oracle NoSQL Database Downloads for downloads, and see Information about the proxy for proxy configuration information.

In this case, the endpoint config parameter should point to the NoSQL proxy host and port location.

If running a secure store, a user identity must be created in the store (separately) that has permission to perform the required operations of the application, such as manipulating tables and data. If the secure server has installed a certificate that is self-signed or is not trusted by the default system CA, specify [HandleBuilder::danger_accept_invalid_certs()] to instruct the client to skip verifying server's certificate, or specify the [HandleBuilder::add_cert_from_pemfile()] to verify server's certificate.

    let handle = Handle::builder()
       .endpoint("https://nosql.mycompany.com:8080")?
       .onprem_auth("testUser", "12345")?
       .danger_accept_invalid_certs(true)?
       // alternatively, specify a cert path
       // .add_cert_from_pemfile("/path/to/pemfile.pem")?
       .build().await?;

    // use handle for all NoSQL DB operations
    // ...

If the store is not secure then the username and password are not required, but the mode is still required to differentiate between onprem and cloudsim installations:

    let handle = Handle::builder()
        .mode(HandleMode::Onprem)?
        .endpoint("http://nosql.mycompany.com:8080")?
        .build().await?;
    // use handle for all NoSQL DB operations
    // ...

Quickstart

Below is a complete simple example program that opens a NoSQLDB handle, creates a simple table if it does not already exist, puts, gets, and deletes a row, then drops the table.

The quickstart program can be used as a template which you can copy and modify as desired:

use oracle_nosql_rust_sdk::types::*;
use oracle_nosql_rust_sdk::DeleteRequest;
use oracle_nosql_rust_sdk::GetRequest;
use oracle_nosql_rust_sdk::Handle;
use oracle_nosql_rust_sdk::HandleMode;
use oracle_nosql_rust_sdk::NoSQLError;
use oracle_nosql_rust_sdk::PutRequest;
use oracle_nosql_rust_sdk::QueryRequest;
use oracle_nosql_rust_sdk::TableRequest;
use std::error::Error;
use std::time::Duration;
use tracing::info;

// This method shows various ways to configure a NoSQL Handle.
async fn get_handle() -> Result<Handle, NoSQLError> {
    // Note: later methods called on this builder will override earlier methods.
    // This allows for setting desired defaults that can be overridden by, for example,
    // .from_environment().
    Handle::builder()
        // For local cloudsim: endpoint, Cloudsim mode:
        .endpoint("http://localhost:8080")?
        .mode(HandleMode::Cloudsim)?
        //
        // For on-premises: endpoint, Onprem mode:
        // .endpoint("https://my.company.com:8080")?
        // .mode(HandleMode::Onprem)?
        // Optional file with onprem secure login credentials
        // .onprem_auth_from_file("/path/to/user_pass_file")?
        // Optional path to x509 certificate in PEM format
        // .onprem_auth_from_file("/path/to/certificate.pem")?
        //
        // For cloud, using user-based file:
        // .cloud_auth_from_file("~/.oci/config")?
        // Optional region, if not specified in above file
        // .cloud_region("us-ashburn-1")?
        // Optional full endpoint, if region is not recognized
        //.endpoint("https://nosql.us-unknown-1.oci.oraclecloud.com")?
        //
        // For cloud, using Instance Principal:
        // .cloud_auth_from_instance()?
        //
        // For cloud, using Resource Principal:
        // .cloud_auth_from_resource()?
        //
        // To read all of the above from environment variables:
        .from_environment()?
        //
        // Optional: set a different default timeout (default is 30 seconds)
        .timeout(Duration::from_secs(15))?
        //
        // Build the handle
        .build()
        .await
}

// Example way to use multiple threaded tokio runtime
#[tokio::main(flavor = "multi_thread", worker_threads = 4)]
async fn main() -> Result<(), Box<dyn Error>> {
    // Set up a tracing subscriber to see output based on RUST_LOG environment setting
    tracing_subscriber::fmt()
        .with_env_filter(tracing_subscriber::filter::EnvFilter::from_default_env())
        .compact()
        .init();

    // Create a handle. This should be used throughout the program, across all threads
    info!("Creating new handle...");
    let handle = get_handle().await?;

    // Create an example table
    TableRequest::new("testusers")
        .statement(
            "create table if not exists testusers (id integer, name string,
            created timestamp(3), primary key(id))",
        )
        // the following line is only needed for Cloud mode
        .limits(&TableLimits::provisioned(1000, 1000, 10))
        .execute(&handle)
        .await?
        // wait up to 15 seconds for table to be created
        .wait_for_completion_ms(&handle, 15000, 500)
        .await?;

    // Put a record into the table
    // Note: ttl is a Duration, but internally is converted to a whole number of
    // hours or days. Minimum duration is one hour.
    let putres = PutRequest::new("testusers")
        .timeout(&Duration::from_millis(3000))
        .value(MapValue::new().i32("id", 10).str("name", "jane"))
        .ttl(&Duration::new(7200, 0))
        .execute(&handle)
        .await?;
    println!("PutResult={:?}", putres);
    // PutResult should have a version
    if putres.version().is_none() {
        return Err("PutRequest should have returned a version, but did not".into());
    }

    // Example of using if_version to overwrite existing record
    let putreq2 = PutRequest::new("testusers")
        .timeout(&Duration::from_millis(3000))
        .value(MapValue::new().i32("id", 10).str("name", "john"))
        .if_version(&putres.version().unwrap())
        .ttl(&Duration::new(7200, 0));
    println!("Putreq2={:?}", putreq2);
    let putres2 = putreq2.execute(&handle).await?;
    println!("PutResult2={:?}", putres2);

    // Get the record back
    let getres = GetRequest::new("testusers")
        .key(MapValue::new().i32("id", 10))
        .consistency(Consistency::Eventual)
        .execute(&handle)
        .await?;
    println!("GetResult={:?}", getres);
    // GetResult should have a version
    if getres.version().is_none() {
        return Err("GetRequest should have returned a version, but did not".into());
    }

    // write in some more records, so query below has more to return
    for i in 20..30 {
        //let name = format!("name{}", i);
        let name = "somename".to_string();
        let _ = PutRequest::new("testusers")
            .value(
                MapValue::new()
                    .i32("id", i)
                    .str("name", name.as_str()),
            )
            .execute(&handle)
            .await?;
        // Optional delay between puts, if desired
        // tokio::time::sleep(std::time::Duration::from_millis(1000)).await;
    }

    // Simple query of all rows
    let qres = QueryRequest::new("select * from testusers")
        .execute(&handle)
        .await?;
    println!("QueryResult = {:?}", qres);

    // Query with ordering
    let qres1 = QueryRequest::new("select * from testusers order by id")
        .execute(&handle)
        .await?;
    println!("QueryResult1 = {:?}", qres1);

    // Example of how to remove a record with if_version
    let delres = DeleteRequest::new("testusers", MapValue::new().i32("id", 10))
        .if_version(&getres.version().unwrap())
        .execute(&handle)
        .await?;
    println!("delres={:?}", delres);

    // Drop the table
    TableRequest::new("testusers")
        .statement("drop table if exists testusers")
        .execute(&handle)
        .await?
        .wait_for_completion_ms(&handle, 15000, 500)
        .await?;

    Ok(())
}

Create a directory quickstart and quickstart/src, save the example program as main.rs in the quickstart/src directory.

Add a Cargo.toml file to the quickstart directory:

[package]
name = "quickstart"
version = "0.1.0"
edition = "2021"

[dependencies]
tokio = { version = "1.38.0", features = ["full"] }
chrono = { version = "0.4.31", features = ["alloc", "std"] }
oracle-nosql-rust-sdk = { version = "0.1" }
tracing = "0.1.40"
tracing-subscriber =  { version = "0.3", features = ["env-filter", "std"] }

Run the example program with the commands:

cd quickstart

cargo build

cargo run

Examples

Examples can be found at the examples directory. Examples include simple, standalone programs that show the Rust API usages. They include comments about how they can be configured and run in the different supported environments.

Help

There are a few ways to get help or report issues:

Open an issue in the Issues page.
Post your question on the Oracle NoSQL Database Community.
Email to [email protected]

When requesting help please be sure to include as much detail as possible, including version of the SDK and simple, standalone example code as needed.

Changes

See the Changelog.

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide

Security

Please consult the security guide for our responsible security vulnerability disclosure process

License

This SDK is licensed under the Universal Permissive License 1.0. See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
examples		examples
oracle-nosql-rust-sdk-derive		oracle-nosql-rust-sdk-derive
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.toml		Cargo.toml
LICENSE.txt		LICENSE.txt
README.md		README.md
SECURITY.md		SECURITY.md
THIRD_PARTY_LICENSES.txt		THIRD_PARTY_LICENSES.txt
build.rs		build.rs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

oracle-nosql-rust-sdk

Simple Example

Prerequisites

Installation

Configuring the SDK

Configure for the Cloud Service

Using Instance Principal Credentials

Using Resource Principal Credentials

Using User Config File to Specify OCI Credentials

Using the Config to Connect an Application to the Cloud Service

Configure for the Cloud Simulator

Configure for the On-Premise Oracle NoSQL Database

Quickstart

Examples

Help

Changes

Contributing

Security

License

About

Releases

Contributors 2

Languages

License

oracle/nosql-rust-sdk

Folders and files

Latest commit

History

Repository files navigation

oracle-nosql-rust-sdk

Simple Example

Prerequisites

Installation

Configuring the SDK

Configure for the Cloud Service

Using Instance Principal Credentials

Using Resource Principal Credentials

Using User Config File to Specify OCI Credentials

Using the Config to Connect an Application to the Cloud Service

Configure for the Cloud Simulator

Configure for the On-Premise Oracle NoSQL Database

Quickstart

Examples

Help

Changes

Contributing

Security

License

About

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

Contributors 2

Languages