feat: create sqlx.toml format (#3383)

* feat: create `sqlx.toml` format

* feat: add support for ignored_chars config to sqlx_core::migrate

* chore: test ignored_chars with `U+FEFF` (ZWNBSP/BOM)

https://en.wikipedia.org/wiki/Byte_order_mark

* refactor: make `Config` always compiled

simplifies usage while still making parsing optional for less generated code

* refactor: add origin information to `Column`

* feat(macros): implement `type_override` and `column_override` from `sqlx.toml`

* refactor(sqlx.toml): make all keys kebab-case, create `macros.preferred-crates`

* feat: make macros aware of `macros.preferred-crates`

* feat: make `sqlx-cli` aware of `database-url-var`

* feat: teach macros about `migrate.table-name`, `migrations-dir`

* feat: teach macros about `migrate.ignored-chars`

* chore: delete unused source file `sqlx-cli/src/migration.rs`

* feat: teach `sqlx-cli` about `migrate.defaults`

* feat: teach `sqlx-cli` about `migrate.migrations-dir`

* feat: teach `sqlx-cli` about `migrate.table-name`

* feat: introduce `migrate.create-schemas`

* WIP feat: create multi-tenant database example

* fix(postgres): don't fetch `ColumnOrigin` for transparently-prepared statements

* feat: progress on axum-multi-tenant example

* feat(config): better errors for mislabeled fields

* WIP feat: filling out axum-multi-tenant example

* feat: multi-tenant example

No longer Axum-based because filling out the request routes would have distracted from the purpose of the example.

* chore(ci): test multi-tenant example

* fixup after merge

* fix(ci): enable `sqlx-toml` in CLI build for examples

* fix: CI, README for `multi-tenant`

* fix: clippy warnings

* fix: multi-tenant README

* fix: sequential versioning inference for migrations

* fix: migration versioning with explicit overrides

* fix: only warn on ambiguous crates if the invocation relies on it

* fix: remove unused imports

* fix: doctest

* fix: `sqlx mig add` behavior and tests

* fix: restore original type-checking order

* fix: deprecation warning in `tests/postgres/macros.rs`

* feat: create postgres/multi-database example

* fix: examples/postgres/multi-database

* fix: cargo fmt

* chore: add tests for config `migrate.defaults`

* fix: sqlx-cli/tests/add.rs

* feat(cli): add `--config` override to all relevant commands

* chore: run `sqlx mig add` test with `RUST_BACKTRACE=1`

* fix: properly canonicalize config path for `sqlx mig add` test

* fix: get `sqlx mig add` test passing

* fix(cli): test `migrate.ignored-chars`, fix bugs

* feat: create `macros.preferred-crates` example

* fix(examples): use workspace `sqlx`

* fix: examples

* fix(sqlite): unexpected feature flags in `type_checking.rs`

* fix: run `cargo fmt`

* fix: more example fixes

* fix(ci): preferred-crates setup

* fix(examples): enable default-features for workspace `sqlx`

* fix(examples): issues in `preferred-crates`

* chore: adjust error message for missing param type in `query!()`

* doc: mention new `sqlx.toml` configuration

* chore: add `CHANGELOG` entry

Normally I generate these when cutting the release, but I wanted to take time to editorialize this one.

* doc: fix new example titles

* refactor: make `sqlx-toml` feature non-default, improve errors

* refactor: eliminate panics in `Config` read path

* chore: remove unused `axum` dependency from new examples

* fix(config): restore fallback to default config for macros

* chore(config): remove use of `once_cell` (to match `main`)

Author: abonander

.github/workflows/examples.yml

@@ -27,7 +27,7 @@ jobs:
           --bin sqlx
           --release
           --no-default-features
-          --features mysql,postgres,sqlite
+          --features mysql,postgres,sqlite,sqlx-toml
 
       - uses: actions/upload-artifact@v4
         with:
@@ -175,6 +175,49 @@ jobs:
           DATABASE_URL: postgres://postgres:password@localhost:5432/mockable-todos
         run: cargo run -p sqlx-example-postgres-mockable-todos
 
+      - name: Multi-Database (Setup)
+        working-directory: examples/postgres/multi-database
+        env:
+          DATABASE_URL: postgres://postgres:password@localhost:5432/multi-database
+          ACCOUNTS_DATABASE_URL: postgres://postgres:password@localhost:5432/multi-database-accounts
+          PAYMENTS_DATABASE_URL: postgres://postgres:password@localhost:5432/multi-database-payments
+        run: |
+          (cd accounts && sqlx db setup)
+          (cd payments && sqlx db setup)
+          sqlx db setup
+
+      - name: Multi-Database (Run)
+        env:
+          DATABASE_URL: postgres://postgres:password@localhost:5432/multi-database
+          ACCOUNTS_DATABASE_URL: postgres://postgres:password@localhost:5432/multi-database-accounts
+          PAYMENTS_DATABASE_URL: postgres://postgres:password@localhost:5432/multi-database-payments
+        run: cargo run -p sqlx-example-postgres-multi-database
+
+      - name: Multi-Tenant (Setup)
+        working-directory: examples/postgres/multi-tenant
+        env:
+          DATABASE_URL: postgres://postgres:password@localhost:5432/multi-tenant
+        run: |
+          (cd accounts && sqlx db setup)
+          (cd payments && sqlx migrate run)
+          sqlx migrate run
+
+      - name: Multi-Tenant (Run)
+        env:
+          DATABASE_URL: postgres://postgres:password@localhost:5432/multi-tenant
+        run: cargo run -p sqlx-example-postgres-multi-tenant
+
+      - name: Preferred-Crates (Setup)
+        working-directory: examples/postgres/preferred-crates
+        env:
+          DATABASE_URL: postgres://postgres:password@localhost:5432/preferred-crates
+        run: sqlx db setup
+
+      - name: Multi-Tenant (Run)
+        env:
+          DATABASE_URL: postgres://postgres:password@localhost:5432/preferred-crates
+        run: cargo run -p sqlx-example-postgres-preferred-crates
+
       - name: TODOs (Setup)
         working-directory: examples/postgres/todos
         env:

CHANGELOG.md

@@ -13,16 +13,42 @@ This section will be replaced in subsequent alpha releases. See the Git history
 
 ### Breaking
 
-* [[#3821]] Groundwork for 0.9.0-alpha.1
-  * Increased MSRV to 1.86 and set rust-version [@abonander]
+* [[#3821]]: Groundwork for 0.9.0-alpha.1 [[@abonander]]
+  * Increased MSRV to 1.86 and set rust-version 
   * Deleted deprecated combination runtime+TLS features (e.g. `runtime-tokio-native-tls`)
   * Deleted re-export of unstable `TransactionManager` trait in `sqlx`.
     * Not technically a breaking change because it's `#[doc(hidden)]`, 
       but [it _will_ break SeaORM][seaorm-2600] if not proactively fixed.
+* [[#3383]]: feat: create `sqlx.toml` format [[@abonander]]
+  * SQLx and `sqlx-cli` now support per-crate configuration files (`sqlx.toml`)
+  * New functionality includes, but is not limited to:
+    * Rename `DATABASE_URL` for a crate (for multi-database workspaces) 
+    * Set global type overrides for the macros (supporting custom types)
+    * Rename or relocate the `_sqlx_migrations` table (for multiple crates using the same database)
+    * Set characters to ignore when hashing migrations (e.g. ignore whitespace)
+  * More to be implemented in future releases.
+  * Enable feature `sqlx-toml` to use.
+    * `sqlx-cli` has it enabled by default, but `sqlx` does **not**.
+    * Default features of library crates can be hard to completely turn off because of [feature unification], 
+      so it's better to keep the default feature set as limited as possible. 
+      [This is something we learned the hard way.][preferred-crates]
+  * Guide: see `sqlx::_config` module in documentation.
+  * Reference: [[Link](sqlx-core/src/config/reference.toml)]
+  * Examples (written for Postgres but can be adapted to other databases; PRs welcome!):
+    * Multiple databases using `DATABASE_URL` renaming and global type overrides: [[Link](examples/postgres/multi-database)]
+    * Multi-tenant database using `_sqlx_migrations` renaming and multiple schemas: [[Link](examples/postgres/multi-tenant)]
+    * Force use of `chrono` when `time` is enabled (e.g. when using `tower-sessions-sqlx-store`): [[Link][preferred-crates]]
+      * Forcing `bigdecimal` when `rust_decimal` is enabled is also shown, but problems with `chrono`/`time` are more common.
+  * **Breaking changes**:
+    * Significant changes to the `Migrate` trait
+    * `sqlx::migrate::resolve_blocking()` is now `#[doc(hidden)]` and thus SemVer-exempt.
 
 [seaorm-2600]: https://github.com/SeaQL/sea-orm/issues/2600
+[feature unification]: https://doc.rust-lang.org/cargo/reference/features.html#feature-unification
+[preferred-crates]: examples/postgres/preferred-crates
 
-[#3821]: https://github.com/launchbadge/sqlx/pull/3830
+[#3821]: https://github.com/launchbadge/sqlx/pull/3821
+[#3383]: https://github.com/launchbadge/sqlx/pull/3383
 
 ## 0.8.6 - 2025-05-19