db-function-contract

Define PostgreSQL function contracts for model CRUD commands with JSONB payloads and envelopes.

1|Updated Jun 25, 2026
One-click install
npx skills add https://github.com/IgorAIvanov/altera03 --skill db-function-contract-igoraivanov
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: db-function-contract
Source: https://github.com/IgorAIvanov/altera03/tree/main/skills/src/db-function-contract
Command: npx skills add https://github.com/IgorAIvanov/altera03 --skill db-function-contract-igoraivanov

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Backend models need consistent PostgreSQL functions for list, get, save, delete, and lookup operations, but hand-writing them leads to inconsistent signatures, drifting response shapes, and duplicated SQL. This Skill standardizes the function contract so every model command accepts a user id plus a JSONB payload and returns a stable JSONB envelope. ## Core Features & Use Cases - Standard command contract: Defines naming ({schema}.{model}_{command}), signatures, and a fixed response envelope with item, rows, options, totals, extra, messages, and meta keys. - Generated CRUD workflow: Standard list/get/save/delete/lookup functions are generated from the model's TypeBox schema and manifest via deno task sql:gen, with per-function overrides in db/<model>.custom.sql. - Document and register semantics: Covers posting/unposting, soft-delete marking, related-document trees, compound and off-balance journal entries, and localized user-facing messages via @[key] markers. - Use Case: When adding a new catalog or document model, use this Skill to write only the schema, manifest, and DDL, then generate the five standard functions and add custom SQL only for non-standard logic. ## Quick Start Describe the model and the shape of its list, item, options, and save data so the Skill can define the PostgreSQL function contract for it.

Frequently Asked Questions about db-function-contract

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I define PostgreSQL functions for model CRUD operations?

Name functions as {schema}.{model}_{command} with a user_id bigint first parameter and a JSONB payload second, returning JSONB. Standard list, get, save, delete, and lookup functions are generated from the model's TypeBox schema rather than written by hand.

What response format should PostgreSQL model functions return?

Return a JSONB envelope with ok, data, messages, and meta keys. The data object always contains item, rows, options, totals, and extra, using null or empty values for keys a command does not use, so the client can rely on every key being present.

When should I write custom SQL instead of using generated CRUD functions?

Write custom SQL only for non-standard logic, placed in db/<model>.custom.sql. A function defined there overrides the generated one of the same name while the other four standard commands remain generated.

Why does a not-null constraint fail when saving through the generated save function?

The generated save builds its MERGE source from jsonb_to_recordset, so a key absent from the payload arrives as explicit null and does not trigger the column default. Give the field a default in the TypeBox schema so it is always sent.

Does delete physically remove records in this contract?

No, delete marks the record by setting is_deleted to true, and undelete clears the mark. List still shows marked records while lookup hides them; physical deletion is a separate operation that must check references.

How are user-facing error messages handled in SQL functions?

Messages a person reads are emitted as named markers like @[invoice.postNoAmount] with an optional JSON object of substitutions, which the client translates. The key must exist in every locale file or a test fails.