Crate qldb

source ·
Expand description

Amazon’s QLDB Driver

Driver for Amazon’s QLDB Database implemented in pure rust.

Documentation Crates.io Rust

The driver is fairly tested and should be ready to test in real projects.

Example

use qldb::QldbClient;
use std::collections::HashMap;

let client = QldbClient::default("rust-crate-test", 200).await?;

let mut value_to_insert = HashMap::new();
// This will insert a documents with a key "test_column"
// with the value "IonValue::String(test_value)"
value_to_insert.insert("test_column", "test_value");

client
    .transaction_within(|client| async move {   
        client
            .query("INSERT INTO TestTable VALUE ?")
            .param(value_to_insert)
            .execute()
            .await?;
        Ok(())
    })
    .await?;

Session Pool

The driver has a session pool. The second parameter in the QldbClient::default is the maximum size of the connection pool.

The pool will be auto-populated as parallel transaction are being requested until it reaches the provided maximum.

The pool uses one independent thread with a single-threaded executor (async-executor) in order to be able to spawn tasks after the session has been returned.

Alternative session Pool

There is an alternative session pool that will require an spawner function to be provided. It allows to have the pool running by using the spawn function of the executor you use. We tested async-std and tokio, but others should work as well.

This pool will spawn two internal tasks handling the pool.

Use this if you want for this driver to not create a new thread.

Example with async-std:

use qldb::QldbClient;
use std::sync::Arc;

    let client = QldbClient::default_with_spawner(
        "rust-crate-test",
        200,
        Arc::new(move |fut| {async_std::task::spawn(Box::pin(fut));})
    )
    .await?;

Or, with tokio:

use qldb::QldbClient;
use std::sync::Arc;

    let client = QldbClient::default_with_spawner(
        "rust-crate-test",
        200,
        Arc::new(move |fut| {tokio::spawn(Box::pin(fut));})
    )
    .await?;

Select the pool you want to use

By default, both pools are available by using the methods QldbClient::default and QldbClient::default_with_spawner. If you don’t want the pool to be available in runtime, you can disable by removing the default features. Still, you will need to add at least one feature to enable one pool.

This will only enable the default pool, the one that uses one thread.

qldb = { version = "3", default_features = false, features = ["internal_pool_with_thread"]}

This will only enable the alternative pool, the one that requires an spawner

qldb = { version = "3", default_features = false, features = ["internal_pool_with_spawner"]}

Underlying Ion Format Implementation

The library uses ion-binary-rs, which is our own, pure rust, implementation of the format. It is very well tested and ready to use in production too.

Test

For tests you will need to have some AWS credentials in your PC (as env variables or in ~/.aws/credentials). There needs to be a QLDB database with the name “rust-crate-test” in the aws account. The tests need to be run sequentially, so in order to run the tests please run the following command:

RUST_TEST_THREADS=1 cargo test

Re-exports

Structs

  • Cursor
    Cursor allows to get all values from a statement page by page.
  • Document
    It contains the IonValue representing the QLDB Document.
  • DocumentCollection
    Represents a collection of documents. It implements so you can call in order to use it in for loops or with .
  • QldbClient
    It allows to start transactions. In QLDB all queries are transactions. So you always need to create a transaction for every query.
  • QueryBuilder
    Represents the query being built. It allows to add parameters and to execute the query.
  • Transaction
    Every query in QLDB is within a transaction. Ideally you will interact with this object via the method QLDBClient::transaction_within.

Enums

Type Aliases