devflow-kit 0.9.0 → 1.1.0

package/shared/skills/database-patterns/references/patterns.md

@@ -0,0 +1,394 @@
+# Database Correct Patterns
+
+Extended examples of correct database design and optimization patterns.
+
+## Schema Design Patterns
+
+### Proper Table Structure
+
+```sql
+-- Well-designed table with all essential elements
+CREATE TABLE orders (
+  -- Primary key: UUID for distributed systems, SERIAL for simpler cases
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  -- Foreign keys with appropriate actions
+  customer_id UUID NOT NULL REFERENCES customers(id) ON DELETE RESTRICT,
+
+  -- Appropriate data types
+  total DECIMAL(10, 2) NOT NULL CHECK (total >= 0),
+  status VARCHAR(20) NOT NULL DEFAULT 'pending',
+
+  -- Timestamps with timezone
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+
+  -- Constraints
+  CONSTRAINT valid_status CHECK (status IN ('pending', 'processing', 'completed', 'cancelled'))
+);
+
+-- Indexes for common queries
+CREATE INDEX idx_orders_customer ON orders(customer_id);
+CREATE INDEX idx_orders_status ON orders(status) WHERE status != 'completed';
+CREATE INDEX idx_orders_created ON orders(created_at);
+```
+
+### Audit Trail Pattern
+
+```sql
+-- Audit columns on every table
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email VARCHAR(255) NOT NULL UNIQUE,
+  name VARCHAR(100) NOT NULL,
+
+  -- Audit trail
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  created_by UUID REFERENCES users(id),
+  updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  updated_by UUID REFERENCES users(id),
+  deleted_at TIMESTAMP WITH TIME ZONE,  -- Soft delete
+  deleted_by UUID REFERENCES users(id)
+);
+
+-- Trigger for automatic updated_at
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER users_updated_at
+  BEFORE UPDATE ON users
+  FOR EACH ROW
+  EXECUTE FUNCTION update_updated_at();
+```
+
+### Enum Pattern (Preferred over VARCHAR)
+
+```sql
+-- Create enum type
+CREATE TYPE order_status AS ENUM (
+  'pending',
+  'processing',
+  'shipped',
+  'delivered',
+  'cancelled'
+);
+
+-- Use in table
+CREATE TABLE orders (
+  id UUID PRIMARY KEY,
+  status order_status NOT NULL DEFAULT 'pending'
+);
+
+-- Benefits: type safety, storage efficiency, self-documenting
+```
+
+---
+
+## Query Optimization Patterns
+
+### Efficient Batch Loading
+
+```typescript
+// Load related data efficiently
+async function getUsersWithOrders(userIds: string[]): Promise<UserWithOrders[]> {
+  // Query 1: Get users
+  const users = await db.query(
+    'SELECT * FROM users WHERE id = ANY($1)',
+    [userIds]
+  );
+
+  // Query 2: Get all orders for these users in one query
+  const orders = await db.query(
+    'SELECT * FROM orders WHERE user_id = ANY($1)',
+    [userIds]
+  );
+
+  // Build lookup map
+  const ordersByUser = new Map<string, Order[]>();
+  for (const order of orders) {
+    const existing = ordersByUser.get(order.user_id) || [];
+    existing.push(order);
+    ordersByUser.set(order.user_id, existing);
+  }
+
+  // Combine
+  return users.map(user => ({
+    ...user,
+    orders: ordersByUser.get(user.id) || []
+  }));
+}
+// Total: 2 queries regardless of user count
+```
+
+### Pagination Pattern
+
+```typescript
+// Cursor-based pagination (efficient for large datasets)
+async function getOrdersPage(
+  customerId: string,
+  cursor?: string,
+  limit: number = 20
+): Promise<{ orders: Order[]; nextCursor: string | null }> {
+  const query = cursor
+    ? `SELECT * FROM orders
+       WHERE customer_id = $1 AND created_at < $2
+       ORDER BY created_at DESC
+       LIMIT $3`
+    : `SELECT * FROM orders
+       WHERE customer_id = $1
+       ORDER BY created_at DESC
+       LIMIT $2`;
+
+  const params = cursor
+    ? [customerId, new Date(cursor), limit + 1]
+    : [customerId, limit + 1];
+
+  const orders = await db.query(query, params);
+
+  const hasMore = orders.length > limit;
+  if (hasMore) orders.pop();
+
+  return {
+    orders,
+    nextCursor: hasMore ? orders[orders.length - 1].created_at.toISOString() : null
+  };
+}
+```
+
+### Index Strategy
+
+```sql
+-- Primary lookup index
+CREATE INDEX idx_orders_customer ON orders(customer_id);
+
+-- Composite index for common query pattern
+-- Order matters: most selective first, or match query order
+CREATE INDEX idx_orders_customer_status_date
+  ON orders(customer_id, status, created_at DESC);
+
+-- Partial index for active records only
+CREATE INDEX idx_orders_pending
+  ON orders(customer_id, created_at)
+  WHERE status = 'pending';
+
+-- Covering index (includes all needed columns)
+CREATE INDEX idx_orders_summary
+  ON orders(customer_id, status)
+  INCLUDE (total, created_at);
+-- Query can be satisfied entirely from index
+```
+
+---
+
+## Migration Patterns
+
+### Safe Column Addition
+
+```typescript
+// Migration: Add new required column safely
+export async function up(db: Database): Promise<void> {
+  // Step 1: Add nullable column (instant, no lock)
+  await db.query(`
+    ALTER TABLE users ADD COLUMN phone VARCHAR(20)
+  `);
+
+  // Step 2: Backfill in batches
+  let processed = 0;
+  const batchSize = 1000;
+
+  while (true) {
+    const result = await db.query(`
+      UPDATE users
+      SET phone = 'UNKNOWN'
+      WHERE phone IS NULL
+      AND id IN (
+        SELECT id FROM users WHERE phone IS NULL LIMIT $1
+      )
+      RETURNING id
+    `, [batchSize]);
+
+    processed += result.rowCount;
+    if (result.rowCount < batchSize) break;
+
+    // Small delay to reduce load
+    await sleep(100);
+  }
+
+  // Step 3: Add NOT NULL constraint
+  await db.query(`
+    ALTER TABLE users ALTER COLUMN phone SET NOT NULL
+  `);
+}
+
+export async function down(db: Database): Promise<void> {
+  await db.query(`
+    ALTER TABLE users DROP COLUMN phone
+  `);
+}
+```
+
+### Safe Column Rename
+
+```typescript
+// Migration: Rename column without downtime
+export async function up(db: Database): Promise<void> {
+  // Step 1: Add new column
+  await db.query(`
+    ALTER TABLE users ADD COLUMN full_name VARCHAR(200)
+  `);
+
+  // Step 2: Copy data
+  await db.query(`
+    UPDATE users SET full_name = name WHERE full_name IS NULL
+  `);
+
+  // Step 3: Create trigger for dual-write during transition
+  await db.query(`
+    CREATE OR REPLACE FUNCTION sync_name_columns()
+    RETURNS TRIGGER AS $$
+    BEGIN
+      IF TG_OP = 'INSERT' OR TG_OP = 'UPDATE' THEN
+        IF NEW.full_name IS NOT NULL AND NEW.name IS DISTINCT FROM NEW.full_name THEN
+          NEW.name = NEW.full_name;
+        ELSIF NEW.name IS NOT NULL AND NEW.full_name IS DISTINCT FROM NEW.name THEN
+          NEW.full_name = NEW.name;
+        END IF;
+      END IF;
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+
+    CREATE TRIGGER sync_names
+      BEFORE INSERT OR UPDATE ON users
+      FOR EACH ROW
+      EXECUTE FUNCTION sync_name_columns();
+  `);
+
+  // Step 4: Deploy code using new column
+  // Step 5: (separate migration) Drop old column and trigger
+}
+```
+
+### Safe Table Restructure
+
+```typescript
+// Migration: Restructure table without downtime
+export async function up(db: Database): Promise<void> {
+  // Step 1: Create new table structure
+  await db.query(`
+    CREATE TABLE users_v2 (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      email VARCHAR(255) NOT NULL UNIQUE,
+      -- new structure
+      profile JSONB NOT NULL DEFAULT '{}'::jsonb,
+      created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+    )
+  `);
+
+  // Step 2: Create insert trigger on old table
+  await db.query(`
+    CREATE OR REPLACE FUNCTION sync_to_users_v2()
+    RETURNS TRIGGER AS $$
+    BEGIN
+      INSERT INTO users_v2 (id, email, profile, created_at)
+      VALUES (
+        NEW.id,
+        NEW.email,
+        jsonb_build_object('name', NEW.name, 'phone', NEW.phone),
+        NEW.created_at
+      )
+      ON CONFLICT (id) DO UPDATE SET
+        email = EXCLUDED.email,
+        profile = EXCLUDED.profile;
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+
+    CREATE TRIGGER sync_users
+      AFTER INSERT OR UPDATE ON users
+      FOR EACH ROW
+      EXECUTE FUNCTION sync_to_users_v2();
+  `);
+
+  // Step 3: Backfill existing data
+  await db.query(`
+    INSERT INTO users_v2 (id, email, profile, created_at)
+    SELECT
+      id,
+      email,
+      jsonb_build_object('name', name, 'phone', phone),
+      created_at
+    FROM users
+    ON CONFLICT (id) DO NOTHING
+  `);
+
+  // Step 4: Switch reads to new table (code deployment)
+  // Step 5: (separate migration) Drop old table
+}
+```
+
+---
+
+## Transaction Patterns
+
+### Proper Transaction Handling
+
+```typescript
+// Transaction with proper error handling and isolation
+async function transferFunds(
+  fromAccount: string,
+  toAccount: string,
+  amount: number
+): Promise<Result<void, TransferError>> {
+  const client = await db.pool.connect();
+
+  try {
+    await client.query('BEGIN');
+    await client.query('SET TRANSACTION ISOLATION LEVEL SERIALIZABLE');
+
+    // Lock rows in consistent order to prevent deadlocks
+    const accounts = [fromAccount, toAccount].sort();
+
+    const fromResult = await client.query(
+      'SELECT balance FROM accounts WHERE id = $1 FOR UPDATE',
+      [accounts[0] === fromAccount ? fromAccount : toAccount]
+    );
+
+    const toResult = await client.query(
+      'SELECT balance FROM accounts WHERE id = $1 FOR UPDATE',
+      [accounts[0] === fromAccount ? toAccount : fromAccount]
+    );
+
+    const fromBalance = fromResult.rows[0]?.balance;
+    if (!fromBalance || fromBalance < amount) {
+      await client.query('ROLLBACK');
+      return { ok: false, error: { type: 'insufficient_funds' } };
+    }
+
+    await client.query(
+      'UPDATE accounts SET balance = balance - $1 WHERE id = $2',
+      [amount, fromAccount]
+    );
+
+    await client.query(
+      'UPDATE accounts SET balance = balance + $1 WHERE id = $2',
+      [amount, toAccount]
+    );
+
+    await client.query('COMMIT');
+    return { ok: true, value: undefined };
+
+  } catch (error) {
+    await client.query('ROLLBACK');
+    return { ok: false, error: { type: 'transaction_failed', cause: error } };
+
+  } finally {
+    client.release();
+  }
+}
+```

