pub enum Pool {
Postgres(PgPool),
Mysql(MySqlPool),
Sqlite(SqlitePool),
}Expand description
A wrapper around any sqlx pool rustango supports. Cloning is
cheap: sqlx already keeps the pool behind an Arc.
Variants§
Implementations§
Source§impl Pool
impl Pool
Sourcepub async fn connect(url: &str) -> Result<Self, PoolError>
pub async fn connect(url: &str) -> Result<Self, PoolError>
Connect from a URL. The scheme picks the backend and must be
postgres://, postgresql://, mysql:// or sqlite:, and
its Cargo feature must be on.
§Errors
PoolError::UnsupportedSchemefor any other scheme.PoolError::FeatureNotEnabledwhen the scheme is known but its feature was off at build time.PoolError::Connectwhen sqlx cannot reach the database.
Sourcepub async fn connect_with_timeout(
url: &str,
timeout: Duration,
) -> Result<Self, PoolError>
pub async fn connect_with_timeout( url: &str, timeout: Duration, ) -> Result<Self, PoolError>
Self::connect with its own acquire timeout. That already
has a bounded default, see [ACQUIRE_TIMEOUT_ENV], so use
this only when one pool must differ from the rest.
§Errors
Same set as Self::connect, plus a Connect error if sqlx
times out before the database accepts the connection.
Sourcepub async fn connect_diagnosed(
url: &str,
timeout: Duration,
) -> Result<Self, ConnectDiagnosis>
pub async fn connect_diagnosed( url: &str, timeout: Duration, ) -> Result<Self, ConnectDiagnosis>
Self::connect_with_timeout, but a failure comes back as a
ConnectDiagnosis instead of a string.
Use this when the caller needs to branch on the kind of fault, as a tenant pre-flight check or an operator console showing per-fault advice does.
§Errors
A ConnectDiagnosis naming the fault, the endpoint tried (with
the password removed) and the driver’s own message.
Sourcepub async fn connect_admin(
url: &str,
database: Option<&str>,
timeout: Duration,
) -> Result<Self, ConnectDiagnosis>
pub async fn connect_admin( url: &str, database: Option<&str>, timeout: Duration, ) -> Result<Self, ConnectDiagnosis>
A one-connection admin pool on the server behind url, for
database and login DDL. database: None picks the maintenance
target: Postgres’ postgres database, no database on MySQL.
Each connection first runs Dialect::admin_session_sql.
§Errors
A ConnectDiagnosis; SQLite and unknown schemes are refused.
Sourcepub async fn connect_from_env() -> Result<Self, PoolError>
pub async fn connect_from_env() -> Result<Self, PoolError>
Read connection details from environment variables and connect.
See crate::env::database_url_from_env for the var resolution
order (DATABASE_URL takes precedence; otherwise assembled from
DB_DRIVER / DB_HOST / DB_PORT / DB_USER / DB_PASSWORD
/ DB_NAME / DB_PARAMS).
§Errors
PoolError::Env when the env-var pass fails (missing required
vars or unsupported driver), plus the same set as Self::connect.
Sourcepub fn connect_lazy(url: &str) -> Result<Self, PoolError>
pub fn connect_lazy(url: &str) -> Result<Self, PoolError>
Self::connect without dialling: the pool connects on the
first query. manage::Cli uses it for commands that may never
touch the database, so printing help opens no socket.
§Errors
As Self::connect.
Sourcepub async fn close(&self)
pub async fn close(&self)
Close the pool, waiting for its connections to be released.
Dropping a pool schedules the close but does not wait, so a short-lived pool such as a connection probe can outlive the code that made it and keep a socket open. Call this when you are done with the pool and the release must have happened before you return.
Sourcepub fn dialect(&self) -> &'static dyn Dialect
pub fn dialect(&self) -> &'static dyn Dialect
The Dialect for this pool’s backend. Use it to ask about
identifier quoting, placeholder shape and the rest without
caring which backend is underneath.
Sourcepub fn backend_name(&self) -> &'static str
pub fn backend_name(&self) -> &'static str
The backend’s short name, for logs and manage output. The
same as pool.dialect().name().
Sourcepub fn scope_key(&self) -> u64
pub fn scope_key(&self) -> u64
A stable hash of which database this pool talks to. Use it to partition any process-global cache whose rows are facts about one database.
ContentType is the case that needs it: its id comes from
that database’s own sequence, so the same natural key is a
different number in every tenant. A cache keyed on the natural
key alone would hand one tenant another’s id.
On Postgres the hash includes the connect options, and that
part is load-bearing. Schema-mode tenants share one host,
port and database, and differ only in their search_path.
Hashing the connection details alone would collide across all
of them. A pool that sets search_path with an after_connect
SET is told apart only if it was tagged with its schema.
Two pools to the same database hash the same, which is what a cache wants. Cheap enough for a hot path.
Sourcepub fn as_postgres(&self) -> Option<&PgPool>
pub fn as_postgres(&self) -> Option<&PgPool>
Borrow as a PgPool for code that needs Postgres itself.
None on any other backend.
Sourcepub fn as_mysql(&self) -> Option<&MySqlPool>
pub fn as_mysql(&self) -> Option<&MySqlPool>
Borrow as a MySqlPool. Self::as_postgres for MySQL.
Sourcepub fn as_sqlite(&self) -> Option<&SqlitePool>
pub fn as_sqlite(&self) -> Option<&SqlitePool>
Borrow as a SqlitePool. Self::as_postgres for SQLite.
Sourcepub async fn connect_postgres(url: &str) -> Result<PgPool, PoolError>
pub async fn connect_postgres(url: &str) -> Result<PgPool, PoolError>
Connect to Postgres and return the typed pool.
Prefer Self::connect unless you need sqlx::PgPool
itself. Use this over PgPool::connect, which applies none of
the framework’s pool options.
§Errors
As Self::connect.
Sourcepub fn connect_postgres_lazy(url: &str) -> Result<PgPool, PoolError>
pub fn connect_postgres_lazy(url: &str) -> Result<PgPool, PoolError>
Self::connect_postgres without dialling: the pool connects
on first use. For commands that may never touch the database.
§Errors
As Self::connect.
Sourcepub async fn connect_sqlite(url: &str) -> Result<SqlitePool, PoolError>
pub async fn connect_sqlite(url: &str) -> Result<SqlitePool, PoolError>
Connect to SQLite. This also applies the framework’s pragmas
through [sqlite_connect_options]: WAL for a file-backed
database, and ?mode=rwc so a missing file is created.
§Errors
As Self::connect.
Sourcepub fn connect_sqlite_lazy(url: &str) -> Result<SqlitePool, PoolError>
pub fn connect_sqlite_lazy(url: &str) -> Result<SqlitePool, PoolError>
Trait Implementations§
Source§impl From<Pool<Sqlite>> for Pool
Available on crate feature sqlite only.
impl From<Pool<Sqlite>> for Pool
sqlite only.Source§fn from(p: SqlitePool) -> Self
fn from(p: SqlitePool) -> Self
impl<'c> SqlExecutor<'c> for &'c Pool
Auto Trait Implementations§
impl !RefUnwindSafe for Pool
impl !UnwindSafe for Pool
impl Forget for Pool
impl Freeze for Pool
impl Move for Pool
impl Send for Pool
impl Sync for Pool
impl Unpin for Pool
impl UnsafeUnpin for Pool
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more