PgQue CLAUDE.md

CLAUDE.md -- PgQue

Project

PgQue (pgque) -- PgQ Universal Edition. Zero-bloat PostgreSQL queue repackaged from PgQ for managed database environments. Repo: NikolayS/pgque.

Naming Convention

• pgque -- lowercase for schema, package names, CLI, repo, function prefixes
• PgQue -- capitalized form for prose, headings, README titles
• Mirrors PostgreSQL ecosystem convention (pgmq, pg_cron, psycopg)

Architecture

Two-layer design:

• pgque-core: Productization of PgQ (rename, PG14+ modernization, pg_cron, security hardening, single-file install). Mechanical transformation of ~4,028 lines of proven PL/pgSQL.
• pgque-api: Modern convenience layer (send/receive/ack/nack, DLQ, delayed delivery). New code (~1,500 lines) that must reduce cleanly to PgQ primitives.

See blueprints/SPECx.md for the full specification. See blueprints/SPEC.md for PgQ internals reference (rotation mechanics, snapshot isolation, batch_event_sql algorithm, dual-filter optimization).

Stack

• Pure SQL + PL/pgSQL (no extensions, no .control file)
• Anti-extension design: \i pgque.sql to install
• Works on RDS, Aurora, Cloud SQL, AlloyDB, Supabase, Neon, Crunchy Bridge
• Optional pg_cron for automated ticker and maintenance
• PostgreSQL 14+ required (uses pg_snapshot, xid8)

Style Rules

These rules are the source of truth for agentic engineering in this repo. Agents and AI coding tools must read this file before making changes.

SQL Style

• Follow the Postgres.AI SQL style guide: https://gitlab.com/postgres-ai/rules/-/blob/main/rules/development__db-sql-style-guide.mdc The rules below restate its core plus pgque-specific additions; on any conflict, this file wins.
• Prefer C-style /* ... */ block comments for anything spanning 2+ lines; use -- only for single-line comments.
• Comments state what the code cannot: a constraint, a non-obvious invariant, a concurrency hazard. Per-function headers and inline comments say that in 1-3 lines; do NOT write per-function essays or step-by-step narration alongside the code. One consolidated design-notes block per file (or per section) is encouraged for the bigger picture -- keep it C-style, and it may cite the spec (SPEC section 15).
• Do NOT cite user-story or requirement IDs (US-13.4, I2, G2) or other spec-process artifacts in code, and do not restate the spec at length. Longer rationale lives in blueprints/ and the specs; a short pointer (SPEC section 15, see blueprints/...) is fine.
• These style rules govern pgque-authored code only. The inherited PgQ engine (batch/tick/rotation and other repackaged PgQ internals) keeps its original comment style and is never restyled.
• Collapse single-argument keyword clauses onto one line (select 1, from t, where x = y, into v); expand only multi-argument clauses, one argument per line.
• Lowercase SQL keywords: select, create function, not SELECT, CREATE FUNCTION
• snake_case for all identifiers
• Schema-qualify all internal references: pgque.queue, not just queue
• Root SQL keywords must be left-aligned within the statement. Do not use decorative vertical indentation like select / from / where shifted by different amounts. This is non-negotiable for generated and source SQL.
• Put and / or at the start of continuation lines, aligned under the statement's where clause indentation.
• All SECURITY DEFINER functions MUST include SET search_path = pgque, pg_catalog
• Use xid8 for transaction ID columns, pg_snapshot for snapshot columns
• Use modern PG14+ function names: pg_current_xact_id() not txid_current()