pg_exporter: Instructions file for Codex

AGENTS.md

These guidelines are mandatory for contributors and for any AI coding agent operating in this repository. The goal is to land changes safely, keep security invariants intact, and keep the workspace consistent over time.

Project Shape

• This repository is a single Rust crate, not a Cargo workspace.
• Prefer cargo test over cargo test --workspace.
• The main entrypoint is pg_exporter, a PostgreSQL metrics exporter written in Rust.

First Steps

Before making non-trivial changes:

1. Read CONTRIBUTING.md.
2. Read tests/TESTING.md if touching collectors or tests.
3. Check .justfile for the supported local workflows.

DevPod Workflow (Preferred)

• Prefer the compose-based DevPod environment documented in CONTRIBUTING.md and .devcontainer/README.md for development and database-backed validation.
• Start or refresh it with scripts/dev-up, then enter it with scripts/dev-ssh. For non-interactive commands, use devpod ssh pg-exporter --workdir /workspaces/pg_exporter --command '<command>'.
• Run setup checks, Rust tests, and collector integration tests inside DevPod so they use the bundled postgres service with pg_stat_statements preloaded.
• Do not start a second host-side PostgreSQL container when the DevPod services are available.

Local Commands

• Start local PostgreSQL: just postgres
• Verify the local test database: ./scripts/setup-local-test-db.sh
• Run the standard local validation flow: just test
• Formatting is required: cargo fmt --all -- --check
• Clippy is required: cargo clippy --all-targets --all-features
• Run tests directly when the local DB is already ready:
  • PG_EXPORTER_DSN="postgresql://postgres:postgres@localhost:5432/postgres" cargo test

These are not advisory commands. A change is not ready for review if formatting, Clippy, or tests fail locally.

Test Database Rules

• Tests must run against local PostgreSQL: localhost:5432 for the host workflow, or the compose postgres:5432 service inside DevPod.
• Do not run the test suite against a remote PG_EXPORTER_DSN.
• The local PostgreSQL instance must have pg_stat_statements preloaded and the extension created.
• Rootless Podman is used in local workflows. Podman networking may invoke pasta; errors from pasta are container-networking failures, not Rust test failures by themselves.