80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
|
---
|
||
|
|
name: design-postgres-tables
|
||
|
|
description: Design PostgreSQL table schemas. Use when modeling new data, adding tables, or reviewing/improving existing schema design.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Design Postgres Tables Skill
|
||
|
|
|
||
|
|
Use when: designing new tables, modeling relationships, reviewing schema, or planning migrations.
|
||
|
|
|
||
|
|
## Column Conventions
|
||
|
|
- **Primary key**: `id UUID PRIMARY KEY DEFAULT gen_random_uuid()` (prefer UUID over serial for distributed systems; use BIGSERIAL if you need sortable IDs)
|
||
|
|
- **Timestamps**: always include `created_at TIMESTAMPTZ DEFAULT NOW()` and `updated_at TIMESTAMPTZ DEFAULT NOW()`
|
||
|
|
- **Soft delete**: `deleted_at TIMESTAMPTZ DEFAULT NULL` (NULL = active)
|
||
|
|
- **Foreign keys**: name as `<table_singular>_id`, e.g. `user_id`, `project_id`
|
||
|
|
- Use `TEXT` over `VARCHAR(n)` unless you need DB-enforced length limits
|
||
|
|
- Use `BOOLEAN` not `SMALLINT` for true/false
|
||
|
|
- Use `NUMERIC(precision, scale)` for money, never `FLOAT`
|
||
|
|
|
||
|
|
## Naming Conventions
|
||
|
|
- Tables: `snake_case`, plural: `users`, `project_sessions`, `api_tokens`
|
||
|
|
- Columns: `snake_case`, singular
|
||
|
|
- Indexes: `idx_<table>_<column(s)>`: `idx_users_email`
|
||
|
|
- Foreign keys: `fk_<table>_<referenced_table>`: `fk_orders_users`
|
||
|
|
- Unique constraints: `uq_<table>_<column(s)>`: `uq_users_email`
|
||
|
|
|
||
|
|
## Standard Table Template
|
||
|
|
```sql
|
||
|
|
CREATE TABLE items (
|
||
|
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
|
|
|
||
|
|
-- Business columns
|
||
|
|
name TEXT NOT NULL,
|
||
|
|
description TEXT,
|
||
|
|
status TEXT NOT NULL DEFAULT 'active'
|
||
|
|
CHECK (status IN ('active', 'inactive', 'archived')),
|
||
|
|
|
||
|
|
-- Relationships
|
||
|
|
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||
|
|
|
||
|
|
-- Metadata
|
||
|
|
metadata JSONB DEFAULT '{}',
|
||
|
|
|
||
|
|
-- Audit
|
||
|
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
|
|
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
|
|
deleted_at TIMESTAMPTZ
|
||
|
|
);
|
||
|
|
|
||
|
|
-- Indexes
|
||
|
|
CREATE INDEX idx_items_user_id ON items(user_id);
|
||
|
|
CREATE INDEX idx_items_status ON items(status) WHERE deleted_at IS NULL;
|
||
|
|
CREATE INDEX idx_items_created_at ON items(created_at DESC);
|
||
|
|
|
||
|
|
-- Auto-update updated_at
|
||
|
|
CREATE TRIGGER items_updated_at
|
||
|
|
BEFORE UPDATE ON items
|
||
|
|
FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
|
||
|
|
```
|
||
|
|
|
||
|
|
## Relationship Patterns
|
||
|
|
- **One-to-many**: FK on the "many" side
|
||
|
|
- **Many-to-many**: junction table with `<a>_id` + `<b>_id` + its own PK + timestamps
|
||
|
|
- **Polymorphic**: `entity_type TEXT + entity_id UUID` (add check constraint for valid types)
|
||
|
|
|
||
|
|
## Index Strategy
|
||
|
|
- Index all foreign keys
|
||
|
|
- Index columns used in WHERE clauses with high selectivity
|
||
|
|
- Partial indexes for filtered queries: `WHERE deleted_at IS NULL`
|
||
|
|
- Composite indexes: put equality columns first, range columns last
|
||
|
|
- JSONB: use GIN index for `@>` containment queries
|
||
|
|
|
||
|
|
## Design Checklist
|
||
|
|
- [ ] Every table has UUID PK + created_at + updated_at
|
||
|
|
- [ ] Foreign keys have explicit ON DELETE behavior (CASCADE vs RESTRICT vs SET NULL)
|
||
|
|
- [ ] Enum-like columns use CHECK constraints or a lookup table
|
||
|
|
- [ ] Money stored as NUMERIC not FLOAT
|
||
|
|
- [ ] Indexes on all FK columns
|
||
|
|
- [ ] No storing arrays as comma-separated strings (use ARRAY[] or junction table)
|
||
|
|
- [ ] JSONB for truly dynamic/schemaless data only — not as a crutch
|