feat: create macros.preferred-crates example

Author: abonander

.github/workflows/examples.yml

@@ -207,6 +207,17 @@ jobs:
           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 migrate run
+
+      - 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:

Cargo.lock

@@ -19,6 +19,7 @@ members = [
     "examples/postgres/mockable-todos",
     "examples/postgres/multi-database",
     "examples/postgres/multi-tenant",
+    "examples/postgres/preferred-crates",
     "examples/postgres/todos",
     "examples/postgres/transaction",
     "examples/sqlite/todos",

Cargo.toml

@@ -0,0 +1,37 @@
+[package]
+name = "sqlx-example-postgres-preferred-crates"
+version.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+authors.workspace = true
+
+[dependencies]
+dotenvy.workspace = true
+
+anyhow = "1"
+chrono = "0.4"
+serde = { version = "1", features = ["derive"] }
+uuid = { version = "1", features = ["serde"] }
+
+[dependencies.tokio]
+workspace = true
+features = ["rt-multi-thread", "macros"]
+
+[dependencies.sqlx]
+path = "../../.."
+version = "0.8"
+features = ["runtime-tokio", "postgres", "bigdecimal", "chrono", "derive"]
+
+[dependencies.uses-rust-decimal]
+path = "uses-rust-decimal"
+package = "sqlx-example-postgres-preferred-crates-uses-rust-decimal"
+
+[dependencies.uses-time]
+path = "uses-time"
+package = "sqlx-example-postgres-preferred-crates-uses-time"
+
+[lints]
+workspace = true

examples/postgres/preferred-crates/Cargo.toml

@@ -0,0 +1,55 @@
+# Usage of `macros.preferred-crates` in `sqlx.toml`
+
+## The Problem
+
+SQLx has many optional features that enable integrations for external crates to map from/to SQL types.
+
+In some cases, more than one optional feature applies to the same set of types:
+
+* The `chrono` and `time` features enable mapping SQL date/time types to those in these crates.
+* Similarly, `bigdecimal` and `rust_decimal` enable mapping for the SQL `NUMERIC` type.
+
+Throughout its existence, the `query!()` family of macros has inferred which crate to use based on which optional 
+feature was enabled. If multiple features are enabled, one takes precedent over the other: `time` over `chrono`, 
+`rust_decimal` over `bigdecimal`, etc. The ordering is purely the result of historical happenstance and 
+does not indicate any specific preference for one crate over another. They each have their tradeoffs.
+
+This works fine when only one crate in the dependency graph depends on SQLx, but can break down if another crate
+in the dependency graph also depends on SQLx. Because of Cargo's [feature unification], any features enabled
+by this other crate are also forced on for all other crates that depend on the same version of SQLx in the same project.
+
+This is intentional design on Cargo's part; features are meant to be purely additive, so it can build each transitive
+dependency just once no matter how many crates depend on it. Otherwise, this could result in combinatorial explosion.
+
+Unfortunately for us, this means that if your project depends on SQLx and enables the `chrono` feature, but also depends 
+on another crate that enables the `time` feature, the `query!()` macros will end up thinking that _you_ want to use 
+the `time` crate, because they don't know any better. 
+
+Fixing this has historically required patching the dependency, which is annoying to maintain long-term.
+
+[feature unification]: https://doc.rust-lang.org/cargo/reference/features.html#feature-unification
+
+## The Solution
+
+However, as of 0.9.0, SQLx has gained the ability to configure the macros through the use of a `sqlx.toml` file.
+
+This includes the ability to tell the macros which crate you prefer, overriding the inference.
+
+See the [`sqlx.toml`](./sqlx.toml) file in this directory for details.
+
+A full reference `sqlx.toml` is also available as `sqlx-core/src/config/reference.toml`.
+
+## This Example
+
+This example exists both to showcase the macro configuration and also serve as a test for the functionality.
+
+It consists of three crates:
+
+* The root crate, which depends on SQLx and enables the `chrono` and `bigdecimal` features,
+* `uses-rust-decimal`, a dependency which also depends on SQLx and enables the `rust_decimal` feature,
+* and `uses-time`, a dependency which also depends on SQLx and enables the `time` feature.
+  * This serves as a stand-in for `tower-sessions-sqlx-store`, which is [one of the culprits for this issue](https://github.com/launchbadge/sqlx/issues/3412#issuecomment-2277377597).
+
+Given that both dependencies enable features with higher precedence, they would historically have interfered
+with the usage in the root crate. (Pretend that they're published to crates.io and cannot be easily changed.) 
+However, because the root crate uses a `sqlx.toml`, the macros know exactly which crates it wants to use and everyone's happy.

examples/postgres/preferred-crates/README.md

@@ -0,0 +1,9 @@
+[migrate]
+# Move `migrations/` to under `src/` to separate it from subcrates.
+migrations-dir = "src/migrations"
+
+[macros.preferred-crates]
+# Keeps `time` from taking precedent even though it's enabled by a dependency.
+date-time = "chrono"
+# Same thing with `rust_decimal`
+numeric = "bigdecimal"

examples/postgres/preferred-crates/sqlx.toml

@@ -0,0 +1,66 @@
+use anyhow::Context;
+use chrono::{DateTime, Utc};
+use sqlx::{Connection, PgConnection};
+use std::time::Duration;
+use uuid::Uuid;
+
+#[derive(serde::Serialize, serde::Deserialize, PartialEq, Eq, Debug)]
+struct SessionData {
+    user_id: Uuid,
+}
+
+#[derive(sqlx::FromRow, Debug)]
+struct User {
+    id: Uuid,
+    username: String,
+    password_hash: String,
+    // Because `time` is enabled by a transitive dependency, we previously would have needed
+    // a type override in the query to get types from `chrono`.
+    created_at: DateTime<Utc>,
+    updated_at: Option<DateTime<Utc>>,
+}
+
+const SESSION_DURATION: Duration = Duration::from_secs(60 * 60); // 1 hour
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let mut conn =
+        PgConnection::connect(&dotenvy::var("DATABASE_URL").context("DATABASE_URL must be set")?)
+            .await
+            .context("failed to connect to DATABASE_URL")?;
+
+    sqlx::migrate!("./src/migrations").run(&mut conn).await?;
+
+    uses_rust_decimal::create_table(&mut conn).await?;
+    uses_time::create_table(&mut conn).await?;
+
+    let user_id = sqlx::query!(
+        "insert into users(username, password_hash) values($1, $2) returning id",
+        "user_foo",
+        "<pretend this is a password hash>",
+    )
+    .fetch_one(&mut conn)
+    .await?;
+
+    let user = sqlx::query_as!(User, "select * from users where id = $1", user_id)
+        .fetch_one(&mut conn)
+        .await?;
+
+    let session =
+        uses_time::create_session(&mut conn, SessionData { user_id }, SESSION_DURATION).await?;
+
+    let session_from_id = uses_time::get_session::<SessionData>(&mut conn, session.id)
+        .await?
+        .expect("expected session");
+
+    assert_eq!(session, session_from_id);
+
+    let purchase_id =
+        uses_rust_decimal::create_purchase(&mut conn, user_id, 1234u32.into(), "Rent").await?;
+
+    let purchase = uses_rust_decimal::get_purchase(&mut conn, purchase_id)
+        .await?
+        .expect("expected purchase");
+
+    Ok(())
+}

examples/postgres/preferred-crates/src/main.rs

@@ -0,0 +1,30 @@
+-- We try to ensure every table has `created_at` and `updated_at` columns, which can help immensely with debugging
+-- and auditing.
+--
+-- While `created_at` can just be `default now()`, setting `updated_at` on update requires a trigger which
+-- is a lot of boilerplate. These two functions save us from writing that every time as instead we can just do
+--
+-- select trigger_updated_at('<table name>');
+--
+-- after a `CREATE TABLE`.
+create or replace function set_updated_at()
+    returns trigger as
+$$
+begin
+    NEW.updated_at = now();
+    return NEW;
+end;
+$$ language plpgsql;
+
+create or replace function trigger_updated_at(tablename regclass)
+    returns void as
+$$
+begin
+    execute format('CREATE TRIGGER set_updated_at
+        BEFORE UPDATE
+        ON %s
+        FOR EACH ROW
+        WHEN (OLD is distinct from NEW)
+    EXECUTE FUNCTION set_updated_at();', tablename);
+end;
+$$ language plpgsql;

examples/postgres/preferred-crates/src/migrations/01_setup.sql

@@ -0,0 +1,11 @@
+create table users(
+    id uuid primary key default gen_random_uuid(),
+    username text not null,
+    password_hash text not null,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz
+);
+
+create unique index users_username_unique on users(lower(username));
+
+select trigger_updated_at('users');

examples/postgres/preferred-crates/src/migrations/02_users.sql

@@ -0,0 +1,21 @@
+[package]
+name = "sqlx-example-postgres-preferred-crates-uses-rust-decimal"
+version.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+authors.workspace = true
+
+[dependencies]
+chrono = "0.4"
+rust_decimal = "1"
+uuid = "1"
+
+[dependencies.sqlx]
+workspace = true
+features = ["runtime-tokio", "postgres", "rust_decimal", "chrono", "uuid"]
+
+[lints]
+workspace = true

examples/postgres/preferred-crates/uses-rust-decimal/Cargo.toml

@@ -0,0 +1,53 @@
+use chrono::{DateTime, Utc};
+use sqlx::PgExecutor;
+
+#[derive(sqlx::FromRow)]
+struct Purchase {
+    pub id: Uuid,
+    pub user_id: Uuid,
+    pub amount: Decimal,
+    pub description: String,
+    pub created_at: DateTime<Utc>,
+}
+
+pub use rust_decimal::Decimal;
+use uuid::Uuid;
+
+pub async fn create_table(e: impl PgExecutor<'_>) -> sqlx::Result<()> {
+    sqlx::raw_sql(
+        // language=PostgreSQL
+        "create table if not exists purchases( \
+                id uuid primary key default gen_random_uuid(), \
+                user_id uuid not null, \
+                amount numeric not null check(amount > 0), \
+                description text not null, \
+                created_at timestamptz not null \
+             );
+        ",
+    )
+    .execute(e)
+    .await?;
+
+    Ok(())
+}
+
+pub async fn create_purchase(
+    e: impl PgExecutor<'_>,
+    user_id: Uuid,
+    amount: Decimal,
+    description: &str,
+) -> sqlx::Result<Uuid> {
+    sqlx::query_scalar("insert into purchases(user_id, amount, description) values ($1, $2, $3)")
+        .bind(user_id)
+        .bind(amount)
+        .bind(description)
+        .fetch_one(e)
+        .await
+}
+
+pub async fn get_purchase(e: impl PgExecutor<'_>, id: Uuid) -> sqlx::Result<Option<Purchase>> {
+    sqlx::query_as("select * from purchases where id = $1")
+        .bind(id)
+        .fetch_optional(e)
+        .await
+}

examples/postgres/preferred-crates/uses-rust-decimal/src/lib.rs

@@ -0,0 +1,21 @@
+[package]
+name = "sqlx-example-postgres-preferred-crates-uses-time"
+version.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+authors.workspace = true
+
+[dependencies]
+serde = "1"
+time = "0.3"
+uuid = "1"
+
+[dependencies.sqlx]
+workspace = true
+features = ["runtime-tokio", "postgres", "time", "json", "uuid"]
+
+[lints]
+workspace = true