diff --git a/sqlx-core/src/blocking.rs b/sqlx-core/src/blocking.rs index 633e7098..07aca56e 100644 --- a/sqlx-core/src/blocking.rs +++ b/sqlx-core/src/blocking.rs @@ -1,4 +1,5 @@ -//! Types and traits used to implement a database driver with **blocking** I/O. +//! Types and traits used to interact with a database driver +//! for **blocking** operations. //! use std::io::{Read, Result as IoResult, Write}; @@ -21,44 +22,60 @@ pub use connection::Connection; pub use options::ConnectOptions; pub use runtime::Runtime; +/// Convenience re-export of common traits for blocking operations. pub mod prelude { - pub use super::Acquire; - pub use super::Close; - pub use super::Connect; - pub use super::ConnectOptions; - pub use super::Connection; - pub use super::Runtime; - pub use crate::Database; + #[doc(no_inline)] + pub use super::Acquire as _; + #[doc(no_inline)] + pub use super::Close as _; + #[doc(no_inline)] + pub use super::Connect as _; + #[doc(no_inline)] + pub use super::ConnectOptions as _; + #[doc(no_inline)] + pub use super::Connection as _; + #[doc(no_inline)] + pub use super::Runtime as _; + #[doc(no_inline)] + pub use crate::Database as _; } -/// Uses the `std::net` primitives to implement a blocking runtime for SQLx. -#[derive(Debug)] -pub struct Blocking; +pub(super) mod rt { + /// Uses the `std::net` primitives to implement a blocking runtime for SQLx. + #[derive(Debug)] + pub struct Blocking; +} -impl crate::Runtime for Blocking { +impl crate::Runtime for rt::Blocking { + #[doc(hidden)] type TcpStream = TcpStream; } -impl Runtime for Blocking { +impl Runtime for rt::Blocking { + #[doc(hidden)] fn connect_tcp(host: &str, port: u16) -> IoResult { TcpStream::connect((host, port)) } } // 's: stream -impl<'s> crate::io::Stream<'s, Blocking> for TcpStream { +impl<'s> crate::io::Stream<'s, rt::Blocking> for TcpStream { + #[doc(hidden)] #[cfg(feature = "async")] type ReadFuture = futures_util::future::BoxFuture<'s, IoResult>; + #[doc(hidden)] #[cfg(feature = "async")] type WriteFuture = futures_util::future::BoxFuture<'s, IoResult>; + #[doc(hidden)] #[cfg(feature = "async")] fn read_async(&'s mut self, _buf: &'s mut [u8]) -> Self::ReadFuture { // UNREACHABLE: [`Blocking`] does not implement the [`Async`] marker unreachable!() } + #[doc(hidden)] #[cfg(feature = "async")] fn write_async(&'s mut self, _buf: &'s [u8]) -> Self::WriteFuture { // UNREACHABLE: [`Blocking`] does not implement the [`Async`] marker @@ -67,11 +84,13 @@ impl<'s> crate::io::Stream<'s, Blocking> for TcpStream { } // 's: stream -impl<'s> io::Stream<'s, Blocking> for TcpStream { +impl<'s> io::Stream<'s, rt::Blocking> for TcpStream { + #[doc(hidden)] fn read(&'s mut self, buf: &'s mut [u8]) -> IoResult { Read::read(self, buf) } + #[doc(hidden)] fn write(&'s mut self, buf: &'s [u8]) -> IoResult { let size = buf.len(); self.write_all(buf)?; diff --git a/sqlx-core/src/lib.rs b/sqlx-core/src/lib.rs index 39c951a4..47455f94 100644 --- a/sqlx-core/src/lib.rs +++ b/sqlx-core/src/lib.rs @@ -39,7 +39,7 @@ pub mod blocking; pub use acquire::Acquire; #[cfg(feature = "blocking")] -pub use blocking::Blocking; +pub use blocking::rt::Blocking; pub use close::Close; pub use connect::Connect; pub use connection::Connection; @@ -55,15 +55,22 @@ pub use runtime::AsyncStd; pub use runtime::Tokio; pub use runtime::{Async, DefaultRuntime, Runtime}; -#[cfg(any(feature = "async-std", feature = "tokio", feature = "actix"))] +/// Convenience re-export of common traits for non-blocking operations. pub mod prelude { - pub use super::Acquire; - pub use super::Close; - pub use super::Connect; - pub use super::ConnectOptions; - pub use super::Connection; - pub use super::Database; - pub use super::Runtime; + #[doc(no_inline)] + pub use super::Acquire as _; + #[doc(no_inline)] + pub use super::Close as _; + #[doc(no_inline)] + pub use super::Connect as _; + #[doc(no_inline)] + pub use super::ConnectOptions as _; + #[doc(no_inline)] + pub use super::Connection as _; + #[doc(no_inline)] + pub use super::Database as _; + #[doc(no_inline)] + pub use super::Runtime as _; } #[cfg(all( @@ -71,11 +78,3 @@ pub mod prelude { feature = "blocking" ))] pub use blocking::prelude; - -#[cfg(not(any( - feature = "async-std", - feature = "actix", - feature = "tokio", - feature = "blocking" -)))] -pub mod prelude {} diff --git a/sqlx-core/src/runtime.rs b/sqlx-core/src/runtime.rs index e36cc9c7..8190b8a9 100644 --- a/sqlx-core/src/runtime.rs +++ b/sqlx-core/src/runtime.rs @@ -39,7 +39,7 @@ pub use tokio_::Tokio; /// Additionally, a `std` blocking runtime is provided. This is intended for use in /// environments where asynchronous IO either doesn't make sense or isn't available. /// -/// - [`Blocking`][crate::blocking::Blocking] +/// - [`Blocking`][crate::Blocking] /// pub trait Runtime: 'static + Send + Sync + Sized { #[doc(hidden)] @@ -119,7 +119,7 @@ mod default { /// 1. [`AsyncStd`] /// 2. [`Tokio`] /// 3. [`Actix`] -/// 4. [`Blocking`] +/// 4. [`Blocking`][crate::Blocking] /// 5. `()` – No runtime selected (nothing is possible) /// /// The intent is to allow the following to cleanly work, regardless of the enabled runtime, diff --git a/sqlx-core/src/runtime/actix.rs b/sqlx-core/src/runtime/actix.rs index 541dd0ed..f107d568 100644 --- a/sqlx-core/src/runtime/actix.rs +++ b/sqlx-core/src/runtime/actix.rs @@ -7,7 +7,7 @@ use futures_util::{future::BoxFuture, AsyncReadExt, AsyncWriteExt, FutureExt, Tr use crate::{io::Stream, Async, Runtime}; -/// Actix SQLx runtime. Uses [`actix-rt`][actix_rt] to provide [`Runtime`]. +/// Provides [`Runtime`] for [**Actix**](https://actix.rs). Supports only non-blocking operation. /// /// As of 2021 Jan., Actix re-exports Tokio so this should be equivalent to [`Tokio`][crate::Tokio]. /// This is split-out to allow Actix to shift, or for it to use a different major Tokio version and diff --git a/sqlx-core/src/runtime/async_std.rs b/sqlx-core/src/runtime/async_std.rs index 42ccbb66..fd131893 100644 --- a/sqlx-core/src/runtime/async_std.rs +++ b/sqlx-core/src/runtime/async_std.rs @@ -1,4 +1,6 @@ use _async_std::net::TcpStream; +#[cfg(feature = "blocking")] +use _async_std::task; use futures_util::io::{Read, Write}; use futures_util::{future::BoxFuture, AsyncReadExt, AsyncWriteExt, FutureExt}; @@ -6,11 +8,11 @@ use futures_util::{future::BoxFuture, AsyncReadExt, AsyncWriteExt, FutureExt}; use crate::blocking; use crate::{io::Stream, Async, Runtime}; -/// Provides [`Runtime`] for [**async-std**][_async_std]. Supports both blocking +/// Provides [`Runtime`] for [**async-std**](https://async.rs). Supports both blocking /// and non-blocking operation. /// /// For blocking operation, the equivalent non-blocking methods are called -/// and trivially wrapped in [`task::block_on`][_async_std::task::block_on]. +/// and trivially wrapped in [`task::block_on`][task::block_on]. /// #[cfg_attr(doc_cfg, doc(cfg(feature = "async-std")))] #[derive(Debug)] @@ -30,8 +32,9 @@ impl Async for AsyncStd { #[cfg(feature = "blocking")] impl blocking::Runtime for AsyncStd { + #[doc(hidden)] fn connect_tcp(host: &str, port: u16) -> std::io::Result { - _async_std::task::block_on(Self::connect_tcp_async(host, port)) + task::block_on(Self::connect_tcp_async(host, port)) } } diff --git a/sqlx-core/src/runtime/tokio.rs b/sqlx-core/src/runtime/tokio.rs index e47f02c2..8a03be10 100644 --- a/sqlx-core/src/runtime/tokio.rs +++ b/sqlx-core/src/runtime/tokio.rs @@ -7,7 +7,7 @@ use futures_util::{future::BoxFuture, AsyncReadExt, AsyncWriteExt, FutureExt, Tr use crate::{io::Stream, Async, Runtime}; -/// Tokio SQLx runtime. Uses [`tokio`] to provide [`Runtime`]. +/// Provides [`Runtime`] for [**Tokio**](https://tokio.rs). Supports only non-blocking operation. /// /// SQLx does not require the use of a multi-threaded executor. /// diff --git a/sqlx-mysql/src/lib.rs b/sqlx-mysql/src/lib.rs index eed1c02d..b74307be 100644 --- a/sqlx-mysql/src/lib.rs +++ b/sqlx-mysql/src/lib.rs @@ -1,6 +1,6 @@ -//! [MySQL] database driver for [SQLx][sqlx_core], the Rust SQL toolkit. +//! [**MySQL**] database driver. //! -//! [MySQL]: https://www.mysql.com/ +//! [**MySQL**]: https://www.mysql.com/ //! #![cfg_attr(doc_cfg, feature(doc_cfg))] #![cfg_attr(not(any(feature = "async", feature = "blocking")), allow(unused))] diff --git a/sqlx/src/lib.rs b/sqlx/src/lib.rs index c33ed1ba..adc1fc8f 100644 --- a/sqlx/src/lib.rs +++ b/sqlx/src/lib.rs @@ -1,4 +1,31 @@ -//! SQLx is an async, pure Rust SQL crate featuring compile-time checked queries without a DSL. +//! SQLx is an async-first, pure Rust SQL crate featuring compile-time checked queries without a DSL. +//! +//! ## Database +//! +//! SQLx is **database agnostic**. Functionality is composed through traits defined in `sqlx-core` and implemented +//! in SQLx driver crates (`sqlx-postgres`, etc.). Enable support for a database by selecting an associated +//! crate feature. +//! +//! | Database | Supported Versions | Crate feature | Driver module | +//! | --- | --- | --- | --- | +//! | [MySQL](https://www.mysql.com/) | 5.0+, 8.0 | `mysql` | [`mysql`][sqlx_mysql] +//! | [MariaDB](https://mariadb.com/) | 10.2+ | `mysql` | [`mysql`][sqlx_mysql] +//! +//! ## Runtime +//! +//! SQLx is **asynchronous** (by default) and operation requires the selection of a runtime. This is done through +//! selecting one of the below crate features. +//! +//! Additionally, there is a **blocking** runtime available for simple use cases or environments where +//! asynchronous IO is either not available or not practical. The blocking runtime _does not wrap +//! the asynchronous runtime_. Blocking versions of the core traits are available in the [`blocking`] module. +//! +//! | Crate feature | Runtime | Prelude | +//! | --- | --- | --- | +//! | `async-std` | [`AsyncStd`] | [`sqlx::prelude`][prelude] or [`sqlx::blocking::prelude`][blocking::prelude] | +//! | `tokio` | [`Tokio`] | [`sqlx::prelude`][prelude]| +//! | `actix` | [`Actix`] | [`sqlx::prelude`][prelude] | +//! | `blocking` | [`Blocking`] | [`sqlx::blocking::prelude`][blocking::prelude] | //! #![deny(unsafe_code)] #![warn(rust_2018_idioms)] @@ -15,16 +42,18 @@ #![warn(clippy::useless_let_if_seq)] #![allow(clippy::doc_markdown)] -#[cfg(feature = "blocking")] -pub use sqlx_core::blocking; #[cfg(feature = "actix")] pub use sqlx_core::Actix; #[cfg(feature = "async-std")] pub use sqlx_core::AsyncStd; #[cfg(feature = "tokio")] pub use sqlx_core::Tokio; +#[cfg(feature = "blocking")] +pub use sqlx_core::{blocking, Blocking}; pub use sqlx_core::{ - prelude, ConnectOptions, Connection, Database, DefaultRuntime, Error, Result, Runtime, + prelude, Acquire, Close, Connect, ConnectOptions, Connection, Database, DefaultRuntime, Error, + Result, Runtime, }; #[cfg(feature = "mysql")] +#[doc(inline)] pub use sqlx_mysql as mysql;