How to Execute Tests Against a Local Postgres Database Without SQLX_OFFLINE in the Macro Repository

Use the just setup_test_envs and just initialize_dbs commands to spin up a Docker-based PostgreSQL instance, then run cargo test without setting SQLX_OFFLINE=true.

The macro-inc/macro repository provides built-in tooling that eliminates the need for SQLx offline mode during integration testing. By orchestrating a real PostgreSQL container locally, you enable SQLx to validate queries against live schema — catching mismatches that offline mode would miss.

Why Avoid SQLX_OFFLINE for Integration Tests

SQLX_OFFLINE=true tells the SQLx query checker to use cached metadata instead of connecting to a database. While this speeds up CI builds and enables offline compilation, it masks schema drift and query errors that only appear when executing against real data. The Macro project explicitly discourages this approach for database-backed test suites.

In docs/CLOUD_STORAGE.md at line 23, the documentation states that SQLX_OFFLINE should NOT be set when running tests for crates that interact with PostgreSQL.

Prerequisites

Before starting, ensure you have:

• Docker and Docker Compose installed
• just command runner (cargo install just)
• Rust toolchain with cargo

Step-by-Step: Local PostgreSQL Test Setup

1. Start the Test Environment

The just setup_test_envs command creates .env configuration files and launches the Docker-based PostgreSQL container.

just setup_test_envs

This target is defined in tooling/just/rust.just and orchestrates services defined in docker/docker-compose.yml.

2. Initialize the Databases

Apply all migrations to the fresh PostgreSQL instance:

just initialize_dbs

This step is chained automatically in CI workflows. In tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs at line 264, the "prepare tests" step runs exactly this sequence:

// From code_check_cloud_storage.rs — step "prepare tests"
.just setup_test_envs && just initialize_dbs

3. Run Tests Without SQLX_OFFLINE

With the database ready, execute tests normally. Do not set SQLX_OFFLINE — SQLx will connect to the live container and perform compile-time query verification against the actual schema.

cargo test

For specific crate testing:

cargo test -p document_storage_service

Complete Command Examples

Run document-storage service tests only:

just setup_test_envs && just initialize_dbs && cargo test -p document_storage_service

Execute the full workspace test suite using the project's just target:

just setup_test_envs && just initialize_dbs && just test

How the Test Environment Works

Component	File Path	Purpose
Environment setup	tooling/just/rust.just	Defines setup_test_envs target
Docker orchestration	docker/docker-compose.yml	Provides PostgreSQL service container
CI workflow reference	tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs	Demonstrates proper test preparation sequence
Documentation	docs/CLOUD_STORAGE.md	Lines 21-23 contain setup instructions and SQLX_OFFLINE warning

The workflow in code_check_cloud_storage.rs validates that this approach works in production CI pipelines, not just local development.

Troubleshooting Common Issues

• Connection refused: Ensure just setup_test_envs completed successfully and the Docker container is healthy (docker ps).
• Migration failures: Run just initialize_dbs a second time — it is idempotent for existing databases.
• Query compilation errors: Verify SQLX_OFFLINE is unset in your environment (echo $SQLX_OFFLINE should return nothing).

Summary

• Use just setup_test_envs to create .env files and start PostgreSQL in Docker
• Run just initialize_dbs to apply all schema migrations
• Execute cargo test without SQLX_OFFLINE=true to enable live query validation
• Reference docs/CLOUD_STORAGE.md for authoritative project-specific guidance

This workflow ensures your tests exercise real database behavior while maintaining reproducible, automated setup through the just task runner.

Frequently Asked Questions

What happens if I accidentally set SQLX_OFFLINE=true during tests?

SQLx will use cached query metadata and skip database connection. Tests may pass despite schema mismatches, producing false confidence. The Macro repository explicitly warns against this in docs/CLOUD_STORAGE.md line 23.

Can I use this setup for continuous integration?

Yes. The same commands are used in the official CI workflow at tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs line 264, proving this approach is production-validated for automated pipelines.

How do I reset the test database between test runs?

The just initialize_dbs command is idempotent — re-running it applies any new migrations without destroying existing data. For a complete reset, run docker compose -f docker/docker-compose.yml down -v to remove the PostgreSQL volume, then repeat the setup steps.

Why does SQLX_OFFLINE exist if the project discourages it?

Offline mode serves valid purposes: enabling builds without database access, accelerating compilation in isolated environments, and supporting air-gapped deployments. The Macro project simply recommends against it for integration testing where query correctness against real schema is paramount.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}