1 unstable release
0.3.0 | Oct 14, 2024 |
---|
#372 in Asynchronous
180 downloads per month
29KB
563 lines
Asynchronous Database Pool Connection Library
This library provides the connection logic to support using SurrealDB v2+ with the asynchronous 'bb8' connection pool library. It supports feature flags to enable easier cross-platform development and testing. By default the library will use the memory storage engine, but it can be configured to use many other SurrealDB storage engine types.
Usage
To use this library, add the following to your Cargo.toml
file:
[dependencies]
async-trait = "0.1"
bb8 = "0.8.5"
bb8_surrealdb2 = "0.3"
serde = { version = "1.0.210", features = ["derive"] }
surreal_db = "2.0"
tokio = { version = "1.40.0", features = [
"macros",
"rt-multi-thread",
"test-util",
] }
Within the code, you can use the library as follows:
// Hold a single reference to the pool for all test cases to run in parallel.
static POOL: OnceCell<Arc<Pool<ConnectionManager>>> = OnceCell::const_new();
// Initialize the pool with a memory database.
async fn init_pool() -> Result<Arc<Pool<ConnectionManager>>, Box<dyn Error>> {
// Use whichever settings you need for your database.
let settings = DatabaseSettings::new_memory_db("test".to_string(), "test".to_string());
let manager = ConnectionManager::new(settings);
// Set the maximum pool size to whatever you need.
// Memory databases are single-threaded, so limit the pool size to 1 in this case.
let pool = Pool::builder().max_size(1).build(manager).await?;
Ok(Arc::new(pool))
}
/// Create a pool if it doesn't already exist and return a reference.
pub async fn get_pool() -> Result<Arc<Pool<ConnectionManager>>, Box<dyn Error>> {
POOL.get_or_try_init(init_pool)
.await
.map(|pool| pool.clone())
}
// Everywhere you need to use the pool, you can get a connection reference to it like this:
let pool = get_pool().await?;
let connection = pool.get().await?;
// or even better, use a match case to handle potential errors:
match get_pool().await {
Ok(pool) => match pool.get().await {
Ok(mut conn) => {
// Do something with the connection.
}
Err(e) => {
// Handle the error.
}
}
Err(e) => {
// Handle the error.
}
}
Example
There are two examples provided in the examples
directory. The first example demonstrates how to use the library
with a local SurrealDB v2 instance. The second example demonstrates how to use the library with web base applications.
to run these examples, use the following command:
cargo test -- --nocapture
License
Licensed under the MIT license (LICENSE).
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you shall be licensed as above, without any additional terms or conditions.
Dependencies
~60–82MB
~1.5M SLoC