@sylix/coworker 2.0.10 → 2.0.12

package/dist/skills/defaults/backend-development/database-design.md

@@ -0,0 +1,305 @@
+---
+name: database-design
+description: Design efficient, scalable database schemas with normalization, indexing, and performance optimization.
+---
+
+# Database Design — CoWorker Edition
+
+Build robust data models that scale. These principles apply to PostgreSQL, MySQL, and most relational databases.
+
+## When to Use This Skill
+
+- Designing new database schemas
+- Normalizing or denormalizing existing schemas
+- Optimizing query performance
+- Choosing data types
+- Implementing relationships
+
+## Core Concepts
+
+### 1. Normalization
+
+**First Normal Form (1NF):**
+- Atomic values (no arrays in columns)
+- No repeated groups
+- Each row unique
+
+```sql
+-- Bad: Repeating groups
+CREATE TABLE orders_bad (
+    id INT,
+    item1 VARCHAR(100),
+    item2 VARCHAR(100),
+    item3 VARCHAR(100)
+);
+
+-- Good: Atomic values
+CREATE TABLE orders (
+    id INT PRIMARY KEY,
+    customer_id INT,
+    order_date DATE
+);
+
+CREATE TABLE order_items (
+    id INT PRIMARY KEY,
+    order_id INT REFERENCES orders(id),
+    product_id INT,
+    quantity INT
+);
+```
+
+**Second Normal Form (2NF):**
+- 1NF + No partial dependencies
+- Non-key columns depend on entire primary key
+
+```sql
+-- Bad: Partial dependency
+CREATE TABLE order_items_bad (
+    order_id INT,
+    product_id INT,  -- Part of PK
+    product_name VARCHAR(100),  -- Depends only on product_id
+    quantity INT,
+    PRIMARY KEY (order_id, product_id)
+);
+
+-- Good: Separate tables
+CREATE TABLE products (
+    id INT PRIMARY KEY,
+    name VARCHAR(100)
+);
+
+CREATE TABLE order_items (
+    order_id INT REFERENCES orders(id),
+    product_id INT REFERENCES products(id),
+    quantity INT,
+    PRIMARY KEY (order_id, product_id)
+);
+```
+
+**Third Normal Form (3NF):**
+- 2NF + No transitive dependencies
+- Non-key columns depend only on primary key
+
+```sql
+-- Bad: Transitive dependency
+CREATE TABLE orders_bad (
+    id INT PRIMARY KEY,
+    customer_id INT,
+    customer_city VARCHAR(100),  -- Depends on customer_id, not order
+    customer_zip VARCHAR(10)
+);
+
+-- Good: Separate customer info
+CREATE TABLE customers (
+    id INT PRIMARY KEY,
+    city VARCHAR(100),
+    zip VARCHAR(10)
+);
+```
+
+### 2. Indexing Strategies
+
+```sql
+-- Single column index
+CREATE INDEX idx_orders_customer ON orders(customer_id);
+
+-- Composite index (order matters!)
+-- For: WHERE status = 'pending' AND created_at > '2024-01-01'
+CREATE INDEX idx_orders_status_date ON orders(status, created_at);
+
+-- Partial index (only active records)
+CREATE INDEX idx_active_orders ON orders(customer_id)
+WHERE status = 'active';
+
+-- Unique index
+CREATE UNIQUE INDEX idx_users_email ON users(email);
+
+-- Covering index (includes all queried columns)
+CREATE INDEX idx_orders_cover ON orders(customer_id, status, created_at)
+INCLUDE (total_amount);
+```
+
+### 3. Data Types
+
+```sql
+-- Use appropriate types
+-- Dates
+created_at TIMESTAMP WITH TIME ZONE  -- For logs, records
+birth_date DATE  -- For dates without time
+
+-- Strings
+username VARCHAR(50)    -- Bounded
+bio TEXT                -- Unbounded
+country_code CHAR(2)   -- Fixed length
+
+-- Numbers
+quantity INT           -- Whole numbers
+price DECIMAL(10, 2)   -- Exact precision for money
+latitude DECIMAL(9, 6) -- Coordinates
+
+-- UUID vs Integer
+id UUID PRIMARY KEY DEFAULT gen_random_uuid()  -- Distributed systems
+id SERIAL PRIMARY KEY  -- Single database
+```
+
+### 4. Relationships
+
+```sql
+-- One-to-One
+CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    email VARCHAR(255) UNIQUE
+);
+
+CREATE TABLE user_profiles (
+    user_id INT PRIMARY KEY REFERENCES users(id),
+    bio TEXT,
+    avatar_url VARCHAR(500)
+);
+
+-- One-to-Many
+CREATE TABLE customers (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255)
+);
+
+CREATE TABLE orders (
+    id SERIAL PRIMARY KEY,
+    customer_id INT REFERENCES customers(id),
+    total DECIMAL(10, 2)
+);
+
+-- Many-to-Many
+CREATE TABLE students (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255)
+);
+
+CREATE TABLE courses (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255)
+);
+
+CREATE TABLE enrollments (
+    student_id INT REFERENCES students(id),
+    course_id INT REFERENCES courses(id),
+    enrolled_at TIMESTAMP DEFAULT NOW(),
+    PRIMARY KEY (student_id, course_id)
+);
+```
+
+### 5. Migrations
+
+```python
+# Alembic migration example
+"""add_user_preferences
+
+Revision ID: abc123
+Revises: 
+Create Date: 2024-01-15 10:00:00
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = 'abc123'
+down_revision = 'previous_revision'
+branch_labels = None
+depends_on = None
+
+def upgrade():
+    op.create_table(
+        'user_preferences',
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('theme', sa.String(20), server_default='light'),
+        sa.Column('notifications', sa.Boolean(), server_default=True),
+        sa.ForeignKeyConstraint(['user_id'], ['users.id']),
+        sa.PrimaryKeyConstraint('user_id')
+    )
+    
+    # Add index
+    op.create_index(
+        'idx_preferences_theme',
+        'user_preferences',
+        ['theme']
+    )
+
+def downgrade():
+    op.drop_index('idx_preferences_theme')
+    op.drop_table('user_preferences')
+```
+
+### 6. Query Optimization
+
+```python
+# Bad: N+1 queries
+def get_orders_with_users():
+    orders = db.query(Order).all()
+    for order in orders:
+        user = db.query(User).get(order.user_id)  # Query per order!
+        order.user = user
+    return orders
+
+# Good: Eager loading
+def get_orders_with_users():
+    return db.query(Order).options(
+        joinedload(Order.user)
+    ).all()
+
+# Good: Specific columns
+def get_order_summary():
+    return db.query(
+        Order.id,
+        Order.status,
+        User.name.label('customer_name')
+    ).join(User).all()
+```
+
+### 7. Transactions
+
+```python
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+engine = create_engine(DATABASE_URL)
+Session = sessionmaker(bind=engine)
+
+def transfer_funds(from_account: int, to_account: int, amount: Decimal):
+    session = Session()
+    try:
+        # Start transaction
+        from_acc = session.query(Account).filter_by(id=from_account).with_for_update().first()
+        to_acc = session.query(Account).filter_by(id=to_account).with_for_update().first()
+        
+        if from_acc.balance < amount:
+            raise InsufficientFundsError()
+        
+        from_acc.balance -= amount
+        to_acc.balance += amount
+        
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+```
+
+## Best Practices
+
+1. **Start normalized** - Denormalize only for performance
+2. **Index strategically** - Based on actual query patterns
+3. **Use constraints** - NOT NULL, CHECK, UNIQUE, FOREIGN KEY
+4. **Version migrations** - Always use migration tools
+5. **Test migrations** - Run against copy before production
+6. **Document schema** - ERD diagrams, README
+7. **Soft deletes** - Use `deleted_at` for audit trails
+
+## Common Pitfalls
+
+- Missing foreign key constraints
+- No indexes on foreign keys
+- Storing serialized JSON when columns work
+- Using TEXT for everything
+- Over-normalization (too many joins)
+- No migration strategy
+- Ignoring database-specific features