189 lines
6.3 KiB
Markdown
189 lines
6.3 KiB
Markdown
---
|
|
name: db-design
|
|
description: "Activate when user requests: Database/table design for transactional (OLTP), analytics (OLAP), create or extend schema, design fact/dimension tables, analyze/review CSV/JSON/SQL files to create tables, or need advice on data storage structure."
|
|
---
|
|
|
|
# SKILL: Database Schema Design
|
|
|
|
## Execution Process
|
|
|
|
### Step 1: Analyze Context (MANDATORY)
|
|
|
|
Before ANY design work, AI MUST check:
|
|
|
|
- [ ] Database stack identified? (MySQL / PostgreSQL / BigQuery / SQLite / D1)
|
|
- [ ] Existing schema explored via tools/MCP?
|
|
- [ ] Use case clear? (transactional vs analytics vs ETL)
|
|
|
|
**If ANY checkbox is unclear → STOP and ask user before proceeding.**
|
|
|
|
### Step 2: Gather Requirements
|
|
|
|
**MUST ask if missing:**
|
|
|
|
| Missing Info | Required Question |
|
|
|--------------|-------------------|
|
|
| Entities unclear | "What are the main entities involved in this feature?" |
|
|
| Query patterns unknown | "What queries/reports will run most often?" |
|
|
| Granularity unclear | "What level of detail needed? (per order, per item, per day)" |
|
|
| Constraints unknown | "Any uniqueness, retention, or multi-tenant requirements?" |
|
|
| Relationships unclear | "How do these entities relate to each other?" |
|
|
|
|
**DO NOT assume or proceed without answers. DO NOT design schema without understanding the business context.**
|
|
|
|
### Step 3: Load Documentation by Intent
|
|
|
|
| Intent | Keywords | Load file |
|
|
|--------|----------|-----------|
|
|
| **OLTP** | "business tables", "transactional", "CRUD", "orders", "users" | [transactional.md](transactional.md) |
|
|
| **OLAP** | "analytics", "statistics", "reports", "fact", "dimension" | [analytics.md](analytics.md) |
|
|
| **ETL** | "incremental", "load", "sync", "watermark", "etl" | [incremental-etl.md](incremental-etl.md) |
|
|
|
|
**Database stacks:** [MySQL](stacks/mysql.md) · [PostgreSQL](stacks/postgres.md) · [BigQuery](stacks/bigquery.md) · [SQLite](stacks/sqlite.md) · [D1 Cloudflare](stacks/d1_cloudflare.md)
|
|
|
|
### Step 4: Design & Propose
|
|
|
|
Only after Steps 1-3 complete:
|
|
- Propose DDL with reasoning
|
|
- **Wait for user approval before execution**
|
|
- Never auto-execute DDL
|
|
|
|
### Step 5: Verify Checklist
|
|
|
|
Before delivering final DDL, verify the **Final Checklist** at the end of this file.
|
|
|
|
---
|
|
|
|
## Scope & Objectives
|
|
|
|
Design or extend database schemas ensuring:
|
|
|
|
- Consistent, understandable, maintainable data structures
|
|
- Good performance with appropriate indexes
|
|
- Design that fits existing tables (avoid duplication, avoid breaking logic)
|
|
|
|
---
|
|
|
|
## Naming Conventions
|
|
|
|
### Table naming
|
|
|
|
- Use **snake_case**, English, plural for main entities:
|
|
- `users`, `orders`, `order_items`, `product_variants`
|
|
- Junction/mapping tables:
|
|
- `role_permissions`, `user_roles`, `product_categories`
|
|
- Fact & dimension tables (analytics):
|
|
- Fact: `fact_orders`, `fact_order_items`, `fact_pageviews`
|
|
- Dimension: `dim_date`, `dim_customer`, `dim_product`, `dim_store`
|
|
- Avoid unclear abbreviations:
|
|
- ❌ `usr`, `ord`, `inv_tx`
|
|
- ✅ `users`, `orders`, `inventory_transactions`
|
|
|
|
### Column naming
|
|
|
|
- Use **snake_case**, clear meaning, consistent across tables
|
|
- **Primary key**: `id` (main PK of table)
|
|
- **Foreign key**: `xxx_id` pointing to table `xxx`:
|
|
- `user_id` → `users.id`
|
|
- `order_id` → `orders.id`
|
|
- **Audit & lifecycle**:
|
|
- `created_at`, `updated_at`, `deleted_at` (soft delete)
|
|
- **Boolean flags**:
|
|
- `is_active`, `is_deleted`, `is_primary`, `is_verified`
|
|
- **Quantities & prices**:
|
|
- `quantity`, `unit_price`, `total_price`, `discount_amount`, `tax_amount`
|
|
- **Time ranges**:
|
|
- `start_at`, `end_at` or `valid_from`, `valid_to` (pick one convention and use consistently)
|
|
- **Enum/state**:
|
|
- `status` (combine with ENUM / CHECK constraint)
|
|
|
|
---
|
|
|
|
## Workflow
|
|
|
|
### 1. Understand business requirements
|
|
|
|
- Summarize requirements in your own words
|
|
- If missing context, ask:
|
|
- What entities are involved?
|
|
- What is the main business flow?
|
|
- What queries/reports are commonly used?
|
|
|
|
### 2. Explore existing schema (MANDATORY before proposing)
|
|
|
|
- Use tools/MCP to list tables and describe structure
|
|
- For DBs with comments (MySQL/PostgreSQL/BigQuery): read comments directly
|
|
- For SQLite/D1: query `metadata_tables` and `metadata_columns` tables
|
|
|
|
### 3. Analyze and propose draft
|
|
|
|
- Which tables already partially cover requirements?
|
|
- Which tables need additional columns/indexes?
|
|
- Which tables are completely missing (need to create)?
|
|
|
|
### 4. Confirm with user before finalizing design
|
|
|
|
- Required granularity
|
|
- Metrics to calculate
|
|
- Important business constraints (uniqueness, retention, privacy)
|
|
|
|
### 5. Design detailed schema
|
|
|
|
- Provide proposed DDL - **do NOT auto-execute**
|
|
- Wait for user approval before execution
|
|
|
|
---
|
|
|
|
## Processing Data Files (CSV/JSON/SQL)
|
|
|
|
When user provides files:
|
|
|
|
1. **Read and identify structure**: headers, data types, relationships
|
|
2. **Large files**: write Python script to parse and analyze
|
|
3. **SQL files**: review naming, indexes, constraints, propose improvements
|
|
4. **Output**: Proposed DDL with reasoning
|
|
|
|
---
|
|
|
|
## Output Format
|
|
|
|
When delivering design results:
|
|
|
|
1. **Summary**: list of new tables / tables to modify
|
|
2. **Complete DDL SQL**: columns, types, PK, FK, indexes, comments
|
|
3. **Reasoning**: explain why this structure/index was chosen, tied to actual queries
|
|
|
|
---
|
|
|
|
## Final Checklist
|
|
|
|
Before delivering final DDL:
|
|
|
|
- [ ] Explored existing schema via tools/MCP
|
|
- [ ] No duplicate tables with existing schema
|
|
- [ ] All FKs have indexes
|
|
- [ ] Composite indexes match main query patterns
|
|
- [ ] Naming convention consistent with existing schema
|
|
- [ ] Added comments/descriptions for tables and columns
|
|
- [ ] For SQLite/D1: prepared INSERTs for metadata tables
|
|
- [ ] Explained reasoning for important design decisions
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
```
|
|
.opencode/skills/databases/
|
|
├── SKILL.md # Skill description (entry + execution process + checklist)
|
|
├── db-design.md # This file
|
|
├── transactional.md # OLTP design rules
|
|
├── analytics.md # OLAP / Star Schema rules
|
|
├── incremental-etl.md # ETL & watermark patterns
|
|
└── stacks/
|
|
├── mysql.md # MySQL-specific rules
|
|
├── postgres.md # PostgreSQL-specific rules
|
|
├── bigquery.md # BigQuery-specific rules
|
|
├── sqlite.md # SQLite-specific rules
|
|
└── d1_cloudflare.md # D1 Cloudflare-specific rules
|
|
```
|