package/shared/skills/database-patterns/references/violations.md

@@ -0,0 +1,332 @@
+# Database Violation Examples
+
+Extended examples of database anti-patterns and violations.
+
+## Schema Design Violations
+
+### Missing Foreign Keys - Extended
+
+```sql
+-- PROBLEM: No referential integrity
+CREATE TABLE orders (
+  id SERIAL PRIMARY KEY,
+  customer_id INT,  -- No FK constraint!
+  total DECIMAL
+);
+
+-- SOLUTION: Add foreign key
+CREATE TABLE orders (
+  id SERIAL PRIMARY KEY,
+  customer_id INT NOT NULL REFERENCES customers(id) ON DELETE RESTRICT,
+  total DECIMAL
+);
+```
+
+**Why it matters:**
+- Orphaned records accumulate over time
+- Data integrity depends on application code (fragile)
+- Cannot use cascading deletes/updates
+- Database cannot optimize joins
+
+### Denormalization Without Justification - Extended
+
+```sql
+-- PROBLEM: Unnecessary duplication
+CREATE TABLE orders (
+  id SERIAL PRIMARY KEY,
+  customer_id INT,
+  customer_name VARCHAR(100),     -- Duplicated!
+  customer_email VARCHAR(100),    -- Duplicated!
+  customer_address TEXT           -- Duplicated!
+);
+
+-- SOLUTION: Normalize unless performance requires otherwise
+CREATE TABLE orders (
+  id SERIAL PRIMARY KEY,
+  customer_id INT REFERENCES customers(id)
+);
+-- Access customer data via JOIN
+```
+
+**When denormalization IS justified:**
+- Read-heavy workloads with measured performance issues
+- Historical data that must not change when source changes
+- Reporting/analytics tables (materialized views)
+- Document explicitly: `-- DENORMALIZED: Performance requirement, see ticket DB-123`
+
+### Poor Data Type Choices - Extended
+
+```sql
+-- PROBLEM: Inappropriate types
+CREATE TABLE users (
+  id VARCHAR(100),           -- Use UUID or SERIAL
+  age VARCHAR(10),           -- Use INT
+  balance VARCHAR(50),       -- Use DECIMAL
+  is_active VARCHAR(5),      -- Use BOOLEAN
+  created_at VARCHAR(50)     -- Use TIMESTAMP
+);
+
+-- SOLUTION: Appropriate types
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  age INT CHECK (age >= 0 AND age < 150),
+  balance DECIMAL(10, 2) DEFAULT 0,
+  is_active BOOLEAN DEFAULT true,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+```
+
+**Data type guidelines:**
+| Data | Wrong | Correct |
+|------|-------|---------|
+| Money | FLOAT, VARCHAR | DECIMAL(precision, scale) |
+| Boolean | VARCHAR, INT | BOOLEAN |
+| Date/Time | VARCHAR | TIMESTAMP WITH TIME ZONE |
+| IDs | VARCHAR (random) | UUID, SERIAL, BIGSERIAL |
+| Email | TEXT | VARCHAR(255) with CHECK |
+
+### Missing Constraints - Extended
+
+```sql
+-- PROBLEM: No data validation
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(100),
+  price DECIMAL,
+  quantity INT
+);
+
+-- SOLUTION: Add constraints
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(100) NOT NULL,
+  price DECIMAL(10, 2) NOT NULL CHECK (price >= 0),
+  quantity INT NOT NULL DEFAULT 0 CHECK (quantity >= 0),
+  CONSTRAINT name_not_empty CHECK (LENGTH(TRIM(name)) > 0)
+);
+```
+
+**Essential constraints:**
+- `NOT NULL` on required fields
+- `CHECK` constraints for business rules
+- `UNIQUE` on natural keys
+- `DEFAULT` values where appropriate
+
+---
+
+## Query Optimization Violations
+
+### N+1 Queries - Extended
+
+```typescript
+// PROBLEM: Query per iteration (N+1)
+const users = await db.query('SELECT * FROM users');
+for (const user of users) {
+  const orders = await db.query(
+    'SELECT * FROM orders WHERE user_id = ?',
+    [user.id]
+  );
+  user.orders = orders;
+}
+// If 100 users: 1 + 100 = 101 queries!
+
+// SOLUTION 1: Single query with JOIN
+const users = await db.query(`
+  SELECT u.*, json_agg(o.*) as orders
+  FROM users u
+  LEFT JOIN orders o ON o.user_id = u.id
+  GROUP BY u.id
+`);
+
+// SOLUTION 2: Two queries with IN (batch)
+const users = await db.query('SELECT * FROM users');
+const userIds = users.map(u => u.id);
+const orders = await db.query(
+  'SELECT * FROM orders WHERE user_id = ANY($1)',
+  [userIds]
+);
+// Group orders by user_id in application code
+// Total: 2 queries regardless of user count
+```
+
+### Full Table Scans - Extended
+
+```sql
+-- PROBLEM: Functions prevent index use
+SELECT * FROM users WHERE LOWER(email) = 'john@example.com';
+-- Sequential scan: O(n)
+
+SELECT * FROM orders WHERE YEAR(created_at) = 2024;
+-- Sequential scan: index on created_at cannot be used
+
+SELECT * FROM products WHERE name LIKE '%widget%';
+-- Sequential scan: leading wildcard prevents index use
+
+-- SOLUTIONS:
+
+-- 1. Functional index
+CREATE INDEX idx_users_email_lower ON users(LOWER(email));
+SELECT * FROM users WHERE LOWER(email) = 'john@example.com';
+-- Now uses index
+
+-- 2. Range query instead of function
+SELECT * FROM orders
+WHERE created_at >= '2024-01-01' AND created_at < '2025-01-01';
+-- Uses index on created_at
+
+-- 3. Full-text search for LIKE patterns
+CREATE INDEX idx_products_name_gin ON products USING gin(to_tsvector('english', name));
+SELECT * FROM products WHERE to_tsvector('english', name) @@ to_tsquery('widget');
+```
+
+### Inefficient JOINs - Extended
+
+```sql
+-- PROBLEM: Joining large tables without filters
+SELECT * FROM orders o
+JOIN order_items oi ON oi.order_id = o.id
+JOIN products p ON p.id = oi.product_id;
+-- Returns millions of rows, processes entire tables
+
+-- SOLUTION: Filter early, select specific columns
+SELECT
+  o.id as order_id,
+  o.created_at,
+  oi.quantity,
+  p.name as product_name,
+  p.price
+FROM orders o
+JOIN order_items oi ON oi.order_id = o.id
+JOIN products p ON p.id = oi.product_id
+WHERE o.customer_id = 123
+  AND o.created_at > NOW() - INTERVAL '30 days';
+-- Filters applied before join expands data
+```
+
+---
+
+## Migration Violations
+
+### Breaking Changes Without Migration Path
+
+```sql
+-- PROBLEM: Destructive change
+ALTER TABLE users DROP COLUMN legacy_field;
+-- Data is lost immediately!
+
+-- SOLUTION: Phased approach
+-- Phase 1: Stop writes (deploy code that doesn't write to column)
+-- Phase 2: Add deprecation notice
+ALTER TABLE users ALTER COLUMN legacy_field SET DEFAULT NULL;
+-- Phase 3: Wait for deployment verification
+-- Phase 4: Drop column after confirming no reads/writes
+ALTER TABLE users DROP COLUMN legacy_field;
+```
+
+### Data Loss Risk
+
+```sql
+-- PROBLEM: Type change loses data
+ALTER TABLE products ALTER COLUMN price TYPE INT;
+-- Decimal values truncated: 19.99 becomes 19
+
+-- SOLUTION: Validate first
+SELECT id, price FROM products WHERE price != FLOOR(price);
+-- If results exist: handle decimal values first
+
+-- Safe alternative: create new column
+ALTER TABLE products ADD COLUMN price_cents INT;
+UPDATE products SET price_cents = price * 100;
+-- Verify, then drop old column
+```
+
+### Missing Rollback Strategy
+
+```typescript
+// PROBLEM: No way to undo
+export async function up(db) {
+  await db.query('DROP TABLE old_users');
+}
+
+export async function down(db) {
+  // Can't recreate dropped table with its data!
+  throw new Error('Irreversible migration');
+}
+
+// SOLUTION: Always plan rollback
+export async function up(db) {
+  await db.query('ALTER TABLE old_users RENAME TO old_users_backup');
+  await db.query('CREATE TABLE users_v2 AS SELECT * FROM old_users_backup');
+}
+
+export async function down(db) {
+  await db.query('DROP TABLE IF EXISTS users_v2');
+  await db.query('ALTER TABLE old_users_backup RENAME TO old_users');
+}
+```
+
+### Performance Impact
+
+```sql
+-- PROBLEM: Locks table for extended period
+ALTER TABLE large_table ADD COLUMN new_field VARCHAR(100) NOT NULL DEFAULT 'value';
+-- Rewrites entire table, holds exclusive lock
+
+-- SOLUTION: Non-blocking approach (3 steps)
+-- Step 1: Add nullable column (instant, no rewrite)
+ALTER TABLE large_table ADD COLUMN new_field VARCHAR(100);
+
+-- Step 2: Backfill in batches (no lock)
+UPDATE large_table SET new_field = 'value' WHERE id BETWEEN 1 AND 10000;
+UPDATE large_table SET new_field = 'value' WHERE id BETWEEN 10001 AND 20000;
+-- ... continue in batches with small transactions
+
+-- Step 3: Add constraint after backfill complete
+ALTER TABLE large_table ALTER COLUMN new_field SET NOT NULL;
+```
+
+---
+
+## Security Violations
+
+### SQL Injection - Extended
+
+```typescript
+// VULNERABLE: String interpolation
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+// If email = "'; DROP TABLE users; --" -> disaster
+
+// VULNERABLE: String concatenation
+const query = 'SELECT * FROM users WHERE email = "' + email + '"';
+// Same vulnerability
+
+// SECURE: Parameterized queries
+const query = 'SELECT * FROM users WHERE email = $1';
+await db.query(query, [email]);
+
+// SECURE: ORM with proper escaping
+await User.findOne({ where: { email } });
+```
+
+### Excessive Privileges
+
+```sql
+-- PROBLEM: App has too many privileges
+GRANT ALL PRIVILEGES ON DATABASE myapp TO app_user;
+-- App can DROP tables, modify schema, etc.
+
+-- SOLUTION: Minimum required privileges (principle of least privilege)
+-- Read-only operations
+GRANT SELECT ON users, products, orders TO readonly_user;
+
+-- Application user (typical CRUD)
+GRANT SELECT, INSERT, UPDATE ON users TO app_user;
+GRANT SELECT ON products TO app_user;
+GRANT SELECT, INSERT ON orders TO app_user;
+-- No DELETE unless business requirement
+-- No schema modification privileges
+
+-- Migrations user (separate, restricted use)
+GRANT ALL ON SCHEMA public TO migrations_user;
+-- Only used during deployments, not by running application
+```