docs: Acquire examples and alternative

sqlx-core/Cargo.toml

@@ -164,3 +164,6 @@ bstr = { version = "0.2.17", default-features = false, features = ["std"], optio
 git2 = { version = "0.13.25", default-features = false, optional = true }
 hashlink = "0.7.0"
 indexmap = "1.7.0"
+
+[dev-dependencies]
+sqlx = { version = "0.5.10", path = "..", default-features = false, features = ["postgres"] }

sqlx-core/src/acquire.rs

@@ -5,6 +5,67 @@ use crate::transaction::Transaction;
 use futures_core::future::BoxFuture;
 use std::ops::{Deref, DerefMut};
 
+/// Acquire connections or transactions from a database in a generic way.
+///
+/// If you want to accept generic database connections that implement
+/// [`Acquire`] which then allows you to [`acquire`][`Acquire::acquire`] a
+/// connection or [`begin`][`Acquire::begin`] a transaction, then you can do it
+/// like that:
+///
+/// ```rust
+/// # use sqlx::{Acquire, postgres::Postgres, error::BoxDynError};
+/// async fn run_query<'a, A>(conn: A) -> Result<(), BoxDynError>
+/// where
+///     A: Acquire<'a, Database = Postgres>,
+/// {
+///     let mut conn = conn.acquire().await?;
+///
+///     sqlx::query!("SELECT 1 as v").fetch_one(&mut *conn).await?;
+///     sqlx::query!("SELECT 2 as v").fetch_one(&mut *conn).await?;
+///
+///     Ok(())
+/// }
+/// ```
+///
+/// If you run into a lifetime error about "implementation of `sqlx::Acquire` is
+/// not general enough", the [workaround] looks like this:
+///
+/// ```rust
+/// # use std::future::Future;
+/// # use sqlx::{Acquire, postgres::Postgres, error::BoxDynError};
+/// fn run_query<'a, 'c, A>(conn: A) -> impl Future<Output = Result<(), BoxDynError>> + Send + 'a
+/// where
+///     A: Acquire<'c, Database = Postgres> + Send + 'a,
+/// {
+///     async move {
+///         let mut conn = conn.acquire().await?;
+///
+///         sqlx::query!("SELECT 1 as v").fetch_one(&mut *conn).await?;
+///         sqlx::query!("SELECT 2 as v").fetch_one(&mut *conn).await?;
+///
+///         Ok(())
+///     }
+/// }
+/// ```
+///
+/// However, if you really just want to accept both, a transaction or a
+/// connection as an argument to a function, then it's easier to just accept a
+/// mutable reference to a database connection like so:
+///
+/// ```rust
+/// # use sqlx::{postgres::PgConnection, error::BoxDynError};
+/// async fn run_query(conn: &mut PgConnection) -> Result<(), BoxDynError> {
+///     sqlx::query!("SELECT 1 as v").fetch_one(&mut *conn).await?;
+///     sqlx::query!("SELECT 2 as v").fetch_one(&mut *conn).await?;
+///
+///     Ok(())
+/// }
+/// ```
+///
+/// The downside of this approach is that you have to `acquire` a connection
+/// from a pool first and can't directly pass the pool as argument.
+///
+/// [workaround]: https://github.com/launchbadge/sqlx/issues/1015#issuecomment-767787777
 pub trait Acquire<'c> {
     type Database: Database;