db-analysis-lab

name	db-analysis-lab
description	Use when editing query lowering, parse/normalize, DB-assisted analysis, local PostgreSQL fixtures, provenance, nullability refinement, or integration tests that depend on Describe/RowDescription behavior. Trigger before making or validating DB-analysis changes.

DB Analysis Lab

Goal

Work safely on PostgreSQL-backed analysis paths without confusing static parsing, DB metadata, and semantic refinement.

Use this when

• Lowered SQL changes.
• Parser integration changes.
• Fingerprint or normalize logic changes.
• Describe / parameter / result metadata retrieval changes.
• LEFT JOIN / COALESCE / aggregate nullability logic changes.
• Local DB-backed integration tests need to run.

Standard local DB commands

Start PostgreSQL 17:

bash .agents/skills/db-analysis-lab/scripts/start_pg17.sh

Stop PostgreSQL 17:

bash .agents/skills/db-analysis-lab/scripts/stop_pg17.sh

Environment defaults

Assume these unless the repo overrides them:

• PGHOST=127.0.0.1
• PGPORT=55432
• PGUSER=sql_lint
• PGPASSWORD=sql_lint
• PGDATABASE=sql_lint

Rules

• Keep DB access read-only for analysis flows.
• Do not claim nullability from RowDescription alone.
• Distinguish parse failures from DB metadata failures.
• If a syntax feature is beyond PG17 / parser support, diagnose degrade behavior explicitly.
• When DB metadata is unavailable, return the correct degraded diagnostic rather than pretending analysis succeeded.

Validation checklist

• Is the lowered SQL stable and inspectable?
• Are query params positional and deterministic?
• Are parser / normalize / fingerprint outputs separated from DB metadata results?
• Is provenance capture limited to what the database actually returns?
• Are unsupported / timeout / metadata-unavailable cases tested?