PostgreSQL SQLSTATE Atlas

This repository is the Hugo + OINK site for a bilingual, source-backed reference to PostgreSQL SQLSTATE values. English is the default language and Simplified Chinese is paired at /zh/; an entry such as 23505 renders at /23505/ and /zh/23505/.

The site keeps one page per SQLSTATE. Class, topic, common-code, and version views are indexes that point back to that page. Structured identity and version facts belong in the generated catalogue; Markdown owns reader-facing explanation and its translation. Research notes and unverified links stay outside public content.

Final handoff status: all 263 bilingual SQLSTATE pairs are accepted (82 full, 181 reference, 0 stub), with 263 evidence records and four accepted guides. See reports/ACCEPTANCE.md for the reproducible build, checker, projection, print, browser, and smoke evidence.

Commands

make fetch          refresh explicitly frozen source inputs
make catalogue      extract and combine local source snapshots
make generate       create permitted pages and derived indexes (EXCLUDE_CODES=... can protect an active author batch)
make check          run offline site, pairing, route, and protection checks
make verify-smoke   run one lightweight case (forwarded aliases below)
make verify         run the configured verification cases
make build          strict production Hugo build (runs `check` by default)
make serve          local preview at http://localhost:1314/ (PORT overrides)

Runtime aliases are forwarded to scripts/verify_cases.py with shell-safe quoting: SQLSTATE/VERIFY_SQLSTATE, VERSION/VERIFY_VERSION, IMAGE/VERIFY_IMAGE, CASE/VERIFY_CASE, ONLY/VERIFY_ONLY, SKIP_PG10/VERIFY_SKIP_PG10, and RUN_ID/VERIFY_RUN_ID. A caller may also supply a complete VERIFY_ARGS list. For example, make verify-smoke IMAGE=postgres:18.6 runs one explicit disposable official image. The runner rejects --version with --image, and rejects either explicit target with --only or --skip-pg10. RUN_ID may contain only letters, numbers, dot, underscore, and hyphen. make build CHECK=0 is reserved for CI after a separate make check; ordinary local builds should keep the default dependency.

The formal OINK dependency is github.com/pgsty/oink v1.0.0, with checksums in go.sum. The selected release resolves remotely to commit 11b0d86ca6000a24726d6773eb67ba428b21f433; local replacement paths are not used for a formal build.

Site checks require Python 3 and PyYAML==6.0.3 to parse front matter. Hugo Extended 0.165.0 and Go 1.27.x are pinned in CI. The formal OINK module is resolved from its tagged release; the repository does not use a local module replacement. Runtime verification additionally requires Docker and psycopg[binary]==3.3.5 when a disposable PostgreSQL target is selected.

Layout

• content/docs/ — bilingual home and index pages; SQLSTATE entries are flat siblings and are added only after the shared schema is frozen.
• sources/, raw/, data/, evidence/ — source and facts owned by the catalogue pipeline.
• static/data/ — curated public catalogue, compact SQLSTATE/version lookup, class/version, evidence, and case JSON; acquisition trees and local result paths are excluded.
• verify/ — executable cases and results owned by calibration.
• scripts/ — explicit source, generation, site contract, and verification entry points.
• reports/ — evidence-backed progress and acceptance records.

The original planning and reference files under references/ are preserved as read-only material. Do not edit them as part of site authoring.

Source updates are explicit and staged: inspect or refresh the frozen inputs with make fetch, derive the catalogue with make catalogue, review the resulting evidence and authored pages, then run make generate, make check, and make build. Generation owns marked fact/index regions and missing stubs; it does not overwrite authored prose or evidence. If a generated facts block changes, generation marks both language pages pending, recomputes the English content hash, and preserves the Chinese translation.source_rev so the checker reports the required translation review instead of silently claiming a synchronized translation. Runtime results are kept under verify/results/ and are never promoted into authored evidence by the site build. Normal checks are offline and do not query release servers.

The normal CI workflow has separate offline checks/build, a small natural 23505 Docker smoke, and an opt-in workflow_dispatch heavy verification path. Both runtime jobs upload their result directories even when a runner fails. The smoke validates the invocation contract; it does not replace the retained version matrix or establish coverage for every SQLSTATE.

Source Markdown uses a fixed relative link contract for curated per-code projections: English pages write ../data/evidence/23505.json and ../data/cases/23505.json; Chinese pages write ../../data/evidence/23505.json and ../../data/cases/23505.json. These resolve to /data/... at the root and /sub/data/... under a /sub/ base. Agent/standalone exports should preserve these source-relative links or emit the matching rendered base URL. Repository-local paths such as ../../evidence/ and verify/results/ are not public routes.