opencode-workflow/skills/storage-postgres/SKILL.md

name	description
storage-postgres	PostgreSQL-specific code design reference for the Code Design Agent. Load only when the architecture or repository indicates PostgreSQL. Covers schema-to-code translation, migrations, repository patterns, transactions, and operational safeguards.

This skill provides PostgreSQL-specific guidance for code-level design.

Announce at start: "I'm using the storage-postgres skill to apply PostgreSQL-specific code design conventions."

When To Load

Load this skill only when one or more of the following is true:

• The architecture explicitly names PostgreSQL or Postgres
• The repository uses PostgreSQL drivers, migrations, or connection strings
• The architecture relies on relational constraints, joins, and transactional behavior that clearly target PostgreSQL

Do not load this skill for document or wide-column databases.

Purpose

Translate logical relational schema decisions into PostgreSQL-oriented code design: migrations, repository boundaries, transaction handling, SQL conventions, and model mapping.

Postgres Design Rules

1. Treat the Architect's schema as the source of truth for tables, columns, constraints, and indexes
2. Keep migration design forward-safe and rollback-aware
3. Prefer explicit SQL and query ownership over hidden ORM behavior unless the codebase already standardizes on an ORM
4. Use transactions only where business invariants require them
5. Make idempotency and uniqueness constraints explicit in both schema and repository behavior

Migration Guidance

• Pick one migration tool and standardize on it
• Use timestamped migration names
• Separate schema changes from data backfills when the rollout risk is different
• Call out zero-downtime concerns explicitly for index creation, column backfills, and large table rewrites

Repository Guidance

• Repositories should own SQL for a bounded aggregate or feature slice
• Document read vs write methods separately when query complexity differs
• Make optimistic locking, unique constraint handling, and pagination strategy explicit
• Document how transactions flow across repositories when multiple tables participate in one business operation

Model Guidance

• Keep persistence structs aligned with table columns and nullability
• Document how nullable columns map into the chosen language types
• Make timestamp and soft-delete conventions explicit
• If JSONB is used, document which fields remain schemaless and why

Query Guidance

• Prefer parameterized queries only
• Define pagination style explicitly: keyset preferred for high-scale ordered lists, offset only when acceptable
• Document index assumptions for all critical queries
• Surface hot queries and expected access patterns in the code design document

Operational Safeguards

• Note connection pool sizing expectations
• Note migration ordering dependencies
• Note any data retention, archival, or partitioning implications from the architecture

Output Constraint

This skill is reference-only. It does not create files by itself. Apply its guidance inside docs/code-design/{date}-{feature}.md only.