68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
|
---
|
||
|
|
name: storage-postgres
|
||
|
|
description: "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.
|