fix(macros): smarter .env loading, caching, and invalidation (#4053)

* fix(macros): smarter `.env` loading, caching, and invalidation

* feat(mysql): test `.env` loading in CI

* feat(postgres): test `.env` loading in CI

* feat(macros): allow `DATABASE_URL` to be empty

* fix(examples/postgres): make `cargo-sqlx` executable

* fix(examples/postgres): `cargo sqlx` invocation

* feat(examples/postgres): check offline prepare on more examples

* fix(examples/postgres): the name of this step

* fix(cli): don't suppress error from `dotenv()`

* fix(ci/examples/postgres): don't use heredoc in this step

* fix(ci/examples/postgres): multi-tenant

* fix(ci/examples/sqlite): test `.env` loading

* chore: add CHANGELOG entry

Author: abonander

.github/workflows/examples.yml

@@ -26,22 +26,27 @@ jobs:
       - run: >
           cargo build
           -p sqlx-cli
-          --bin sqlx
           --release
           --no-default-features
           --features mysql,postgres,sqlite,sqlx-toml
 
       - uses: actions/upload-artifact@v4
         with:
           name: sqlx-cli
-          path: target/release/sqlx
+          path: |
+            target/release/sqlx
+            target/release/cargo-sqlx
 
   mysql:
     name: MySQL Examples
     runs-on: ubuntu-latest
     needs: sqlx-cli
     timeout-minutes: 30
 
+    strategy:
+      matrix:
+        offline: ['', 'offline']
+
     services:
       mysql:
         image: mysql:latest
@@ -60,7 +65,7 @@ jobs:
 
       - run: |
           ls -R /home/runner/.local/bin
-          chmod +x /home/runner/.local/bin/sqlx
+          chmod +x /home/runner/.local/bin/sqlx /home/runner/.local/bin/cargo-sqlx
           echo /home/runner/.local/bin >> $GITHUB_PATH
           sleep 10
 
@@ -77,9 +82,32 @@ jobs:
           DATABASE_URL: mysql://root:password@localhost:3306/todos?ssl-mode=disabled
         run: sqlx db setup
 
+      - name: Todos (Prepare)
+        if: ${{ matrix.offline }}
+        working-directory: examples/mysql/todos
+        env:
+          DATABASE_URL: mysql://root:password@localhost:3306/todos?ssl-mode=disabled
+        run: cargo sqlx prepare
+
+      - name: Todos (Check Offline)
+        if: ${{ matrix.offline }}
+        run: |
+          cargo clean -p sqlx-example-mysql-todos
+          cargo check -p sqlx-example-mysql-todos
+
+      - name: Todos (Prepare from .env)
+        if: ${{ matrix.offline }}
+        working-directory: examples/mysql/todos
+        run: |
+          echo "DATABASE_URL=mysql://root:password@localhost:3306/todos?ssl-mode=disabled" > .env
+          cargo clean -p sqlx-example-mysql-todos
+          cargo sqlx prepare
+          rm .env
+
       - name: Todos (Run)
         env:
           DATABASE_URL: mysql://root:password@localhost:3306/todos?ssl-mode=disabled
+          SQLX_OFFLINE: ${{ matrix.offline == 'offline' }}
         run: cargo run -p sqlx-example-mysql-todos
 
   postgres:
@@ -88,6 +116,10 @@ jobs:
     needs: sqlx-cli
     timeout-minutes: 30
 
+    strategy:
+      matrix:
+        offline: ['', 'offline']
+
     services:
       postgres:
         image: postgres:latest
@@ -106,6 +138,7 @@ jobs:
       - run: |
           ls -R /home/runner/.local/bin
           chmod +x $HOME/.local/bin/sqlx
+          chmod +x $HOME/.local/bin/cargo-sqlx
           echo $HOME/.local/bin >> $GITHUB_PATH
           sleep 10
 
@@ -120,14 +153,32 @@ jobs:
           DATABASE_URL: postgres://postgres:password@localhost:5432/axum-social
         run: sqlx db setup
 
-      - name: Axum Social with Tests (Check)
+      # Test `cargo sqlx prepare` setting `DATABASE_URL` both directly and in `.env`
+      # This doesn't need to be done for every single example here, but should at least cover potential problem cases.
+      - name: Axum Social with Tests (Prepare)
+        if: ${{ matrix.offline }}
         env:
           DATABASE_URL: postgres://postgres:password@localhost:5432/axum-social
-        run: cargo check -p sqlx-example-postgres-axum-social
+        run: cargo sqlx prepare -- -p sqlx-example-postgres-axum-social
+
+      - name: Axum Social with Tests (Check Offline)
+        if: ${{ matrix.offline }}
+        run: |
+          cargo clean -p sqlx-example-postgres-axum-social
+          cargo check -p sqlx-example-postgres-axum-social
+
+      - name: Axum Social with Tests (Prepare from .env)
+        if: ${{ matrix.offline }}
+        run: |
+          echo "DATABASE_URL=postgres://postgres:password@localhost:5432/axum-social" > .env
+          cargo clean -p sqlx-example-postgres-axum-social
+          cargo sqlx prepare -- -p sqlx-example-postgres-axum-social
+          rm .env
 
       - name: Axum Social with Tests (Test)
         env:
           DATABASE_URL: postgres://postgres:password@localhost:5432/axum-social
+          SQLX_OFFLINE: ${{ matrix.offline == 'offline' }}
         run: cargo test -p sqlx-example-postgres-axum-social
 
       # The Chat example has an interactive TUI which is not trivial to test automatically,
@@ -190,11 +241,47 @@ jobs:
           (cd payments && sqlx db setup)
           sqlx db setup
 
+      - name: Multi-Database (Prepare)
+        if: ${{ matrix.offline }}
+        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 clean -p sqlx-example-postgres-multi-database-accounts
+            cargo clean -p sqlx-example-postgres-multi-database-payments
+            cargo clean -p sqlx-example-postgres-multi-database
+            # should include -accounts and -payments
+            cargo sqlx prepare -- -p sqlx-example-postgres-multi-database
+
+      - name: Multi-Database (Check Offline)
+        if: ${{ matrix.offline }}
+        run: |
+          cargo clean -p sqlx-example-postgres-multi-database
+          cargo check -p sqlx-example-postgres-multi-database
+
+      - name: Multi-Database (Prepare from .env)
+        if: ${{ matrix.offline }}
+        run: |
+          # Tried to get this to work with heredocs but had trouble writing tabs in YAML
+          echo 'DATABASE_URL=postgres://postgres:password@localhost:5432/multi-database' >.env
+          # Important: append, don't truncate
+          echo 'ACCOUNTS_DATABASE_URL=postgres://postgres:password@localhost:5432/multi-database-accounts' >> .env
+          echo 'PAYMENTS_DATABASE_URL=postgres://postgres:password@localhost:5432/multi-database-payments' >> .env
+          
+          cargo clean -p sqlx-example-postgres-multi-database-accounts
+          cargo clean -p sqlx-example-postgres-multi-database-payments
+          cargo clean -p sqlx-example-postgres-multi-database
+          cargo sqlx prepare -- -p sqlx-example-postgres-multi-database
+          
+          rm .env
+
       - 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
+          SQLX_OFFLINE: ${{ matrix.offline == 'offline' }}
         run: cargo run -p sqlx-example-postgres-multi-database
 
       - name: Multi-Tenant (Setup)
@@ -206,9 +293,38 @@ jobs:
           (cd payments && sqlx migrate run)
           sqlx migrate run
 
+      - name: Multi-Tenant (Prepare)
+        if: ${{ matrix.offline }}
+        env:
+          DATABASE_URL: postgres://postgres:password@localhost:5432/multi-tenant
+        run: |
+          cargo clean -p sqlx-example-postgres-multi-tenant-accounts
+          cargo clean -p sqlx-example-postgres-multi-tenant-payments
+          cargo clean -p sqlx-example-postgres-multi-tenant
+          # should include -accounts and -payments
+          cargo sqlx prepare -- -p sqlx-example-postgres-multi-tenant
+
+      - name: Multi-Tenant (Check Offline)
+        if: ${{ matrix.offline }}
+        run: cargo check -p sqlx-example-postgres-multi-tenant
+
+      - name: Multi-Tenant (Prepare from .env)
+        if: ${{ matrix.offline }}
+        run: |
+          echo "DATABASE_URL=postgres://postgres:password@localhost:5432/multi-tenant" > .env
+          
+          cargo clean -p sqlx-example-postgres-multi-tenant-accounts
+          cargo clean -p sqlx-example-postgres-multi-tenant-payments
+          cargo clean -p sqlx-example-postgres-multi-tenant
+          # should include -accounts and -payments
+          cargo sqlx prepare -- -p sqlx-example-postgres-multi-tenant
+          
+          rm .env
+
       - name: Multi-Tenant (Run)
         env:
           DATABASE_URL: postgres://postgres:password@localhost:5432/multi-tenant
+          SQLX_OFFLINE: ${{ matrix.offline == 'offline' }}
         run: cargo run -p sqlx-example-postgres-multi-tenant
 
       - name: Preferred-Crates (Setup)
@@ -217,7 +333,7 @@ jobs:
           DATABASE_URL: postgres://postgres:password@localhost:5432/preferred-crates
         run: sqlx db setup
 
-      - name: Multi-Tenant (Run)
+      - name: Preferred-Crates (Run)
         env:
           DATABASE_URL: postgres://postgres:password@localhost:5432/preferred-crates
         run: cargo run -p sqlx-example-postgres-preferred-crates
@@ -275,7 +391,28 @@ jobs:
           DATABASE_URL: sqlite://todos.sqlite
         run: sqlx db setup --source=examples/sqlite/todos/migrations
 
+      - name: Todos (Prepare)
+        if: ${{ matrix.offline }}
+        env:
+          DATABASE_URL: sqlite://todos.sqlite
+        run: cargo sqlx prepare -- -p sqlx-example-sqlite-todos
+
+      - name: Todos (Check Offline)
+        if: ${{ matrix.offline }}
+        run: |
+          cargo clean -p sqlx-example-sqlite-todos
+          cargo check -p sqlx-example-sqlite-todos
+
+      - name: Todos (Prepare from .env)
+        if: ${{ matrix.offline }}
+        run: |
+          echo "DATABASE_URL=sqlite://todos.sqlite" > .env
+          cargo clean -p sqlx-example-sqlite-todos
+          cargo sqlx prepare -- -p sqlx-example-sqlite-todos
+          rm .env
+
       - name: TODOs (Run)
         env:
           DATABASE_URL: sqlite://todos.sqlite
+          SQLX_OFFLINE: ${{ matrix.offline == 'offline' }}
         run: cargo run -p sqlx-example-sqlite-todos

CHANGELOG.md

@@ -43,12 +43,21 @@ This section will be replaced in subsequent alpha releases. See the Git history
     * Significant changes to the `Migrate` trait
     * `sqlx::migrate::resolve_blocking()` is now `#[doc(hidden)]` and thus SemVer-exempt.
 
+### Fixed
+
+* [[#4053]]: fix(macros): smarter `.env` loading, caching, and invalidation [[@abonander]]
+  * Additional credit to [[@AlexTMjugador]] ([[#4018]]) and [[@Diggsey]] ([[#4039]]) for their proposed solutions
+    which served as a useful comparison.
+
 [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/3821
 [#3383]: https://github.com/launchbadge/sqlx/pull/3383
+[#4018]: https://github.com/launchbadge/sqlx/pull/4018
+[#4039]: https://github.com/launchbadge/sqlx/pull/4039
+[#4053]: https://github.com/launchbadge/sqlx/pull/4053
 
 ## 0.8.6 - 2025-05-19
 
@@ -2951,3 +2960,4 @@ Fix docs.rs build by enabling a runtime feature in the docs.rs metadata in `Carg
 [@dyc3]: https://github.com/dyc3
 [@ThomWright]: https://github.com/ThomWright
 [@duhby]: https://github.com/duhby
+[@AlexTMjugador]: https://github.com/AlexTMjugador