Skip to content

Commit

Permalink
docs: Acquire examples and alternative
Browse files Browse the repository at this point in the history
  • Loading branch information
stoically committed Feb 16, 2022
1 parent 2182925 commit 88043c2
Show file tree
Hide file tree
Showing 5 changed files with 72 additions and 1 deletion.
7 changes: 7 additions & 0 deletions .github/workflows/sqlx.yml
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@ jobs:
runs-on: ubuntu-20.04
strategy:
matrix:
postgres: [14, 9_6]
runtime: [async-std, tokio, actix]
tls: [native-tls, rustls]
steps:
Expand All @@ -90,12 +91,18 @@ jobs:
target
key: ${{ runner.os }}-test-${{ hashFiles('**/Cargo.lock') }}

- run: |
docker-compose -f tests/docker-compose.yml run -d -p 5432:5432 --name postgres_${{ matrix.postgres }} postgres_${{ matrix.postgres }}
docker exec postgres_${{ matrix.postgres }} bash -c "until pg_isready; do sleep 1; done"
- uses: actions-rs/cargo@v1
with:
command: test
args: >
--manifest-path sqlx-core/Cargo.toml
--features offline,all-databases,all-types,runtime-${{ matrix.runtime }}-${{ matrix.tls }}
env:
DATABASE_URL: postgres://postgres:password@localhost:5432/sqlx

cli:
name: CLI Binaries
Expand Down
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions sqlx-core/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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 = "..", features = ["postgres"] }
61 changes: 61 additions & 0 deletions sqlx-core/src/acquire.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
1 change: 0 additions & 1 deletion sqlx-core/src/sqlite/options/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,6 @@ use indexmap::IndexMap;
/// # Example
///
/// ```rust,no_run
/// # use sqlx_core as sqlx;
/// # use sqlx_core::connection::ConnectOptions;
/// # use sqlx_core::error::Error;
/// use sqlx::sqlite::{SqliteConnectOptions, SqliteJournalMode};
Expand Down

0 comments on commit 88043c2

Please sign in to comment.