Skip to content

Latest commit

 

History

History
115 lines (95 loc) · 6.09 KB

sqlx-metadata.md

File metadata and controls

115 lines (95 loc) · 6.09 KB

SQLx offline query metadata

TL;DR

  • Checked-in .sqlx/ metadata keeps normal builds credential-free and offline.
  • cargo xtask verify sqlx-metadata regenerates and checks metadata against only the explicitly authorized isolated local Compose PostgreSQL profile.
  • The canonical action checks SQLx CLI 0.9.0, assembles both adapters' schemas, and fails if generated .sqlx/ metadata differs from the working tree.
  • This proves query/schema freshness, not runtime transaction behavior or a production migration procedure.

Offline build contract

The tooling worker also checks its authorization, dispatch claim and fenced receipt statements with macros. Metadata assembly applies its disposable process-schema.sql after adapter migrations. Fresh metadata databases are required; these fixture tables are not product migrations.

P08 also assembles simulation-postgres/migrations/0001_account_admission.sql for checked account admission queries. Its capability-local Clippy policy rejects runtime SQL and unchecked macros; private proof fixture DDL remains tooling-only.

All production inbox and outbox SQL uses checked SQLx query macros. Outbox enqueue and replay identity lookups use sqlx::query!; lease transitions and the audited replay CTE use readable capability-owned query_file! / query_file_as! statements. All eight outbox statements participate in the same metadata workflow. The workspace commits their .sqlx/ metadata, and .cargo/config.toml defaults to SQLX_OFFLINE=true. Ordinary cargo check, cargo build, Clippy, and tests therefore need neither PostgreSQL nor a .env file. The database-backed CI gate regenerates the metadata and rejects any diff; runtime PostgreSQL conformance tests remain a separate behavioral check.

The OCI builder also copies .cargo/config.toml and the committed .sqlx/query-*.json files before compiling workspace binaries, and explicitly sets SQLX_OFFLINE=true. Context rules re-exclude directory children before allowing the exact config/cache files, so Cargo credentials and non-query siblings stay excluded. No .env file or database URL is required. The default image contract sensor and mutation tests protect this ordering/context contract; container smoke tests exercise the real build. Adding a tooling binary with adapter dependencies must not make image builds require a live database.

The outbox's capability-local clippy.toml rejects runtime query constructors and unchecked macros in production. Isolated PostgreSQL conformance fixtures have explicit test-only exemptions for schema administration and fault injection. cargo xtask verify --check sqlx-query-policy runs real offline Clippy fixtures: a checked macro must compile, while prohibited APIs must fail with the expected lint, including renamed imports. This T2 check runs on both CI platforms; it does not connect to PostgreSQL or replace the T3 metadata freshness and runtime conformance proofs.

Schema assembly and isolation

Assembly also includes crates/market-data-postgres/migrations for durable acquisition admission/accounting and terminal receipt/head/version statements (M03-PR9/PR10). Compose existing inbox/outbox tables in the same private schema.

Metadata must be generated against a fresh, isolated PostgreSQL database with both adapters' checked-in tables in the default public schema. The two migration directories both start at version 1, so SQLx CLI's shared migration ledger can track only one of them in a single schema. Run the outbox migrations through SQLx CLI and apply the inbox SQL files directly with psql, in lexical order. This is a metadata-only schema assembly, not the production migration procedure. Service composition roots remain responsible for deployment migrations and schema ownership.

The action also applies the tooling-only crates/event-spine-conformance/fixtures/process-schema.sql before preparing all targets. This describes the checked synthetic acceptance, aggregate-lock, semantic-receipt and revision-update statements; it does not add conformance tables to any product service migration. Runtime process proofs create only the table owned by each isolated service schema.

The action refuses any DATABASE_URL other than the exact checked-in local Compose URI. It also requires SQLX_OFFLINE=false and explicit EDGEAGENT_SQLX_METADATA_LOCAL=1 authorization before changing schema or generating metadata. These checks do not prove the database is fresh: use a fresh local profile without retained or drifted tables. Never target a shared or production database.

Canonical verification command

On the local Compose platform, run these commands from the workspace root in a POSIX shell. The example credentials are public local-only fixtures.

make local-up
cargo install sqlx-cli --version '=0.9.0' --no-default-features --features postgres,rustls
export DATABASE_URL='postgresql://edgeagent:edgeagent-local-postgres@127.0.0.1:5432/edgeagent'
export SQLX_OFFLINE=false
export EDGEAGENT_SQLX_METADATA_LOCAL=1
cargo xtask verify sqlx-metadata

The action launches fixed argument vectors and pipes migration bytes directly into Compose psql.

The action probes cargo sqlx --no-dotenv --version, which reports sqlx-cli-sqlx 0.9.0. The standalone sqlx --version reports sqlx-cli 0.9.0; these are different command banners for the same pinned package. The probe requires a successful exit and the exact Cargo-plugin banner, ignores ambient .env files, and rejects other versions. Failure diagnostics distinguish an unsuccessful probe from an unexpected banner without printing raw command output.

Metadata changes and evidence boundaries

Review and commit every added, changed, or removed .sqlx/query-*.json with the query or migration change. Never use production for metadata generation or commit a real database URL. The command intentionally fails after generation when metadata changes: review and commit the changes, then rerun it. CI invokes the same canonical action and checks for an exactly empty git status --porcelain -- .sqlx result. Runtime transaction, quarantine, replay, and fencing guarantees remain separate local-platform conformance checks.