db-designlisted

# Database Design — PostgreSQL First A practical design playbook for the project's stack: PostgreSQL as the system of record, accessed by the Go+Fiber business core and the Python+FastAPI AI adapter, with hexagonal repositories isolating the rest of the codebase from schema specifics. ## When to Use This Skill - Modeling the schema for a new bounded context (orders, users, lessons, payments). - Adding a column or table that will see growth. - Choosing PK / FK shapes (UUID? bigint? prefixed string?). - Designing indexes after seeing query patterns or EXPLAIN output. - Writing migrations that touch live data (never just on a fresh DB). - Picking ORM (sqlc / GORM / SQLAlchemy / Drizzle) vs raw SQL for a feature. - Deciding on soft delete vs hard delete + audit table. - Evaluating Redis (cache/queue) vs Postgres (LISTEN/NOTIFY, advisory locks) for a side-channel. Skip when: prototyping with a sqlite that will be thrown away. Use this skill before the throw-away gets promoted. ## The Three Rules 1. **Constraints in the database, not the application.** `NOT NULL`, `CHECK`, `UNIQUE`, `FOREIGN KEY` enforced by Postgres survive bugs in the app, replays of stale code, and direct DBA fixes. Application-only invariants are constantly violated by accident. 2. **Migrations are forward-only and additive.** Never drop a column the same release you stop writing to it. Two-phase: stop writing → wait → drop. See [references/migration-discipline.md](references/migration-discipline.md). 3.