CtrlK
BlogDocsLog inGet started
Tessl Logo

alonso-skills/postgres-writing-guidelines

Use when writing or reviewing PostgreSQL/PL-pgSQL, designing table schemas, writing functions and procedures, building migrations, defining domains, or architecting a Postgres application database. Also use when writing RAISE EXCEPTION patterns, BEFORE/AFTER triggers for cross-table constraints, base/subtype hierarchies, composite key designs, row-level security policies, or idempotent DDL scripts. If you are touching Postgres for an application database, use this skill. PostgreSQL-specific — examples will not run on other engines.

84

1.72x
Quality

89%

Does it follow best practices?

Impact

100%

1.72x

Average score across 2 eval scenarios

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

criteria.jsonevals/scenario-2/

{
  "context": "Tests whether the agent follows Postgres writing guidelines when implementing hierarchical composite keys, a relational job queue, a stored procedure with the 4-block structure, and an audit system. Covers SQLSTATE error codes, FOR UPDATE SKIP LOCKED, composite PKs, audit table shape, partial indexes, and trigger patterns.",
  "type": "weighted_checklist",
  "checklist": [
    {
      "name": "Composite PKs in hierarchy",
      "description": "The order_line table's primary key includes the parent order's key column(s) (i.e., composite PK), not a standalone BIGSERIAL or IDENTITY column",
      "max_score": 10
    },
    {
      "name": "No BIGSERIAL child keys",
      "description": "Child tables (order_line, shipment) do NOT use BIGSERIAL or IDENTITY as their sole primary key — they embed the parent PK",
      "max_score": 8
    },
    {
      "name": "FOR UPDATE SKIP LOCKED queue",
      "description": "The job/shipment queue claim uses SELECT ... FOR UPDATE SKIP LOCKED (not FOR UPDATE alone, not application-level polling with separate SELECT and UPDATE)",
      "max_score": 10
    },
    {
      "name": "Procedure 4-block structure",
      "description": "The order line creation procedure contains clearly identifiable guard/validation, state validation, apply (DML), and commit blocks in that order",
      "max_score": 8
    },
    {
      "name": "fn_assert_not_in_transaction",
      "description": "The procedure calls fn_assert_not_in_transaction() (or defines and uses a similar transaction-check guard) at the start of its body",
      "max_score": 6
    },
    {
      "name": "SQLSTATE error codes",
      "description": "RAISE EXCEPTION statements include USING ERRCODE = 'P0xxx' (e.g., P0001 for invalid input, P0002 for not found, P0005 for state conflict)",
      "max_score": 8
    },
    {
      "name": "Audit table shape",
      "description": "The audit table has before_data, after_data, and change_diff columns, all of type jsonb (not text, not hstore)",
      "max_score": 8
    },
    {
      "name": "GIN index on change_diff",
      "description": "A GIN index is created on the audit table's change_diff column",
      "max_score": 6
    },
    {
      "name": "AFTER trigger for audit",
      "description": "The audit trigger is an AFTER INSERT OR UPDATE OR DELETE trigger (not BEFORE), calling a trigger function named with the tg_ prefix",
      "max_score": 6
    },
    {
      "name": "Thin trigger body",
      "description": "The audit trigger's body delegates to a function (EXECUTE FUNCTION tg_...) rather than containing inline DML logic in the trigger definition itself",
      "max_score": 6
    },
    {
      "name": "DOMAIN types used",
      "description": "At least two custom DOMAIN types are defined and used in table column definitions instead of bare built-in types",
      "max_score": 6
    },
    {
      "name": "Partial index for queue",
      "description": "A partial index exists on the job/shipment queue table filtering on the pending status (e.g., WHERE status = 'pending') to optimize claim queries",
      "max_score": 6
    },
    {
      "name": "pr_ prefix on procedures",
      "description": "Stored procedures follow the pr_add_* / pr_modify_* / pr_remove_* naming convention with the pr_ prefix",
      "max_score": 4
    },
    {
      "name": "tg_ prefix on trigger functions",
      "description": "Trigger functions are named with the tg_ prefix (e.g., tg_order_line_audit), not generic names like audit_trigger or order_line_after_change",
      "max_score": 4
    },
    {
      "name": "Predicate constraint names",
      "description": "At least one FOREIGN KEY or CHECK constraint is named as a natural-language predicate sentence (e.g., order_line_belongs_to_order) rather than a mechanism name (e.g., fk_order_line_order)",
      "max_score": 4
    }
  ]
}

evals

SKILL.md

tile.json