diff --git a/libtransact/src/state/merkle/sql/backend/mod.rs b/libtransact/src/state/merkle/sql/backend/mod.rs index afaebc77..b80216dc 100644 --- a/libtransact/src/state/merkle/sql/backend/mod.rs +++ b/libtransact/src/state/merkle/sql/backend/mod.rs @@ -15,6 +15,10 @@ * ----------------------------------------------------------------------------- */ +//! Database Backends +//! +//! A Backend provides a light-weight abstraction over database connections. + #[cfg(feature = "postgres")] pub(in crate::state::merkle::sql) mod postgres; #[cfg(feature = "sqlite")] @@ -29,14 +33,22 @@ pub use postgres::{PostgresBackend, PostgresBackendBuilder, PostgresConnection}; #[cfg(feature = "sqlite")] pub use sqlite::{JournalMode, SqliteBackend, SqliteBackendBuilder, SqliteConnection, Synchronous}; +/// A database connection. pub trait Connection { + /// The underlying internal connection. type ConnectionType: diesel::Connection; + /// Access the internal connection. fn as_inner(&self) -> &Self::ConnectionType; } +/// A database backend. +/// +/// A Backend provides a light-weight abstraction over database connections. pub trait Backend: Sync + Send { + /// The database connection. type Connection: Connection; + /// Acquire a database connection. fn connection(&self) -> Result; } diff --git a/libtransact/src/state/merkle/sql/backend/postgres.rs b/libtransact/src/state/merkle/sql/backend/postgres.rs index 9574281f..e0400073 100644 --- a/libtransact/src/state/merkle/sql/backend/postgres.rs +++ b/libtransact/src/state/merkle/sql/backend/postgres.rs @@ -15,12 +15,19 @@ * ----------------------------------------------------------------------------- */ +//! Postgres Database Backend +//! +//! Available if the feature "postgres" is enabled. + use diesel::r2d2::{ConnectionManager, Pool, PooledConnection}; use crate::error::{InternalError, InvalidStateError}; use super::{Backend, Connection}; +/// A connection to a Postgres database. +/// +/// Available if the feature "postgres" is enabled. pub struct PostgresConnection( pub(in crate::state::merkle::sql) PooledConnection>, ); @@ -35,7 +42,9 @@ impl Connection for PostgresConnection { /// The Postgres Backend /// -/// This struct provides the backend implementation details for postgres databases. +/// This struct provides the [Backend] implementation details for Postgres databases. +/// +/// Available if the feature "postgres" is enabled. #[derive(Clone)] pub struct PostgresBackend { connection_pool: Pool>, @@ -61,6 +70,8 @@ impl From>> for PostgresBackend } /// A Builder for the PostgresBackend. +/// +/// Available if the feature "postgres" is enabled. #[derive(Default)] pub struct PostgresBackendBuilder { url: Option, diff --git a/libtransact/src/state/merkle/sql/backend/sqlite.rs b/libtransact/src/state/merkle/sql/backend/sqlite.rs index c216d64d..190713c5 100644 --- a/libtransact/src/state/merkle/sql/backend/sqlite.rs +++ b/libtransact/src/state/merkle/sql/backend/sqlite.rs @@ -16,6 +16,8 @@ */ //! A Backend implementation for SQLite databases. +//! +//! Available if the feature "sqlite" is enabled. use std::convert::TryFrom; use std::fmt; @@ -32,6 +34,8 @@ use crate::error::{InternalError, InvalidStateError}; use super::{Backend, Connection}; /// A connection to a SQLite database. +/// +/// Available if the feature "sqlite" is enabled. pub struct SqliteConnection( pub(in crate::state::merkle::sql) PooledConnection>, ); @@ -47,6 +51,8 @@ impl Connection for SqliteConnection { /// The SQLite Backend /// /// This struct provides the backend implementation details for SQLite databases. +/// +/// Available if the feature "sqlite" is enabled. #[derive(Clone)] pub struct SqliteBackend { connection_pool: Pool>, @@ -78,6 +84,8 @@ pub const DEFAULT_MMAP_SIZE: i64 = 100 * 1024 * 1024; /// /// See the [PRAGMA "synchronous"](https://sqlite.org/pragma.html#pragma_journal_mode) /// documentation for more details. +/// +/// Available if the feature "sqlite" is enabled. #[derive(Debug)] pub enum Synchronous { /// With synchronous Off, SQLite continues without syncing as soon as it has handed data @@ -118,6 +126,8 @@ impl fmt::Display for Synchronous { /// /// See the [PRAGMA "journal_mode"](https://sqlite.org/pragma.html#pragma_journal_mode) /// documentation for more details. +/// +/// Available if the feature "sqlite" is enabled. #[derive(Debug)] pub enum JournalMode { /// The DELETE journaling mode is the normal behavior. In the DELETE mode, the rollback journal @@ -159,6 +169,9 @@ impl fmt::Display for JournalMode { } } +/// A builder for a [SqliteBackend]. +/// +/// Available if the feature "sqlite" is enabled. pub struct SqliteBackendBuilder { connection_path: Option, create: bool, @@ -181,14 +194,15 @@ impl SqliteBackendBuilder { } } - /// Configures the SqliteBackend instance as a memory database, with a connection pool size of 1. + /// Configures the [SqliteBackend] instance as a memory database, with a connection pool size of + /// 1. pub fn with_memory_database(mut self) -> Self { self.connection_path = Some(":memory:".into()); self.pool_size = Some(1); self } - /// Set the path for the Sqlite database. + /// Set the path for the SQLite database. /// /// This is a required field. pub fn with_connection_path>(mut self, connection_path: S) -> Self { @@ -210,7 +224,7 @@ impl SqliteBackendBuilder { /// Set the size used for Memory-Mapped I/O. /// - /// This can be disabled by setting the value to `0` + /// This can be disabled by setting the value to `0`. pub fn with_memory_map_size(mut self, memory_map_size: u64) -> Self { // The try from would fail if the u64 is greater than max i64, so we can unwrap this as // such. diff --git a/libtransact/src/state/merkle/sql/mod.rs b/libtransact/src/state/merkle/sql/mod.rs index e1163145..d98e9a54 100644 --- a/libtransact/src/state/merkle/sql/mod.rs +++ b/libtransact/src/state/merkle/sql/mod.rs @@ -45,6 +45,8 @@ //! //! The resulting `merkle_state` can then be used via the [`Read`], [`Write`] and //! [`MerkleRadixLeafReader`] traits. +//! +//! Available if the feature "state-merkle-sql" is enabled. pub mod backend; mod error;