opencode-workflow/skills/design_database_schema/SKILL.md

name	description
design_database_schema	Produce database schema definitions including tables, collections, partition keys, indexes, relationships, denormalization strategy, and migration strategy. Supports PostgreSQL, Cassandra, MongoDB, Redis, SurrealDB. A deliverable skill referenced by design-architecture.

This skill provides guidance and format requirements for producing database schema definitions within the architecture document.

This is a deliverable skill, not a workflow skill. It is referenced by design-architecture when producing database schema artifacts.

Purpose

The Architect must produce detailed database schema definitions that are specific enough for implementation. Schemas define the data layer of the system and must include tables, fields, indexes, partition keys, relationships, and migration strategies.

Supported Databases

When designing database schema, consider the appropriate database for each data domain:

Database	Best For	Not Ideal For
PostgreSQL	Relational data, ACID transactions, complex queries	Massive write throughput, wide-column access patterns
Cassandra	High write throughput, time-series, wide-column access patterns	Complex joins, ACID transactions, ad-hoc queries
MongoDB	Document data, flexible schema, rapid iteration	Complex joins, strict ACID, relational data
Redis	Caching, sessions, rate limiting, real-time leaderboards	Persistent primary data, complex queries
SurrealDB	Multi-model data, real-time, graph relationships	Unknown maturity, limited ecosystem

Schema Definition Format

Each table/collection must include:

Table Definition

### {table_name}

**Purpose**: {Brief description of what this table stores}

| Column | Type | Constraints | Default | Description |
|--------|------|-------------|---------|-------------|
| id | UUID | PK, NOT NULL | gen_random_uuid() | Primary key |
| ... | ... | ... | ... | ... |

**Indexes**:

| Index Name | Columns | Type | Justification |
|-----------|---------|------|---------------|
| idx_{table}_{columns} | {columns} | B-tree / Hash / GIN | {query pattern this index supports} |

**Partition Key**: {partition_key} (if applicable)

**Foreign Keys**:

| Column | References | On Delete |
|--------|-----------|-----------|
| {column} | {table}.{column} | CASCADE / SET NULL / RESTRICT |

Collection Definition (for document databases)

### {collection_name}

**Purpose**: {Brief description}

**Document Schema**:
- `{field}`: `{type}` — {description}
- ...

**Indexes**:

| Index Name | Fields | Type | Justification |
|-----------|--------|------|---------------|
| ... | ... | ... | ... |

**Partition Key**: {partition_key} (if applicable)

Required Schema Elements

Tables / Collections

• Every entity identified in the architecture must have a table or collection definition
• Each table must have a clear purpose statement
• Each field must have type, constraints, and description

Indexes

• Every index must be justified by a specific query pattern
• Consider composite indexes for multi-column queries
• Consider partial indexes for filtered queries
• Consider unique indexes for business constraints

Partition Keys (when applicable)

• Define partition keys for Cassandra, DynamoDB, or similar databases
• Justify partition key choice based on access patterns
• Document partition distribution expectations

Relationships

• Define foreign key relationships with referential integrity constraints
• Document one-to-one, one-to-many, many-to-many relationships
• Define junction tables for many-to-many relationships
• Document data ownership: each piece of data belongs to exactly one service

Denormalization Strategy

• Document any intentional denormalization
• Justify each denormalization decision with a specific read pattern
• Describe the consistency implications of each denormalization
• Define the synchronization mechanism for denormalized data

Migration Strategy

• Document migration approach for schema changes
• Define backward-compatible migration strategy
• Note any data migration steps required
• Define rollback strategy for schema changes

Knowledge Contract Reference

This deliverable skill works alongside the data-modeling knowledge contract:

• data-modeling provides the theoretical guidance on data modeling principles
• This skill provides the concrete output format and completeness requirements

Anti-Placeholder Rule

Examples in this skill are illustrative only. Do not reuse placeholder table names, column names, types, indexes, or relationships unless explicitly required by the PRD. Every table, field, index, and relationship must be grounded in actual requirements and match the architecture document's data model.

Embedding in Architecture Document

All database schema definitions must be embedded within the ## Database Schema section of docs/architecture/{feature}.md.

Do NOT produce separate schema files. All schema definitions must be within the single architecture document.