doc: mention new sqlx.toml configuration

Author: abonander

sqlx-core/src/config/macros.rs

@@ -1,6 +1,8 @@
 use std::collections::BTreeMap;
 
 /// Configuration for the `query!()` family of macros.
+///
+/// See also [`common::Config`][crate::config::common::Config] for renaming `DATABASE_URL`.
 #[derive(Debug, Default)]
 #[cfg_attr(
     feature = "sqlx-toml",

src/lib.rs

@@ -175,7 +175,8 @@ pub mod prelude {
 }
 
 #[cfg(feature = "_unstable-doc")]
-pub use sqlx_core::config;
+#[cfg_attr(docsrs, doc(cfg(feature = "_unstable-doc")))]
+pub use sqlx_core::config as _config;
 
 // NOTE: APIs exported in this module are SemVer-exempt.
 #[doc(hidden)]

src/macros/mod.rs

@@ -74,6 +74,25 @@
 ///
 /// [dotenv]: https://crates.io/crates/dotenv
 /// [dotenvy]: https://crates.io/crates/dotenvy
+///
+/// ## Configuration with `sqlx.toml`
+/// Multiple crate-wide configuration options are now available, including:
+///
+/// * change the name of the `DATABASE_URL` variable for using multiple databases in the same workspace
+///     * In the initial implementation, a separate crate must be created for each database.
+///       Using multiple databases in the same crate may become possible in the future.
+/// * global type overrides (useful for custom types!)
+/// * per-column type overrides
+/// * force use of a specific crate (e.g. `chrono` when both it and `time` are enabled)
+///
+/// See the [configuration guide] and [reference `sqlx.toml`] for details.
+///
+/// See also `examples/postgres/multi-database` and `examples/postgres/preferred-crates`
+/// for example usage.
+///
+/// [configuration guide]: crate::_config::macros::Config
+/// [reference `sqlx.toml`]: crate::_config::_reference
+///
 /// ## Query Arguments
 /// Like `println!()` and the other formatting macros, you can add bind parameters to your SQL
 /// and this macro will typecheck passed arguments and error on missing ones:
@@ -728,6 +747,7 @@ macro_rules! query_file_scalar_unchecked (
 /// Embeds migrations into the binary by expanding to a static instance of [Migrator][crate::migrate::Migrator].
 ///
 /// ```rust,ignore
+/// // Consider instead setting
 /// sqlx::migrate!("db/migrations")
 ///     .run(&pool)
 ///     .await?;
@@ -745,6 +765,38 @@ macro_rules! query_file_scalar_unchecked (
 ///
 /// See [MigrationSource][crate::migrate::MigrationSource] for details on structure of the ./migrations directory.
 ///
+/// ## Note: Platform-specific Line Endings
+/// Different platforms use different bytes for line endings by default:
+/// * Linux and MacOS use Line Feeds (LF:`\n`)
+/// * Windows uses Carriage Returns _and_ Line Feeds (CRLF:'\r\n')
+///
+/// This may result in un-reproducible hashes across platforms unless taken into account.
+///
+/// One solution is to use a [`.gitattributes` file](https://git-scm.com/docs/gitattributes)
+/// and force `.sql` files to be checked out with Line Feeds:
+///
+/// ```gitattributes
+/// *.sql text eol=lf
+/// ```
+///
+/// Another option is to configure migrations to ignore whitespace.
+/// See the next section for details.
+///
+/// ## Configuration with `sqlx.toml`
+/// Multiple crate-wide configuration options are now available, including:
+///
+/// * creating schemas on database setup
+/// * renaming the `_sqlx_migrations` table or placing it into a new schema
+/// * relocating the migrations directory
+/// * ignoring characters for hashing (such as whitespace and newlines)
+///
+/// See the [configuration guide] and [reference `sqlx.toml`] for details.
+///
+/// `sqlx-cli` can also read these options and use them when setting up or migrating databases.
+///
+/// [configuration guide]: crate::_config::migrate::Config
+/// [reference `sqlx.toml`]: crate::_config::_reference
+///
 /// ## Triggering Recompilation on Migration Changes
 /// In some cases when making changes to embedded migrations, such as adding a new migration without
 /// changing any Rust source files, you might find that `cargo build` doesn't actually do anything,