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

> Execute tests against a local Postgres database without SQLX_OFFLINE. Spin up Docker Postgres with just setup_test_envs and just initialize_dbs, then run cargo test.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/macro-inc/macro/blob/main/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.

```bash
just setup_test_envs

```

This target is defined in `tooling/just/rust.just` and orchestrates services defined in [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml).

### 2. Initialize the Databases

Apply all migrations to the fresh PostgreSQL instance:

```bash
just initialize_dbs

```

This step is chained automatically in CI workflows. In [`tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs) at line 264, the "prepare tests" step runs exactly this sequence:

```rust
// 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.

```bash
cargo test

```

For specific crate testing:

```bash
cargo test -p document_storage_service

```

## Complete Command Examples

Run document-storage service tests only:

```bash
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:

```bash
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`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) | Provides PostgreSQL service container |
| CI workflow reference | [`tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs) | Demonstrates proper test preparation sequence |
| Documentation | [`docs/CLOUD_STORAGE.md`](https://github.com/macro-inc/macro/blob/main/docs/CLOUD_STORAGE.md) | Lines 21-23 contain setup instructions and `SQLX_OFFLINE` warning |

The workflow in [`code_check_cloud_storage.rs`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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.