From e2ce463af873821e259c8dc90570d9291d9260e6 Mon Sep 17 00:00:00 2001 From: Austin Bonander Date: Fri, 30 Jun 2023 16:49:24 -0700 Subject: [PATCH] doc: make it clear that `ConnectOptions` types impl `FromStr` (#2574) --- sqlx-mysql/src/options/mod.rs | 26 +++++++++++++++++--------- sqlx-postgres/src/options/mod.rs | 28 ++++++++++++++++++---------- sqlx-sqlite/src/options/mod.rs | 16 ++++++++-------- 3 files changed, 43 insertions(+), 27 deletions(-) diff --git a/sqlx-mysql/src/options/mod.rs b/sqlx-mysql/src/options/mod.rs index dc06380b07..851237cc02 100644 --- a/sqlx-mysql/src/options/mod.rs +++ b/sqlx-mysql/src/options/mod.rs @@ -18,6 +18,9 @@ pub use ssl_mode::MySqlSslMode; /// mysql://[host][/database][?properties] /// ``` /// +/// This type also implements [`FromStr`][std::str::FromStr] so you can parse it from a string +/// containing a connection URL and then further adjust options if necessary (see example below). +/// /// ## Properties /// /// |Parameter|Default|Description| @@ -30,13 +33,10 @@ pub use ssl_mode::MySqlSslMode; /// # Example /// /// ```rust,no_run -/// # use sqlx_core::error::Error; -/// # use sqlx_core::connection::{Connection, ConnectOptions}; -/// # use sqlx_core::mysql::{MySqlConnectOptions, MySqlConnection, MySqlSslMode}; -/// # -/// # fn main() { -/// # #[cfg(feature = "_rt")] -/// # sqlx::__rt::test_block_on(async move { +/// # async fn example() -> sqlx::Result<()> { +/// use sqlx::{Connection, ConnectOptions}; +/// use sqlx::mysql::{MySqlConnectOptions, MySqlConnection, MySqlPool, MySqlSslMode}; +/// /// // URL connection string /// let conn = MySqlConnection::connect("mysql://root:password@localhost/db").await?; /// @@ -47,8 +47,16 @@ pub use ssl_mode::MySqlSslMode; /// .password("password") /// .database("db") /// .connect().await?; -/// # Result::<(), Error>::Ok(()) -/// # }).unwrap(); +/// +/// // Modifying options parsed from a string +/// let mut opts: MySqlConnectOptions = "mysql://root:password@localhost/db".parse()?; +/// +/// // Change the log verbosity level for queries. +/// // Information about SQL queries is logged at `DEBUG` level by default. +/// opts.log_statements(log::LevelFilter::Trace); +/// +/// let pool = MySqlPool::connect_with(&opts).await?; +/// # Ok(()) /// # } /// ``` #[derive(Debug, Clone)] diff --git a/sqlx-postgres/src/options/mod.rs b/sqlx-postgres/src/options/mod.rs index 0f1972f92d..bd22f84f07 100644 --- a/sqlx-postgres/src/options/mod.rs +++ b/sqlx-postgres/src/options/mod.rs @@ -23,6 +23,9 @@ mod ssl_mode; /// postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...] /// ``` /// +/// This type also implements [`FromStr`][std::str::FromStr] so you can parse it from a string +/// containing a connection URL and then further adjust options if necessary (see example below). +/// /// ## Parameters /// /// |Parameter|Default|Description| @@ -55,13 +58,10 @@ mod ssl_mode; /// # Example /// /// ```rust,no_run -/// # use sqlx_core::error::Error; -/// # use sqlx_core::connection::{Connection, ConnectOptions}; -/// # use sqlx_core::postgres::{PgConnectOptions, PgConnection, PgSslMode}; -/// # -/// # fn main() { -/// # #[cfg(feature = "_rt")] -/// # sqlx::__rt::test_block_on(async move { +/// use sqlx::{Connection, ConnectOptions}; +/// use sqlx::postgres::{PgConnectOptions, PgConnection, PgPool, PgSslMode}; +/// +/// # async fn example() -> sqlx::Result<()> { /// // URL connection string /// let conn = PgConnection::connect("postgres://localhost/mydb").await?; /// @@ -72,9 +72,17 @@ mod ssl_mode; /// .username("secret-user") /// .password("secret-password") /// .ssl_mode(PgSslMode::Require) -/// .connect().await?; -/// # Result::<(), Error>::Ok(()) -/// # }).unwrap(); +/// .connect() +/// .await?; +/// +/// // Modifying options parsed from a string +/// let mut opts: PgConnectOptions = "postgres://localhost/mydb".parse()?; +/// +/// // Change the log verbosity level for queries. +/// // Information about SQL queries is logged at `DEBUG` level by default. +/// opts.log_statements(log::LevelFilter::Trace); +/// +/// let pool = PgPool::connect_with(&opts).await?; /// # } /// ``` #[derive(Debug, Clone)] diff --git a/sqlx-sqlite/src/options/mod.rs b/sqlx-sqlite/src/options/mod.rs index 21013547ba..c35644f54e 100644 --- a/sqlx-sqlite/src/options/mod.rs +++ b/sqlx-sqlite/src/options/mod.rs @@ -25,6 +25,9 @@ use sqlx_core::IndexMap; /// A value of `SqliteConnectOptions` can be parsed from a connection URL, /// as described by [SQLite](https://www.sqlite.org/uri.html). /// +/// This type also implements [`FromStr`][std::str::FromStr] so you can parse it from a string +/// containing a connection URL and then further adjust options if necessary (see example below). +/// /// | URL | Description | /// | -- | -- | /// `sqlite::memory:` | Open an in-memory database. | @@ -36,20 +39,17 @@ use sqlx_core::IndexMap; /// # Example /// /// ```rust,no_run -/// # use sqlx_core::connection::ConnectOptions; -/// # use sqlx_core::error::Error; -/// # use sqlx_sqlite::{SqliteConnectOptions, SqliteJournalMode}; +/// # async fn example() -> sqlx::Result<()> { +/// use sqlx::ConnectOptions; +/// use sqlx::sqlite::{SqliteConnectOptions, SqliteJournalMode}; /// use std::str::FromStr; /// -/// # fn main() { -/// # #[cfg(feature = "_rt-async-std")] -/// # sqlx::__rt::test_block_on(async move { /// let conn = SqliteConnectOptions::from_str("sqlite://data.db")? /// .journal_mode(SqliteJournalMode::Wal) /// .read_only(true) /// .connect().await?; -/// # Result::<(), Error>::Ok(()) -/// # }).unwrap(); +/// # +/// # Ok(()) /// # } /// ``` #[derive(Clone, Debug)]