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

.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

Cargo.toml

@@ -190,6 +190,7 @@ uuid = "1.1.2"
 # Common utility crates
 cfg-if = "1.0.0"
 dotenvy = { version = "0.15.0", default-features = false }
+thiserror = { version = "2.0.17", default-features = false, features = ["std"] }
 
 # Runtimes
 [workspace.dependencies.async-global-executor]

sqlx-cli/src/lib.rs

@@ -49,7 +49,11 @@ pub fn maybe_apply_dotenv() {
         return;
     }
 
-    dotenvy::dotenv().ok();
+    if let Err(e) = dotenvy::dotenv() {
+        if !e.not_found() {
+            eprintln!("Warning: error loading `.env` file: {e:?}");
+        }
+    }
 }
 
 pub async fn run(opt: Opt) -> anyhow::Result<()> {