Type Alias sqlx::MySqlPool

pub type MySqlPool = Pool<MySql>;

An alias for Pool, specialized for MySQL.

Aliased Type

struct MySqlPool(/* private fields */);

Implementations

impl<DB> Pool<DB>

where DB: Database,

pub async fn connect(uri: &str) -> Result<Pool<DB>, Error>

Creates a new connection pool with a default pool configuration and the given connection URI; and, immediately establishes one connection.

pub async fn connect_with( options: <<DB as Database>::Connection as Connection>::Options ) -> Result<Pool<DB>, Error>

Creates a new connection pool with a default pool configuration and the given connection options; and, immediately establishes one connection.

pub fn connect_lazy(uri: &str) -> Result<Pool<DB>, Error>

Creates a new connection pool with a default pool configuration and the given connection URI; and, will establish a connections as the pool starts to be used.

pub fn connect_lazy_with( options: <<DB as Database>::Connection as Connection>::Options ) -> Pool<DB>

Creates a new connection pool with a default pool configuration and the given connection options; and, will establish a connections as the pool starts to be used.

pub fn acquire( &self ) -> impl Future<Output = Result<PoolConnection<DB>, Error>> + 'static

Retrieves a connection from the pool.

Waits for at most the configured connection timeout before returning an error.

pub fn try_acquire(&self) -> Option<PoolConnection<DB>>

Attempts to retrieve a connection from the pool if there is one available.

Returns None immediately if there are no idle connections available in the pool.

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

Retrieves a new connection and immediately begins a new transaction.

pub async fn try_begin(&self) -> Result<Option<Transaction<'static, DB>>, Error>

Attempts to retrieve a new connection and immediately begins a new transaction if there is one available.

pub async fn close(&self)

Shut down the connection pool, waiting for all connections to be gracefully closed.

Upon .awaiting this call, any currently waiting or subsequent calls to Pool::acquire and the like will immediately return Error::PoolClosed and no new connections will be opened.

Any connections currently idle in the pool will be immediately closed, including sending a graceful shutdown message to the database server, if applicable.

Checked-out connections are unaffected, but will be closed in the same manner when they are returned to the pool.

Does not resolve until all connections are returned to the pool and gracefully closed.

Note: async fn

Because this is an async fn, the pool will not be marked as closed unless the returned future is polled at least once.

If you want to close the pool but don’t want to wait for all connections to be gracefully closed, you can do pool.close().now_or_never(), which polls the future exactly once with a no-op waker.

pub fn is_closed(&self) -> bool

Returns true if .close() has been called on the pool, false otherwise.

pub fn close_event(&self) -> CloseEvent

Get a future that resolves when Pool::close() is called.

If the pool is already closed, the future resolves immediately.

This can be used to cancel long-running operations that hold onto a PoolConnection so they don’t prevent the pool from closing (which would otherwise wait until all connections are returned).

Examples

These examples use Postgres and Tokio, but should suffice to demonstrate the concept.

Do something when the pool is closed:

use sqlx::PgPool;

let pool = PgPool::connect("postgresql://...").await?;

let pool2 = pool.clone();

tokio::spawn(async move {
    // Demonstrates that `CloseEvent` is itself a `Future` you can wait on.
    // This lets you implement any kind of on-close event that you like.
    pool2.close_event().await;

    println!("Pool is closing!");

    // Imagine maybe recording application statistics or logging a report, etc.
});

// The rest of the application executes normally...

// Close the pool before the application exits...
pool.close().await;

Cancel a long-running operation:

use sqlx::{Executor, PgPool};

let pool = PgPool::connect("postgresql://...").await?;

let pool2 = pool.clone();

tokio::spawn(async move {
    pool2.close_event().do_until(async {
        // This statement normally won't return for 30 days!
        // (Assuming the connection doesn't time out first, of course.)
        pool2.execute("SELECT pg_sleep('30 days')").await;

        // If the pool is closed before the statement completes, this won't be printed.
        // This is because `.do_until()` cancels the future it's given if the
        // pool is closed first.
        println!("Waited!");
    }).await;
});

// This normally wouldn't return until the above statement completed and the connection
// was returned to the pool. However, thanks to `.do_until()`, the operation was
// cancelled as soon as we called `.close().await`.
pool.close().await;

pub fn size(&self) -> u32

Returns the number of connections currently active. This includes idle connections.

pub fn num_idle(&self) -> usize

Returns the number of connections active and idle (not in use).

This will block until the number of connections stops changing for at least 2 atomic accesses in a row. If the number of idle connections is changing rapidly, this may run indefinitely.

Trait Implementations

impl<DB> Debug for Pool<DB>

where DB: Database,

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

Formats the value using the given formatter.

impl<DB> Clone for Pool<DB>

where DB: Database,

Returns a new Pool tied to the same shared connection pool.

fn clone(&self) -> Pool<DB>

Returns a copy of the value.

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

Performs copy-assignment from source.