feat: create postgres/multi-database example

Author: abonander

.github/workflows/examples.yml

@@ -175,6 +175,24 @@ 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:

Cargo.lock

@@ -17,6 +17,7 @@ members = [
     "examples/postgres/json",
     "examples/postgres/listen",
     "examples/postgres/mockable-todos",
+    "examples/postgres/multi-database",
     "examples/postgres/multi-tenant",
     "examples/postgres/todos",
     "examples/postgres/transaction",

Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "sqlx-example-postgres-multi-database"
+version.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+authors.workspace = true
+
+[dependencies]
+tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
+
+sqlx = { path = "../../..", version = "0.8.3", features = ["runtime-tokio", "postgres"] }
+
+axum = { version = "0.8.1", features = ["macros"] }
+
+color-eyre = "0.6.3"
+dotenvy = "0.15.7"
+tracing-subscriber = "0.3.19"
+
+rust_decimal = "1.36.0"
+
+rand = "0.8.5"
+
+[dependencies.accounts]
+path = "accounts"
+package = "sqlx-example-postgres-multi-database-accounts"
+
+[dependencies.payments]
+path = "payments"
+package = "sqlx-example-postgres-multi-database-payments"
+
+[lints]
+workspace = true

examples/postgres/multi-database/Cargo.toml

@@ -0,0 +1,62 @@
+# Axum App with multi-database Database
+
+This example project involves three crates, each owning a different schema in one database,
+with their own set of migrations.
+
+* The main crate, a simple binary simulating the action of a REST API.
+    * Owns the `public` schema (tables are referenced unqualified).
+    * Migrations are moved to `src/migrations` using config key `migrate.migrations-dir`
+      to visually separate them from the subcrate folders.
+* `accounts`: a subcrate simulating a reusable account-management crate.
+    * Owns schema `accounts`.
+* `payments`: a subcrate simulating a wrapper for a payments API.
+    * Owns schema `payments`.
+
+## Note: Schema-Qualified Names
+
+This example uses schema-qualified names everywhere for clarity.
+
+It can be tempting to change the `search_path` of the connection (MySQL, Postgres) to eliminate the need for schema
+prefixes, but this can cause some really confusing issues when names conflict.
+
+This example will generate a `_sqlx_migrations` table in three different schemas; if `search_path` is set
+to `public,accounts,payments` and the migrator for the main application attempts to reference the table unqualified,
+it would throw an error.
+
+# Setup
+
+This example requires running three different sets of migrations.
+
+Ensure `sqlx-cli` is installed with Postgres and `sqlx.toml` support:
+
+```
+cargo install sqlx-cli --features postgres,sqlx-toml
+```
+
+Start a Postgres server (shown here using Docker, `run` command also works with `podman`):
+
+```
+docker run -d -e POSTGRES_PASSWORD=password -p 5432:5432 --name postgres postgres:latest
+```
+
+Create `.env` with the various database URLs or set them in your shell environment;
+
+```
+DATABASE_URL=postgres://postgres:password@localhost/example-multi-database
+ACCOUNTS_DATABASE_URL=postgres://postgres:password@localhost/example-multi-database-accounts
+PAYMENTS_DATABASE_URL=postgres://postgres:password@localhost/example-multi-database-payments
+```
+
+Run the following commands:
+
+```
+(cd accounts && sqlx db setup)
+(cd payments && sqlx db setup)
+sqlx db setup
+```
+
+It is an open question how to make this more convenient; `sqlx-cli` could gain a `--recursive` flag that checks
+subdirectories for `sqlx.toml` files, but that would only work for crates within the same workspace. If the `accounts`
+and `payments` crates were instead crates.io dependencies, we would need Cargo's help to resolve that information.
+
+An issue has been opened for discussion: <https://github.com/launchbadge/sqlx/issues/3761>

examples/postgres/multi-database/README.md

@@ -0,0 +1,22 @@
+[package]
+name = "sqlx-example-postgres-multi-database-accounts"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+sqlx = { workspace = true, features = ["postgres", "time", "uuid", "macros", "sqlx-toml"] }
+tokio = { version = "1", features = ["rt", "sync"] }
+
+argon2 = { version = "0.5.3", features = ["password-hash"] }
+password-hash = { version = "0.5", features = ["std"] }
+
+uuid = { version = "1", features = ["serde"] }
+thiserror = "1"
+rand = "0.8"
+
+time = { version = "0.3.37", features = ["serde"] }
+
+serde = { version = "1.0.218", features = ["derive"] }
+
+[dev-dependencies]
+sqlx = { workspace = true, features = ["runtime-tokio"] }

examples/postgres/multi-database/accounts/Cargo.toml

@@ -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/multi-database/accounts/migrations/01_setup.sql

@@ -0,0 +1,10 @@
+create table account
+(
+    account_id    uuid primary key     default gen_random_uuid(),
+    email         text unique not null,
+    password_hash text        not null,
+    created_at    timestamptz not null default now(),
+    updated_at    timestamptz
+);
+
+select trigger_updated_at('account');

examples/postgres/multi-database/accounts/migrations/02_account.sql

@@ -0,0 +1,6 @@
+create table session
+(
+    session_token text primary key, -- random alphanumeric string
+    account_id    uuid        not null references account (account_id),
+    created_at    timestamptz not null default now()
+);

examples/postgres/multi-database/accounts/migrations/03_session.sql

@@ -0,0 +1,10 @@
+[common]
+database-url-var = "ACCOUNTS_DATABASE_URL"
+
+[macros.table-overrides.'account']
+'account_id' = "crate::AccountId"
+'password_hash' = "sqlx::types::Text<password_hash::PasswordHashString>"
+
+[macros.table-overrides.'session']
+'session_token' = "crate::SessionToken"
+'account_id' = "crate::AccountId"