diff --git a/README.md b/README.md index e95d79b717..97e91eb8f5 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ SQLx is an async, pure Rust† SQL crate featuring compile-time check - **Pure Rust**. The Postgres and MySQL/MariaDB drivers are written in pure Rust using **zero** unsafe†† code. -- **Runtime Agnostic**. Works on different runtimes ([`async-std`] / [`tokio`] / [`actix`]) and TLS backends ([`native-tls`], [`rustls`]). +- **Runtime Agnostic**. Works on different runtimes ([`async-global-executor`], [`async-std`], [`smol`], [`tokio`]) and TLS backends ([`native-tls`], [`rustls`]). @@ -119,11 +119,12 @@ The SQLite driver directly invokes the SQLite3 API via `libsqlite3-sys`, which r ## Install -SQLx is compatible with the [`async-std`], [`tokio`], and [`actix`] runtimes; and, the [`native-tls`] and [`rustls`] TLS backends. When adding the dependency, you must choose a runtime feature that is `runtime` + `tls`. +SQLx is compatible with the [`async-global-executor`], [`async-std`], [`smol`], and [`tokio`] runtimes; and, the [`native-tls`] and [`rustls`] TLS backends. When adding the dependency, you must choose a runtime feature that is `runtime` + `tls`. +[`async-global-executor`]: https://github.com/async-rs/async-global-executor [`async-std`]: https://github.com/async-rs/async-std +[`smol`]: https://github.com/smol-rs/smol [`tokio`]: https://github.com/tokio-rs/tokio -[`actix`]: https://github.com/actix/actix-net [`native-tls`]: https://crates.io/crates/native-tls [`rustls`]: https://crates.io/crates/rustls @@ -132,6 +133,12 @@ SQLx is compatible with the [`async-std`], [`tokio`], and [`actix`] runtimes; an [dependencies] # PICK ONE OF THE FOLLOWING: +# async-global-executor (no TLS) +sqlx = { version = "0.9", features = [ "runtime-async-global-executor" ] } + +# smol (no TLS) +sqlx = { version = "0.9", features = [ "runtime-smol" ] } + # tokio (no TLS) sqlx = { version = "0.9", features = [ "runtime-tokio" ] } # tokio + native-tls @@ -142,17 +149,6 @@ sqlx = { version = "0.9", features = [ "runtime-tokio", "tls-rustls-ring-webpki" sqlx = { version = "0.9", features = [ "runtime-tokio", "tls-rustls-ring-native-roots" ] } # tokio + rustls with aws-lc-rs sqlx = { version = "0.9", features = [ "runtime-tokio", "tls-rustls-aws-lc-rs" ] } - -# async-std (no TLS) -sqlx = { version = "0.9", features = [ "runtime-async-std" ] } -# async-std + native-tls -sqlx = { version = "0.9", features = [ "runtime-async-std", "tls-native-tls" ] } -# async-std + rustls with ring and WebPKI CA certificates -sqlx = { version = "0.9", features = [ "runtime-async-std", "tls-rustls-ring-webpki" ] } -# async-std + rustls with ring and platform's native CA certificates -sqlx = { version = "0.9", features = [ "runtime-async-std", "tls-rustls-ring-native-roots" ] } -# async-std + rustls with aws-lc-rs -sqlx = { version = "0.9", features = [ "runtime-async-std", "tls-rustls-aws-lc-rs" ] } ``` #### Cargo Feature Flags @@ -163,8 +159,12 @@ or separately. For forward compatibility, you should use the separate runtime and TLS features as the combination features may be removed in the future. +- `runtime-async-global-executor`: Use the `async-global-executor` runtime without enabling a TLS backend. + - `runtime-async-std`: Use the `async-std` runtime without enabling a TLS backend. +- `runtime-smol`: Use the `smol` runtime without enabling a TLS backend. + - `runtime-tokio`: Use the `tokio` runtime without enabling a TLS backend. - Actix-web is fully compatible with Tokio and so a separate runtime feature is no longer needed. @@ -253,9 +253,7 @@ use sqlx::postgres::PgPoolOptions; // use sqlx::mysql::MySqlPoolOptions; // etc. -#[async_std::main] // Requires the `attributes` feature of `async-std` -// or #[tokio::main] -// or #[actix_web::main] +#[tokio::main] async fn main() -> Result<(), sqlx::Error> { // Create a connection pool // for MySQL/MariaDB, use MySqlPoolOptions::new() diff --git a/src/lib.md b/src/lib.md index ea8fae4ed0..aefe3e00e2 100644 --- a/src/lib.md +++ b/src/lib.md @@ -5,18 +5,17 @@ Have a question? [Check our FAQ] or [open a discussion]. ### Runtime Support -SQLx supports both the [Tokio] and [async-std] runtimes. +SQLx supports the [async-global-executor], [async-std], [smol], and [Tokio] runtimes. -You choose which runtime SQLx uses by default by enabling one of the following features: +Choose the runtime SQLx uses by enabling one of the following features: +* `runtime-async-global-executor` * `runtime-async-std` +* `runtime-smol` * `runtime-tokio` -If more than one runtime feature is enabled, the Tokio runtime is used if a Tokio context exists on the current -thread, i.e. [`tokio::runtime::Handle::try_current()`] returns `Ok`; `async-std` is used otherwise. - -Note that while SQLx no longer produces a compile error if zero or multiple runtime features are enabled, -which is useful for libraries building on top of it, +Applications should generally enable exactly one runtime feature. SQLx does not produce a compile error if zero or +multiple runtime features are enabled, which is useful for libraries building on top of it, but **the use of nearly any async function in the API will panic without at least one runtime feature enabled**. The chief exception is the SQLite driver, which is runtime-agnostic, including its integration with the query macros. @@ -57,7 +56,8 @@ will return an error. [Check our FAQ]: https://www.github.com/launchbadge/sqlx/tree/main/FAQ.md [open a discussion]: https://github.com/launchbadge/sqlx/discussions/new?category=q-a [Tokio]: https://www.tokio.rs -[async-std]: https://www.async.rs -[`tokio::runtime::Handle::try_current()`]: https://docs.rs/tokio/latest/tokio/runtime/struct.Handle.html#method.try_current +[async-global-executor]: https://github.com/async-rs/async-global-executor +[async-std]: https://github.com/async-rs/async-std +[smol]: https://github.com/smol-rs/smol [`native-tls`]: https://docs.rs/native-tls/latest/native_tls/ [rustls]: https://docs.rs/rustls/latest/rustls/ diff --git a/src/macros/test.md b/src/macros/test.md index 122eb60356..bbcb336e96 100644 --- a/src/macros/test.md +++ b/src/macros/test.md @@ -1,9 +1,15 @@ Mark an `async fn` as a test with SQLx support. -The test will automatically be executed in the async runtime according to the chosen -`runtime-{async-std, tokio}` feature. If more than one runtime feature is enabled, `runtime-tokio` is preferred. +`#[sqlx::test]` requires one of SQLx's runtime features: -By default, this behaves identically to `#[tokio::test]`1 or `#[async_std::test]`: +* `runtime-async-global-executor` +* `runtime-async-std` +* `runtime-smol` +* `runtime-tokio` + +Applications should generally enable exactly one runtime feature. + +By default, this runs the async test to completion1: ```rust # // Note if reading these examples directly in `test.md`: @@ -18,7 +24,7 @@ async fn test_async_fn() { However, several advanced features are also supported as shown in the next section. -1`#[sqlx::test]` does not recognize any of the control arguments supported by `#[tokio::test]` +1When `runtime-tokio` is selected, `#[sqlx::test]` does not recognize any of the control arguments supported by `#[tokio::test]` as that would have complicated the implementation. If your use case requires any of those, feel free to open an issue. ### Automatic Test Database Management (requires `migrate` feature)