digital-psychology/.ai/database.md

Database — Golden Rules

Schema source of truth for P1 tables: domain/erd.md.

Naming

• snake_case only for tables and columns.
• Forbidden prefixes: tbl_, t_.

Required columns on business tables

id
created_at
updated_at
deleted_at

Types

• Prefer bounded varchar(n).
• TEXT only when necessary.
• Timestamps: timestamptz.

Keys & indexes

• Every foreign key indexed.
• Unique business keys enforced with UNIQUE.

Migration Rules（强制）

1. Every schema change requires a migration under apps/api/migrations/.
2. Never modify production (or shared) databases by hand (ALTER TABLE in psql as a substitute for migration).
3. Migration files are immutable after merge to main — fix forward with a new migration; do not rewrite history on shared branches.
4. Destructive changes (drop column/table, type narrowing) require an explicit rollback/forward strategy in the same change set (Down file or follow-up migration + note).
5. App code must not query columns that are not yet migrated.
6. Local apply: start API（auto-migrate）or documented migrate command in commands.md.

Soft delete

• Default: set deleted_at; do not hard-delete user content in P1.
• Queries filter deleted_at IS NULL unless the task says otherwise.

AI MUST NOT

• 「先改库再补 migration」
• 在 handler 里拼临时 DDL
• 发明未在 domain.md / erd.md 出现的表名（先改文档）