Struct sqlx_core::pool::Pool [−][src]
pub struct Pool<DB: Database>(_);
Expand description
An asynchronous pool of SQLx database connections.
Create a pool with Pool::connect or Pool::connect_with and then call Pool::acquire to get a connection from the pool; when the connection is dropped it will return to the pool so it can be reused.
You can also pass &Pool
directly anywhere an Executor
is required; this will automatically
checkout a connection for you.
See the module documentation for examples.
The pool has a maximum connection limit that it will not exceed; if acquire()
is called
when at this limit and all connections are checked out, the task will be made to wait until
a connection becomes available.
You can configure the connection limit, and other parameters, using PoolOptions.
Calls to acquire()
are fair, i.e. fulfilled on a first-come, first-serve basis.
Pool
is Send
, Sync
and Clone
, so it should be created once at the start of your
application/daemon/web server/etc. and then shared with all tasks throughout its lifetime. How
best to accomplish this depends on your program architecture.
In Actix-Web, you can share a single pool with all request handlers using web::Data.
Type aliases are provided for each database to make it easier to sprinkle Pool
through
your codebase:
- MssqlPool (MSSQL)
- MySqlPool (MySQL)
- PgPool (PostgreSQL)
- SqlitePool (SQLite)
Why Use a Pool?
A single database connection (in general) cannot be used by multiple threads simultaneously for various reasons, but an application or web server will typically need to execute numerous queries or commands concurrently (think of concurrent requests against a web server; many or all of them will probably need to hit the database).
You could place the connection in a Mutex
but this will make it a huge bottleneck.
Naively, you might also think to just open a new connection per request, but this has a number of other caveats, generally due to the high overhead involved in working with a fresh connection. Examples to follow.
Connection pools facilitate reuse of connections to amortize these costs, helping to ensure that you’re not paying for them each time you need a connection.
1. Overhead of Opening a Connection
Opening a database connection is not exactly a cheap operation.
For SQLite, it means numerous requests to the filesystem and memory allocations, while for server-based databases it involves performing DNS resolution, opening a new TCP connection and allocating buffers.
Each connection involves a nontrivial allocation of resources for the database server, usually including spawning a new thread or process specifically to handle the connection, both for concurrency and isolation of faults.
Additionally, database connections typically involve a complex handshake including authentication, negotiation regarding connection parameters (default character sets, timezones, locales, supported features) and upgrades to encrypted tunnels.
If acquire()
is called on a pool with all connections checked out but it is not yet at its
connection limit (see next section), then a new connection is immediately opened, so this pool
does not automatically save you from the overhead of creating a new connection.
However, because this pool by design enforces reuse of connections, this overhead cost
is not paid each and every time you need a connection. In fact you set the min_connections
option in PoolOptions, the pool will create that many connections up-front so that they are
ready to go when a request comes in.
2. Connection Limits (MySQL, MSSQL, Postgres)
Database servers usually place hard limits on the number of connections that it allows open at any given time, to maintain performance targets and prevent excessive allocation of resources, namely RAM.
These limits have different defaults per database flavor, and may vary between different distributions of the same database, but are typically configurable on server start; if you’re paying for managed database hosting then the connection limit will typically vary with your pricing tier.
In MySQL, the default limit is typically 150, plus 1 which is reserved for a user with the
CONNECTION_ADMIN
privilege so you can still access the server to diagnose problems even
with all connections being used.
In MSSQL the only documentation for the default maximum limit is that it depends on the version and server configuration.
In Postgres, the default limit is typically 100, minus 3 which are reserved for superusers (putting the default limit for unprivileged users at 97 connections).
In any case, exceeding these limits results in an error when opening a new connection, which
in a web server context will turn into a 500 Internal Server Error
if not handled, but should
be turned into either 403 Forbidden
or 429 Too Many Requests
depending on your rate-limiting
scheme. However, in a web context, telling a client “go away, maybe try again later” results in
a sub-optimal user experience.
Instead with a connection pool, clients are made to wait in a fair queue for a connection to become available; by using a single connection pool for your whole application, you can ensure that you don’t exceed the connection limit of your database server while allowing response time to degrade gracefully at high load.
Of course, if multiple applications are connecting to the same database server, then you should ensure that the connection limits for all applications add up to your server’s maximum connections or less.
3. Resource Reuse
The first time you execute a query against your database, the database engine must first turn the SQL into an actionable query plan which it may then execute against the database. This involves parsing the SQL query, validating and analyzing it, and in the case of Postgres 12+ and SQLite, generating code to execute the query plan (native or bytecode, respectively).
These database servers provide a way to amortize this overhead by preparing the query, associating it with an object ID and placing its query plan in a cache to be referenced when it is later executed.
Prepared statements have other features, like bind parameters, which make them safer and more
ergonomic to use as well. By design, SQLx pushes you towards using prepared queries/statements
via the Query API et al. and the query!()
macro et al., for
reasons of safety, ergonomics, and efficiency.
However, because database connections are typically isolated from each other in the database server (either by threads or separate processes entirely), they don’t typically share prepared statements between connections so this work must be redone for each connection.
As with section 1, by facilitating reuse of connections, Pool
helps to ensure their prepared
statements (and thus cached query plans) can be reused as much as possible, thus amortizing
the overhead involved.
Depending on the database server, a connection will have caches for all kinds of other data as well and queries will generally benefit from these caches being “warm” (populated with data).
Implementations
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::Connection as Connection>::Options
) -> Result<Self, Error>
pub async fn connect_with(
options: <DB::Connection as Connection>::Options
) -> Result<Self, Error>
Creates a new connection pool with a default pool configuration and the given connection options; and, immediately establishes one connection.
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.
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.
Retrieves a connection from the pool.
Waits for at most the configured connection timeout before returning an error.
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.
Retrieves a new connection and immediately begins a new transaction.
Attempts to retrieve a new connection and immediately begins a new transaction if there is one available.
Ends the use of a connection pool. Prevents any new connections and will close all active connections when they are returned to the pool.
Does not resolve until all connections are closed.
Returns true
if .close()
has been called on the pool, false
otherwise.
Returns the number of connections currently active. This includes idle connections.
Trait Implementations
type Database = DB
type Connection = PoolConnection<DB>
Returns a new Pool tied to the same shared connection pool.
type Database = DB
fn fetch_many<'e, 'q: 'e, E: 'q>(
self,
query: E
) -> BoxStream<'e, Result<Either<DB::QueryResult, DB::Row>, Error>> where
E: Execute<'q, Self::Database>,
fn fetch_many<'e, 'q: 'e, E: 'q>(
self,
query: E
) -> BoxStream<'e, Result<Either<DB::QueryResult, DB::Row>, Error>> where
E: Execute<'q, Self::Database>,
Execute multiple queries and return the generated results as a stream from each query, in a stream. Read more
Execute the query and returns at most one row.
Prepare the SQL query, with parameter type information, to inspect the type information about its parameters and results. Read more
Execute the query and return the total number of rows affected.
fn execute_many<'e, 'q: 'e, E: 'q>(
self,
query: E
) -> BoxStream<'e, Result<<Self::Database as Database>::QueryResult, Error>> where
'c: 'e,
E: Execute<'q, Self::Database>,
fn execute_many<'e, 'q: 'e, E: 'q>(
self,
query: E
) -> BoxStream<'e, Result<<Self::Database as Database>::QueryResult, Error>> where
'c: 'e,
E: Execute<'q, Self::Database>,
Execute multiple queries and return the rows affected from each query, in a stream.
Execute the query and return the generated results as a stream.
Execute the query and return all the generated results, collected into a Vec
.
Execute the query and returns exactly one row.
Auto Trait Implementations
impl<DB> !RefUnwindSafe for Pool<DB>
impl<DB> !UnwindSafe for Pool<DB>
Blanket Implementations
Mutably borrows from an owned value. Read more
fn fmt_binary(self) -> FmtBinary<Self> where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self> where
Self: Binary,
Causes self
to use its Binary
implementation when Debug
-formatted.
fn fmt_display(self) -> FmtDisplay<Self> where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self> where
Self: Display,
Causes self
to use its Display
implementation when
Debug
-formatted. Read more
fn fmt_lower_exp(self) -> FmtLowerExp<Self> where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self> where
Self: LowerExp,
Causes self
to use its LowerExp
implementation when
Debug
-formatted. Read more
fn fmt_lower_hex(self) -> FmtLowerHex<Self> where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self> where
Self: LowerHex,
Causes self
to use its LowerHex
implementation when
Debug
-formatted. Read more
Causes self
to use its Octal
implementation when Debug
-formatted.
fn fmt_pointer(self) -> FmtPointer<Self> where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self> where
Self: Pointer,
Causes self
to use its Pointer
implementation when
Debug
-formatted. Read more
fn fmt_upper_exp(self) -> FmtUpperExp<Self> where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self> where
Self: UpperExp,
Causes self
to use its UpperExp
implementation when
Debug
-formatted. Read more
fn fmt_upper_hex(self) -> FmtUpperHex<Self> where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self> where
Self: UpperHex,
Causes self
to use its UpperHex
implementation when
Debug
-formatted. Read more
impl<T> Pipe for T where
T: ?Sized,
impl<T> Pipe for T where
T: ?Sized,
Pipes by value. This is generally the method you want to use. Read more
Borrows self
and passes that borrow into the pipe function. Read more
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R where
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R where
R: 'a,
Mutably borrows self
and passes that borrow into the pipe function. Read more
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R where
Self: Borrow<B>,
R: 'a,
B: 'a + ?Sized,
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R where
Self: Borrow<B>,
R: 'a,
B: 'a + ?Sized,
Borrows self
, then passes self.borrow()
into the pipe function. Read more
fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> R where
Self: BorrowMut<B>,
R: 'a,
B: 'a + ?Sized,
fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> R where
Self: BorrowMut<B>,
R: 'a,
B: 'a + ?Sized,
Mutably borrows self
, then passes self.borrow_mut()
into the pipe
function. Read more
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R where
Self: AsRef<U>,
R: 'a,
U: 'a + ?Sized,
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R where
Self: AsRef<U>,
R: 'a,
U: 'a + ?Sized,
Borrows self
, then passes self.as_ref()
into the pipe function.
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R where
Self: AsMut<U>,
R: 'a,
U: 'a + ?Sized,
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R where
Self: AsMut<U>,
R: 'a,
U: 'a + ?Sized,
Mutably borrows self
, then passes self.as_mut()
into the pipe
function. Read more
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R where
Self: Deref<Target = T>,
T: 'a + ?Sized,
R: 'a,
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R where
Self: Deref<Target = T>,
T: 'a + ?Sized,
R: 'a,
Borrows self
, then passes self.deref()
into the pipe function.
fn pipe_as_ref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R where
Self: AsRef<T>,
T: 'a,
R: 'a,
fn pipe_as_ref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R where
Self: AsRef<T>,
T: 'a,
R: 'a,
Pipes a trait borrow into a function that cannot normally be called in suffix position. Read more
fn pipe_as_mut<'a, T, R>(&'a mut self, func: impl FnOnce(&'a mut T) -> R) -> R where
Self: AsMut<T>,
T: 'a,
R: 'a,
fn pipe_as_mut<'a, T, R>(&'a mut self, func: impl FnOnce(&'a mut T) -> R) -> R where
Self: AsMut<T>,
T: 'a,
R: 'a,
Pipes a trait mutable borrow into a function that cannot normally be called in suffix position. Read more
fn pipe_borrow<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R where
Self: Borrow<T>,
T: 'a,
R: 'a,
fn pipe_borrow<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R where
Self: Borrow<T>,
T: 'a,
R: 'a,
Pipes a trait borrow into a function that cannot normally be called in suffix position. Read more
fn pipe_borrow_mut<'a, T, R>(
&'a mut self,
func: impl FnOnce(&'a mut T) -> R
) -> R where
Self: BorrowMut<T>,
T: 'a,
R: 'a,
fn pipe_borrow_mut<'a, T, R>(
&'a mut self,
func: impl FnOnce(&'a mut T) -> R
) -> R where
Self: BorrowMut<T>,
T: 'a,
R: 'a,
Pipes a trait mutable borrow into a function that cannot normally be called in suffix position. Read more
fn pipe_deref<'a, R>(&'a self, func: impl FnOnce(&'a Self::Target) -> R) -> R where
Self: Deref,
R: 'a,
fn pipe_deref<'a, R>(&'a self, func: impl FnOnce(&'a Self::Target) -> R) -> R where
Self: Deref,
R: 'a,
Pipes a dereference into a function that cannot normally be called in suffix position. Read more
fn pipe_deref_mut<'a, R>(
&'a mut self,
func: impl FnOnce(&'a mut Self::Target) -> R
) -> R where
Self: DerefMut,
R: 'a,
fn pipe_deref_mut<'a, R>(
&'a mut self,
func: impl FnOnce(&'a mut Self::Target) -> R
) -> R where
Self: DerefMut,
R: 'a,
Pipes a mutable dereference into a function that cannot normally be called in suffix position. Read more
Pipes a reference into a function that cannot ordinarily be called in suffix position. Read more
type Output = T
type Output = T
Should always be Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self where
Self: Borrow<B>,
B: ?Sized,
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self where
Self: Borrow<B>,
B: ?Sized,
Immutable access to the Borrow<B>
of a value. Read more
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self where
Self: BorrowMut<B>,
B: ?Sized,
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self where
Self: BorrowMut<B>,
B: ?Sized,
Mutable access to the BorrowMut<B>
of a value. Read more
Immutable access to the AsRef<R>
view of a value. Read more
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self where
Self: AsMut<R>,
R: ?Sized,
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self where
Self: AsMut<R>,
R: ?Sized,
Mutable access to the AsMut<R>
view of a value. Read more
Immutable access to the Deref::Target
of a value. Read more
Mutable access to the Deref::Target
of a value. Read more
Calls .tap()
only in debug builds, and is erased in release builds.
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
Calls .tap_mut()
only in debug builds, and is erased in release
builds. Read more
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self where
Self: Borrow<B>,
B: ?Sized,
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self where
Self: Borrow<B>,
B: ?Sized,
Calls .tap_borrow()
only in debug builds, and is erased in release
builds. Read more
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self where
Self: BorrowMut<B>,
B: ?Sized,
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self where
Self: BorrowMut<B>,
B: ?Sized,
Calls .tap_borrow_mut()
only in debug builds, and is erased in release
builds. Read more
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self where
Self: AsRef<R>,
R: ?Sized,
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self where
Self: AsRef<R>,
R: ?Sized,
Calls .tap_ref()
only in debug builds, and is erased in release
builds. Read more
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self where
Self: AsMut<R>,
R: ?Sized,
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self where
Self: AsMut<R>,
R: ?Sized,
Calls .tap_ref_mut()
only in debug builds, and is erased in release
builds. Read more
Provides immutable access for inspection. Read more
Calls tap
in debug builds, and does nothing in release builds.
Provides mutable access for modification. Read more
fn tap_mut_dbg<F, R>(self, func: F) -> Self where
F: FnOnce(&mut Self) -> R,
fn tap_mut_dbg<F, R>(self, func: F) -> Self where
F: FnOnce(&mut Self) -> R,
Calls tap_mut
in debug builds, and does nothing in release builds.
impl<T, U> TapAsRef<U> for T where
U: ?Sized,
impl<T, U> TapAsRef<U> for T where
U: ?Sized,
Provides immutable access to the reference for inspection.
fn tap_ref_dbg<F, R>(self, func: F) -> Self where
Self: AsRef<T>,
F: FnOnce(&T) -> R,
fn tap_ref_dbg<F, R>(self, func: F) -> Self where
Self: AsRef<T>,
F: FnOnce(&T) -> R,
Calls tap_ref
in debug builds, and does nothing in release builds.
fn tap_ref_mut<F, R>(self, func: F) -> Self where
Self: AsMut<T>,
F: FnOnce(&mut T) -> R,
fn tap_ref_mut<F, R>(self, func: F) -> Self where
Self: AsMut<T>,
F: FnOnce(&mut T) -> R,
Provides mutable access to the reference for modification.
fn tap_ref_mut_dbg<F, R>(self, func: F) -> Self where
Self: AsMut<T>,
F: FnOnce(&mut T) -> R,
fn tap_ref_mut_dbg<F, R>(self, func: F) -> Self where
Self: AsMut<T>,
F: FnOnce(&mut T) -> R,
Calls tap_ref_mut
in debug builds, and does nothing in release builds.
impl<T, U> TapBorrow<U> for T where
U: ?Sized,
impl<T, U> TapBorrow<U> for T where
U: ?Sized,
fn tap_borrow<F, R>(self, func: F) -> Self where
Self: Borrow<T>,
F: FnOnce(&T) -> R,
fn tap_borrow<F, R>(self, func: F) -> Self where
Self: Borrow<T>,
F: FnOnce(&T) -> R,
Provides immutable access to the borrow for inspection. Read more
fn tap_borrow_dbg<F, R>(self, func: F) -> Self where
Self: Borrow<T>,
F: FnOnce(&T) -> R,
fn tap_borrow_dbg<F, R>(self, func: F) -> Self where
Self: Borrow<T>,
F: FnOnce(&T) -> R,
Calls tap_borrow
in debug builds, and does nothing in release builds.
fn tap_borrow_mut<F, R>(self, func: F) -> Self where
Self: BorrowMut<T>,
F: FnOnce(&mut T) -> R,
fn tap_borrow_mut<F, R>(self, func: F) -> Self where
Self: BorrowMut<T>,
F: FnOnce(&mut T) -> R,
Provides mutable access to the borrow for modification.
fn tap_borrow_mut_dbg<F, R>(self, func: F) -> Self where
Self: BorrowMut<T>,
F: FnOnce(&mut T) -> R,
fn tap_borrow_mut_dbg<F, R>(self, func: F) -> Self where
Self: BorrowMut<T>,
F: FnOnce(&mut T) -> R,
Calls tap_borrow_mut
in debug builds, and does nothing in release
builds. Read more
Immutably dereferences self
for inspection.
fn tap_deref_dbg<F, R>(self, func: F) -> Self where
Self: Deref,
F: FnOnce(&Self::Target) -> R,
fn tap_deref_dbg<F, R>(self, func: F) -> Self where
Self: Deref,
F: FnOnce(&Self::Target) -> R,
Calls tap_deref
in debug builds, and does nothing in release builds.
fn tap_deref_mut<F, R>(self, func: F) -> Self where
Self: DerefMut,
F: FnOnce(&mut Self::Target) -> R,
fn tap_deref_mut<F, R>(self, func: F) -> Self where
Self: DerefMut,
F: FnOnce(&mut Self::Target) -> R,
Mutably dereferences self
for modification.
fn tap_deref_mut_dbg<F, R>(self, func: F) -> Self where
Self: DerefMut,
F: FnOnce(&mut Self::Target) -> R,
fn tap_deref_mut_dbg<F, R>(self, func: F) -> Self where
Self: DerefMut,
F: FnOnce(&mut Self::Target) -> R,
Calls tap_deref_mut
in debug builds, and does nothing in release
builds. Read more