oxisql_core/
pool.rs

1//! Connection pool trait for OxiSQL backends.
2
3use async_trait::async_trait;
4
5use crate::{Connection, OxiSqlError};
6
7/// A pool of database connections.
8///
9/// Implementors manage a bounded set of backend connections and hand them
10/// out to callers on demand.  When the returned [`Box<dyn Connection>`] is
11/// dropped, the underlying connection is returned to the pool automatically
12/// (handled by each backend's pool implementation).
13///
14/// The trait is object-safe: `Box<dyn ConnectionPool>` is a valid type.
15#[async_trait]
16pub trait ConnectionPool: Send + Sync {
17    /// Check out a connection from the pool.
18    ///
19    /// Blocks until a connection is available or returns an error if the
20    /// pool is exhausted / timed out.
21    async fn get(&self) -> Result<Box<dyn Connection + Send>, OxiSqlError>;
22
23    /// Maximum number of connections the pool will hold.
24    fn pool_size(&self) -> usize;
25
26    /// Number of connections currently idle (available for checkout).
27    fn idle_count(&self) -> usize;
28
29    /// Number of connections currently checked out (active).
30    fn active_count(&self) -> usize;
31
32    /// Verify that the pool is healthy by probing the backend.
33    ///
34    /// For RDBMS backends this typically executes `SELECT 1` on an idle
35    /// connection.  For in-memory backends it is a no-op.
36    async fn health_check(&self) -> Result<(), OxiSqlError>;
37
38    /// Drain all idle connections and prevent new checkouts.
39    ///
40    /// Active (checked-out) connections are allowed to finish normally;
41    /// they are closed when returned to the pool after this call.
42    async fn close(&self);
43}
44
45// ── Tests ────────────────────────────────────────────────────────────────────
46
47#[cfg(test)]
48mod tests {
49    use super::*;
50
51    /// Compile-time assertion that `ConnectionPool` is object-safe.
52    ///
53    /// If this function compiles, `dyn ConnectionPool` is a valid type.
54    fn _assert_object_safe(_p: &dyn ConnectionPool) {}
55}
oxisql_core/pool.rs

oxisql_core/
pool.rs
