qldb/
lib.rs

1//! # Amazon's QLDB Driver
2//!
3//! Driver for Amazon's QLDB Database implemented in pure rust.
4//!
5//! [![Documentation](https://docs.rs/qldb/badge.svg)](https://docs.rs/qldb)
6//! [![Crates.io](https://img.shields.io/crates/v/qldb)](https://crates.io/crates/qldb)
7//! [![Rust](https://github.com/Couragium/qldb-rs/actions/workflows/rust.yml/badge.svg)](https://github.com/Couragium/qldb-rs/actions/workflows/rust.yml)
8//!
9//! The driver is fairly tested and should be ready to test in real projects.
10//!
11//! ## Example
12//!
13//! ```rust,no_run
14//! use qldb::QldbClient;
15//! use std::collections::HashMap;
16//! # use eyre::Result;
17//!
18//! # async fn test() -> Result<()> {
19//! let client = QldbClient::default("rust-crate-test", 200).await?;
20//!
21//! let mut value_to_insert = HashMap::new();
22//! // This will insert a documents with a key "test_column"
23//! // with the value "IonValue::String(test_value)"
24//! value_to_insert.insert("test_column", "test_value");
25//!
26//! client
27//!     .transaction_within(|client| async move {   
28//!         client
29//!             .query("INSERT INTO TestTable VALUE ?")
30//!             .param(value_to_insert)
31//!             .execute()
32//!             .await?;
33//!         Ok(())
34//!     })
35//!     .await?;
36//! # Ok(())
37//! # }
38//! ```
39//!
40//! # Session Pool
41//!
42//! The driver has a session pool. The second parameter in the
43//! QldbClient::default is the maximum size of the connection pool.
44//!
45//! The pool will be auto-populated as parallel transaction are being
46//! requested until it reaches the provided maximum.
47//!
48//! The pool uses one independent thread with a single-threaded
49//! executor ([async-executor](https://crates.io/crates/async-executor))
50//! in order to be able to spawn tasks after the session has been returned.
51//!
52//! ## Alternative session Pool
53//!
54//! There is an alternative session pool that will require an spawner
55//! function to be provided. It allows to have the pool running by using
56//! the spawn function of the executor you use. We tested async-std and
57//! tokio, but others should work as well.
58//!
59//! This pool will spawn two internal tasks handling the pool.
60//!
61//! Use this if you want for this driver to not create a new thread.
62//!
63//! Example with async-std:
64//!
65//! ```rust,no_run
66//! use qldb::QldbClient;
67//! use std::sync::Arc;
68//! # use eyre::Result;
69//!
70//! # async fn test() -> Result<()> {
71//!     let client = QldbClient::default_with_spawner(
72//!         "rust-crate-test",
73//!         200,
74//!         Arc::new(move |fut| {async_std::task::spawn(Box::pin(fut));})
75//!     )
76//!     .await?;
77//! # Ok(())
78//! # }
79//! ```
80//!
81//! Or, with tokio:
82//!
83//! ```rust,no_run
84//! use qldb::QldbClient;
85//! use std::sync::Arc;
86//! # use eyre::Result;
87//!
88//! # async fn test() -> Result<()> {
89//!     let client = QldbClient::default_with_spawner(
90//!         "rust-crate-test",
91//!         200,
92//!         Arc::new(move |fut| {tokio::spawn(Box::pin(fut));})
93//!     )
94//!     .await?;
95//! # Ok(())
96//! # }
97//! ```
98//!
99//! ## Select the pool you want to use
100//!
101//! By default, both pools are available by using the methods `QldbClient::default`
102//! and `QldbClient::default_with_spawner`. If you don't want the pool to be available
103//! in runtime, you can disable by removing the default features. Still, you will
104//! need to add at least one feature to enable one pool.
105//!
106//! This will only enable the default pool, the one that uses one thread.
107//! ```toml,no_code
108//! qldb = { version = "3", default_features = false, features = ["internal_pool_with_thread"]}
109//! ```
110//!
111//! This will only enable the alternative pool, the one that requires an spawner
112//! ```toml,no_code
113//! qldb = { version = "3", default_features = false, features = ["internal_pool_with_spawner"]}
114//! ```
115//!
116//! # Underlying Ion Format Implementation
117//!
118//! The library uses [ion-binary-rs](https://crates.io/crates/ion-binary-rs),
119//! which is our own, pure rust, implementation of the format. It is very
120//! well tested and ready to use in production too.
121//!
122//! # Test
123//!
124//! For tests you will need to have some AWS credentials in your
125//! PC (as env variables or in ~/.aws/credentials). There needs
126//! to be a QLDB database with the name "rust-crate-test" in the
127//! aws account. The tests need to be run sequentially, so in order
128//! to run the tests please run the following command:
129//!
130//! ```sh
131//! RUST_TEST_THREADS=1 cargo test
132//! ```
133
134mod client;
135mod cursor;
136mod document;
137mod document_collection;
138mod query_builder;
139mod session_pool;
140mod transaction;
141mod types;
142
143pub use client::QldbClient;
144pub use cursor::Cursor;
145pub use document::Document;
146pub use document_collection::DocumentCollection;
147pub use ion_binary_rs as ion;
148pub use query_builder::QueryBuilder;
149pub use rusoto_core::Region;
150pub use transaction::Transaction;
151pub use types::{QldbError, QldbResult};
152pub use types::{QldbExtractError, QldbExtractResult};
qldb/lib.rs

qldb/
lib.rs
