Struct Pool 

pub struct Pool { /* private fields */ }

A cloneable pool of database connections.

Use Pool when many tasks need database access at the same time. Cloning the pool gives you another handle to the same shared pool state.

Pool is lazy by default. Building it does not open a connection or check that the database is reachable unless PoolBuilder::min_connections asks it to warm some connections up first. After that, Pool::acquire, Pool::query, Pool::prepare, and Pool::begin open a connection only when the pool has no idle one ready to reuse.

The pool keeps up to max_size open connections. When that many connections are already checked out, Pool::acquire waits until one is returned. Idle connections stay in the pool and are reused by later callers.

There is no background opener, health checker, or maintenance task. Idle timeout and max lifetime limits are enforced lazily when a connection is checked out or returned to the pool. Failed operations and unfinished pool transactions mark that checked-out connection as broken so it will not be reused.

Use Pool::with_hooks when the pool should run setup on fresh connections or validate a connection before handing it out.

Use Connection when one long-lived connection is enough.

Implementations

impl Pool

pub fn connect(options: impl IntoConnectOptions) -> Result<PoolBuilder, Error>

Starts building a pool for the given connection options.

pub fn with_hooks(self, hooks: Hooks) -> Pool

Returns a pool handle with hooks enabled.

Use Hooks when new connections need setup work or checked-out connections need validation before they are returned.

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

Acquires one connection from the pool.

This first tries to reuse an idle connection. If none is available and the pool is still below max_size, it opens a new one from the stored connection options.

When all pooled connections are already checked out, this waits until one is returned.

If hooks are configured, fresh connections run Hooks::on_connect and every candidate runs Hooks::before_acquire before this returns.

pub async fn try_acquire(&self) -> Result<PooledConnection, Error>

Tries to acquire one connection from the pool without waiting.

This follows the same reuse rules as Pool::acquire, but returns Error::PoolExhausted immediately when all pooled connections are already checked out.

Once the pool has a candidate connection, configured hooks still run before it is returned.

pub fn max_size(&self) -> usize

Returns the maximum number of open connections.

pub fn driver(&self) -> Driver

Returns the selected driver.

pub fn idle_count(&self) -> usize

Returns the number of idle connections currently kept by the pool.

pub fn available_permits(&self) -> usize

Returns the number of connections that can be acquired without waiting.

pub fn is_closed(&self) -> bool

Returns whether the pool has been closed.

pub fn close(&self)

Closes the pool to new acquire and begin calls.

Idle connections are dropped immediately. Checked-out connections stay usable until they are dropped, and are discarded instead of being returned to the pool.

pub async fn query(&self, sql: &str) -> Result<Rows<'_>, Error>

Acquires a connection, runs SQL, and returns rows.

pub async fn prepare(&self, sql: &str) -> Result<PoolStatement, Error>

Creates a pool-owned prepared statement handle.

Each execution acquires a connection and prepares the SQL on that connection.

pub async fn begin(&self) -> Result<PoolTransaction, Error>

Starts a transaction on a checked-out connection.

This is a convenience for calling Pool::acquire and then PooledConnection::begin. The transaction keeps that connection checked out until commit, rollback, or drop.

pub async fn try_begin(&self) -> Result<PoolTransaction, Error>

Tries to start a transaction without waiting for a connection.

This is the non-blocking counterpart to Pool::begin. It returns Error::PoolExhausted immediately when all pooled connections are already checked out.

Trait Implementations

impl Clone for Pool

fn clone(&self) -> Pool

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Executor for &Pool

type Rows<'a> = Rows<'a> where &Pool: 'a

Row stream returned by this executor.

type Statement<'a> = PoolStatement where &Pool: 'a

Prepared statement returned by this executor.

fn driver(&self) -> Driver

Returns the selected database driver.

async fn query( &mut self, sql: &str, ) -> Result<<&Pool as Executor>::Rows<'_>, Error>

Runs SQL without explicit bound parameters.

async fn query_prepared_source<P>( &mut self, sql: &str, params: &P, ) -> Result<<&Pool as Executor>::Rows<'_>, Error>

where P: ParamSource + ?Sized,

Runs SQL with a borrowed parameter source.

async fn prepare( &mut self, sql: &str, ) -> Result<<&Pool as Executor>::Statement<'_>, Error>

Prepares SQL for repeated use.

impl Executor for &mut Pool

type Rows<'a> = Rows<'a> where &mut Pool: 'a

Row stream returned by this executor.

type Statement<'a> = PoolStatement where &mut Pool: 'a

Prepared statement returned by this executor.

fn driver(&self) -> Driver

Returns the selected database driver.

async fn query( &mut self, sql: &str, ) -> Result<<&mut Pool as Executor>::Rows<'_>, Error>

Runs SQL without explicit bound parameters.

async fn query_prepared_source<P>( &mut self, sql: &str, params: &P, ) -> Result<<&mut Pool as Executor>::Rows<'_>, Error>

where P: ParamSource + ?Sized,

Runs SQL with a borrowed parameter source.

async fn prepare( &mut self, sql: &str, ) -> Result<<&mut Pool as Executor>::Statement<'_>, Error>

Prepares SQL for repeated use.

impl Executor for Pool

type Rows<'a> = Rows<'a> where Pool: 'a

Row stream returned by this executor.

type Statement<'a> = PoolStatement where Pool: 'a

Prepared statement returned by this executor.

fn driver(&self) -> Driver

Returns the selected database driver.

async fn query( &mut self, sql: &str, ) -> Result<<Pool as Executor>::Rows<'_>, Error>

Runs SQL without explicit bound parameters.

async fn query_prepared_source<P>( &mut self, sql: &str, params: &P, ) -> Result<<Pool as Executor>::Rows<'_>, Error>

where P: ParamSource + ?Sized,

Runs SQL with a borrowed parameter source.

async fn prepare( &mut self, sql: &str, ) -> Result<<Pool as Executor>::Statement<'_>, Error>

Prepares SQL for repeated use.