Struct Pool 

pub struct Pool<DB: Database> { /* private fields */ }

An instrumented wrapper around sqlx::Pool that emits OpenTelemetry spans and metrics for every database operation.

Create one via PoolBuilder. The wrapper is a drop-in replacement for sqlx::Pool: &Pool<DB> implements sqlx::Executor, so you can pass it straight into sqlx::query(...), sqlx::query_as(...), and friends. Connections acquired via acquire and transactions started via begin inherit the same instrumentation and produce spans / metrics with identical connection-level attributes.

Clone is cheap – the inner sqlx::Pool, the connection-level attribute set, and the metric instruments are all Arc-shared. Cloning never copies state; cloned pools share the same underlying connection pool and metric stream.

Example

use sqlx_otel::PoolBuilder;

let raw = sqlx::SqlitePool::connect(":memory:").await?;
let pool = PoolBuilder::from(raw).build();

// Pass `&pool` anywhere a `sqlx::Executor` is expected.
let row: (i64,) = sqlx::query_as("SELECT 1").fetch_one(&pool).await?;
assert_eq!(row.0, 1);

See also with_annotations for per-query semantic-convention attributes, and crate::QueryAnnotateExt for attaching annotations on the query side instead of the executor side.

Implementations

impl<DB: Database> Pool<DB>

pub async fn acquire(&self) -> Result<PoolConnection<DB>, Error>

Acquire a pooled connection instrumented for OpenTelemetry.

Records db.client.connection.wait_time (time spent waiting for a connection), tracks db.client.connection.pending_requests while the call is in flight, and increments db.client.connection.timeouts on sqlx::Error::PoolTimedOut. The returned PoolConnection records db.client.connection.use_time when dropped and is itself an sqlx::Executor via &mut conn.

Errors

Returns sqlx::Error if a connection cannot be obtained from the pool – typically PoolTimedOut when the configured acquire timeout elapses, or PoolClosed after close.

pub async fn begin(&self) -> Result<Transaction<'_, DB>, Error>

Begin a new transaction instrumented for OpenTelemetry.

The returned Transaction implements sqlx::Executor via &mut tx and emits the same per-operation spans and metrics as the pool itself. Call commit or rollback to terminate it; dropping the value without doing either rolls back implicitly (per SQLx’s usual behaviour).

Errors

Returns sqlx::Error if BEGIN fails – typically due to a connection problem or because the underlying connection cannot start a new transaction.

pub async fn close(&self)

Shut down the pool, waiting for all connections to be released.

pub fn is_closed(&self) -> bool

Returns true if the pool has been closed.

pub fn with_annotations( &self, annotations: QueryAnnotations, ) -> Annotated<'_, Self>

Return an annotated executor that attaches per-query semantic-convention attributes (db.operation.name, db.collection.name, db.query.summary, db.stored_procedure.name) to every span created by the next operation.

The returned wrapper borrows the pool and implements sqlx::Executor. Use the query-side equivalent (crate::QueryAnnotateExt) when the annotation belongs next to the query text rather than next to the executor.

Example

use sqlx::Executor as _;
use sqlx_otel::QueryAnnotations;

pool.with_annotations(
    QueryAnnotations::new()
        .operation("SELECT")
        .collection("users"),
)
.fetch_all("SELECT * FROM users")
.await?;

pub fn with_operation( &self, operation: impl Into<String>, collection: impl Into<String>, ) -> Annotated<'_, Self>

Shorthand for annotating the next operation with db.operation.name and db.collection.name.

Equivalent to self.with_annotations(QueryAnnotations::new().operation(op).collection(coll)).

Trait Implementations

impl<DB: Database> Clone for Pool<DB>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<DB: Debug + Database> Debug for Pool<DB>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'c, DB> Executor<'c> for &Pool<DB>

where DB: Database, for<'a> &'a mut DB::Connection: Executor<'a, Database = DB>,

fn execute<'e, 'q: 'e, E>( self, query: E, ) -> BoxFuture<'e, Result<<DB as Database>::QueryResult, Error>>

where E: 'q + Execute<'q, DB>, 'c: 'e,

Execute the query and return the total number of rows affected.

fn execute_many<'e, 'q: 'e, E>( self, query: E, ) -> BoxStream<'e, Result<<DB as Database>::QueryResult, Error>>

where E: 'q + Execute<'q, DB>, 'c: 'e,

Execute multiple queries and return the rows affected from each query, in a stream.

fn fetch<'e, 'q: 'e, E>( self, query: E, ) -> BoxStream<'e, Result<<DB as Database>::Row, Error>>

where E: 'q + Execute<'q, DB>, 'c: 'e,

Execute the query and return the generated results as a stream.

fn fetch_many<'e, 'q: 'e, E>( self, query: E, ) -> BoxStream<'e, Result<Either<<DB as Database>::QueryResult, <DB as Database>::Row>, Error>>

where E: 'q + Execute<'q, DB>, 'c: 'e,

Execute multiple queries and return the generated results as a stream from each query, in a stream.

fn fetch_all<'e, 'q: 'e, E>( self, query: E, ) -> BoxFuture<'e, Result<Vec<<DB as Database>::Row>, Error>>

where E: 'q + Execute<'q, DB>, 'c: 'e,

Execute the query and return all the generated results, collected into a Vec.

fn fetch_one<'e, 'q: 'e, E>( self, query: E, ) -> BoxFuture<'e, Result<<DB as Database>::Row, Error>>

where E: 'q + Execute<'q, DB>, 'c: 'e,

Execute the query and returns exactly one row.

fn fetch_optional<'e, 'q: 'e, E>( self, query: E, ) -> BoxFuture<'e, Result<Option<<DB as Database>::Row>, Error>>

where E: 'q + Execute<'q, DB>, 'c: 'e,

Execute the query and returns at most one row.

fn prepare<'e, 'q: 'e>( self, query: &'q str, ) -> BoxFuture<'e, Result<<DB as Database>::Statement<'q>, Error>>

where 'c: 'e,

Prepare the SQL query to inspect the type information of its parameters and results.

Be advised that when using the query, query_as, or query_scalar functions, the query is transparently prepared and executed.

This explicit API is provided to allow access to the statement metadata available after it prepared but before the first row is returned.

fn prepare_with<'e, 'q: 'e>( self, sql: &'q str, parameters: &'e [<DB as Database>::TypeInfo], ) -> BoxFuture<'e, Result<<DB as Database>::Statement<'q>, Error>>

where 'c: 'e,

Prepare the SQL query, with parameter type information, to inspect the type information about its parameters and results.

Only some database drivers (Postgres, MSSQL) can take advantage of this extra information to influence parameter type inference.

type Database = DB