@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/database-migrations.md

@@ -0,0 +1,346 @@
+---
+name: database-migrations
+description: Database migration patterns for Prisma, Knex, zero-downtime deploys, rollback strategies, and seed data management.
+---
+
+# Database Migration Patterns
+
+## When to Use
+Apply migration patterns whenever you change database schema: adding tables, modifying columns, creating indexes, or altering constraints. Migrations provide version-controlled, repeatable, and reversible schema changes. Use these patterns from the first database change to prevent drift between environments. Zero-downtime techniques are essential for production deployments with active traffic.
+
+## How It Works
+
+### Prisma Migrate Workflow
+
+```prisma
+// prisma/schema.prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String?
+  role      Role     @default(USER)
+  posts     Post[]
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([email])
+  @@index([createdAt])
+}
+
+model Post {
+  id        String   @id @default(cuid())
+  title     String   @db.VarChar(255)
+  slug      String   @unique
+  body      String
+  published Boolean  @default(false)
+  author    User     @relation(fields: [authorId], references: [id])
+  authorId  String
+  tags      Tag[]
+  createdAt DateTime @default(now())
+
+  @@index([authorId])
+  @@index([slug])
+  @@index([published, createdAt])
+}
+
+model Tag {
+  id    String @id @default(cuid())
+  name  String @unique
+  posts Post[]
+}
+
+enum Role {
+  USER
+  ADMIN
+}
+```
+
+```bash
+# Create a new migration
+npx prisma migrate dev --name add_tags_table
+
+# Apply migrations in production (no prompt)
+npx prisma migrate deploy
+
+# Reset database (dev only)
+npx prisma migrate reset
+
+# Check migration status
+npx prisma migrate status
+```
+
+### Knex Migration Pattern
+
+```typescript
+// migrations/20260526120000_create_users.ts
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('users', (table) => {
+    table.uuid('id').primary().defaultTo(knex.fn.uuid());
+    table.string('email', 255).notNullable().unique();
+    table.string('name', 255);
+    table.enum('role', ['user', 'admin']).defaultTo('user');
+    table.timestamps(true, true);  // created_at, updated_at with defaults
+
+    table.index(['email']);
+    table.index(['created_at']);
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists('users');
+}
+```
+
+```typescript
+// migrations/20260526130000_add_posts_table.ts
+import { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('posts', (table) => {
+    table.uuid('id').primary().defaultTo(knex.fn.uuid());
+    table.string('title', 255).notNullable();
+    table.string('slug', 255).notNullable().unique();
+    table.text('body').notNullable();
+    table.boolean('published').defaultTo(false);
+    table.uuid('author_id').notNullable()
+      .references('id').inTable('users').onDelete('CASCADE');
+    table.timestamps(true, true);
+
+    table.index(['author_id']);
+    table.index(['slug']);
+    table.index(['published', 'created_at']);
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists('posts');
+}
+```
+
+### Zero-Downtime Column Addition
+
+```typescript
+// Step 1: Add nullable column (non-breaking)
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable('users', (table) => {
+    table.string('avatar_url', 500).nullable();
+  });
+}
+
+// Step 2: Backfill data (separate migration, can run while app serves traffic)
+export async function up(knex: Knex): Promise<void> {
+  const batchSize = 1000;
+  let offset = 0;
+  let rows;
+
+  do {
+    rows = await knex('users')
+      .whereNull('avatar_url')
+      .limit(batchSize)
+      .offset(offset)
+      .select('id');
+
+    if (rows.length > 0) {
+      await knex('users')
+        .whereIn('id', rows.map((r: any) => r.id))
+        .update({ avatar_url: 'https://cdn.example.com/default-avatar.png' });
+    }
+
+    offset += batchSize;
+  } while (rows.length === batchSize);
+}
+
+// Step 3: Add NOT NULL constraint (after backfill verified)
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable('users', (table) => {
+    table.string('avatar_url', 500).notNullable().defaultTo('https://cdn.example.com/default-avatar.png').alter();
+  });
+}
+```
+
+### Zero-Downtime Column Rename (Expand-Contract)
+
+```typescript
+// Phase 1: Add new column, copy data
+export async function up(knex: Knex): Promise<void> {
+  // Add new column
+  await knex.schema.alterTable('users', (table) => {
+    table.string('display_name', 255);
+  });
+
+  // Copy data
+  await knex.raw('UPDATE users SET display_name = name');
+
+  // Add trigger to keep columns in sync during transition
+  await knex.raw(`
+    CREATE OR REPLACE FUNCTION sync_user_name() RETURNS TRIGGER AS $$
+    BEGIN
+      IF TG_OP = 'INSERT' OR NEW.name IS DISTINCT FROM OLD.name THEN
+        NEW.display_name = NEW.name;
+      END IF;
+      IF NEW.display_name IS DISTINCT FROM OLD.display_name THEN
+        NEW.name = NEW.display_name;
+      END IF;
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+
+    CREATE TRIGGER sync_name_trigger BEFORE INSERT OR UPDATE ON users
+    FOR EACH ROW EXECUTE FUNCTION sync_user_name();
+  `);
+}
+
+// Phase 2: Deploy app code reading from display_name
+// Phase 3: Remove old column and trigger
+export async function up(knex: Knex): Promise<void> {
+  await knex.raw('DROP TRIGGER IF EXISTS sync_name_trigger ON users');
+  await knex.raw('DROP FUNCTION IF EXISTS sync_user_name()');
+  await knex.schema.alterTable('users', (table) => {
+    table.dropColumn('name');
+  });
+}
+```
+
+### Seed Data Management
+
+```typescript
+// prisma/seed.ts
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+async function main() {
+  // Upsert to make seeds idempotent
+  const admin = await prisma.user.upsert({
+    where: { email: 'admin@example.com' },
+    update: {},
+    create: {
+      email: 'admin@example.com',
+      name: 'Admin',
+      role: 'ADMIN',
+    },
+  });
+
+  const tags = ['typescript', 'react', 'node', 'database'];
+  for (const name of tags) {
+    await prisma.tag.upsert({
+      where: { name },
+      update: {},
+      create: { name },
+    });
+  }
+
+  console.log(`Seeded: ${admin.email}, ${tags.length} tags`);
+}
+
+main()
+  .then(() => prisma.$disconnect())
+  .catch((e) => {
+    console.error(e);
+    prisma.$disconnect();
+    process.exit(1);
+  });
+```
+
+### Rollback Strategy
+
+```typescript
+// scripts/rollback-migration.ts
+import { execSync } from 'child_process';
+
+async function rollback(steps: number = 1) {
+  console.log(`Rolling back ${steps} migration(s)...`);
+
+  // For Knex
+  execSync(`npx knex migrate:rollback --knexfile knexfile.ts --step ${steps}`, {
+    stdio: 'inherit',
+  });
+
+  // Verify state
+  execSync('npx knex migrate:status --knexfile knexfile.ts', { stdio: 'inherit' });
+}
+
+// For Prisma, rollback requires resolving migration:
+// npx prisma migrate resolve --rolled-back MIGRATION_NAME
+// Then manually reverse the changes
+```
+
+### Migration Testing
+
+```typescript
+// __tests__/migrations.test.ts
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { Knex, knex } from 'knex';
+
+describe('database migrations', () => {
+  let db: Knex;
+
+  beforeAll(async () => {
+    db = knex({ client: 'pg', connection: process.env.TEST_DATABASE_URL });
+  });
+
+  afterAll(async () => { await db.destroy(); });
+
+  it('applies all migrations without error', async () => {
+    await db.migrate.latest();
+    const [, pending] = await db.migrate.status();
+    expect(pending).toHaveLength(0);
+  });
+
+  it('rolls back without error', async () => {
+    await db.migrate.rollback(undefined, true); // rollback all
+    await db.migrate.latest(); // reapply
+  });
+
+  it('creates expected tables', async () => {
+    const tables = await db.raw(`
+      SELECT table_name FROM information_schema.tables
+      WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+    `);
+    const names = tables.rows.map((r: any) => r.table_name);
+    expect(names).toContain('users');
+    expect(names).toContain('posts');
+  });
+
+  it('creates expected indexes', async () => {
+    const indexes = await db.raw(`
+      SELECT indexname FROM pg_indexes WHERE tablename = 'posts'
+    `);
+    const names = indexes.rows.map((r: any) => r.indexname);
+    expect(names).toContain('posts_slug_unique');
+    expect(names).toContain('posts_author_id_index');
+  });
+});
+```
+
+## Examples
+
+| Change | Strategy | Downtime Risk |
+|--------|----------|---------------|
+| Add nullable column | Single migration | None |
+| Add NOT NULL column | 3-step: add nullable, backfill, add constraint | None |
+| Rename column | Expand-contract with sync trigger | None |
+| Drop column | Remove from app code first, then drop | None if app deployed first |
+| Add index | `CREATE INDEX CONCURRENTLY` (PG) | None |
+| Change column type | Add new column, migrate, swap | None |
+
+## Checklist
+- [ ] Every schema change has an up and down migration
+- [ ] Migrations are idempotent (re-running does not fail)
+- [ ] Seeds use upsert to be safely re-runnable
+- [ ] Column additions are nullable or have defaults (non-breaking)
+- [ ] Destructive changes use expand-contract pattern over multiple deploys
+- [ ] Indexes created with `CONCURRENTLY` option on production databases
+- [ ] Migration tests verify apply, rollback, and expected schema
+- [ ] Backfill migrations process data in batches to avoid lock contention

package/assets/skills/database-patterns.md

@@ -0,0 +1,219 @@
+---
+name: database-patterns
+description: Design databases for performance and safety — indexes, N+1 prevention, pooling, migrations, and row-level security.
+---
+
+# Database Patterns
+
+## When to Use
+
+Apply these patterns when designing schemas, writing queries, or operating
+databases in production. Most performance problems are database problems — a
+missing index or N+1 query can make a 10ms page take 10 seconds. Fix these
+at design time, not after users complain.
+
+## How It Works
+
+### 1. Indexing Strategy
+
+Create indexes for columns in WHERE, JOIN, and ORDER BY clauses.
+
+```sql
+-- Single column: filter by status
+CREATE INDEX idx_orders_status ON orders(status);
+
+-- Composite: filter by user + sort by date
+CREATE INDEX idx_orders_user_created ON orders(user_id, created_at DESC);
+
+-- Partial: only index active rows
+CREATE INDEX idx_active_users ON users(email) WHERE deleted_at IS NULL;
+
+-- Covering: index includes all selected columns (index-only scan)
+CREATE INDEX idx_orders_cover ON orders(user_id, status) INCLUDE (total, created_at);
+```
+
+Column order in composite indexes matters. The leftmost column must appear in
+the query for the index to be used. `(user_id, status)` works for queries
+filtering by `user_id` alone or `user_id + status`, but not `status` alone.
+
+Always verify with EXPLAIN:
+
+```sql
+EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 'usr_123' AND status = 'pending';
+-- Look for: Index Scan, not Seq Scan
+-- Check: actual time, rows examined vs returned
+```
+
+### 2. N+1 Query Prevention
+
+The N+1 problem: 1 query to get 50 users, then 50 queries to get each user's
+orders.
+
+```typescript
+// Bad — N+1
+const users = await db.user.findMany();
+for (const user of users) {
+  user.orders = await db.order.findMany({ where: { userId: user.id } });
+}
+
+// Good — eager load (2 queries total)
+const users = await db.user.findMany({
+  include: { orders: { where: { status: 'active' } } },
+});
+
+// Good — manual batch with IN clause
+const users = await db.user.findMany();
+const userIds = users.map((u) => u.id);
+const orders = await db.order.findMany({
+  where: { userId: { in: userIds } },
+});
+const ordersByUser = groupBy(orders, 'userId');
+```
+
+For GraphQL, use DataLoader to batch and deduplicate within a request:
+
+```typescript
+const userLoader = new DataLoader(async (ids: string[]) => {
+  const users = await db.user.findMany({ where: { id: { in: ids } } });
+  const map = new Map(users.map((u) => [u.id, u]));
+  return ids.map((id) => map.get(id) ?? null);
+});
+```
+
+### 3. Connection Pooling
+
+Every database connection consumes memory. Pool and limit them.
+
+```typescript
+// Prisma — configure in connection string
+// postgresql://user:pass@host:5432/db?connection_limit=10&pool_timeout=30
+
+// Node pg pool
+const pool = new Pool({
+  max: 20,                // max connections
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 5000,
+});
+```
+
+Production sizing rule: start with `max = (2 * CPU cores) + disk spindles`.
+For a 2-core VPS with SSD, 5-10 connections is often optimal.
+
+### 4. Migration Best Practices
+
+```sql
+-- Always use IF NOT EXISTS / IF EXISTS for safety
+CREATE TABLE IF NOT EXISTS audit_logs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  action TEXT NOT NULL,
+  user_id UUID REFERENCES users(id),
+  payload JSONB,
+  created_at TIMESTAMPTZ DEFAULT now()
+);
+
+-- Add columns as nullable first, backfill, then add NOT NULL
+ALTER TABLE users ADD COLUMN phone TEXT;
+-- Backfill: UPDATE users SET phone = '' WHERE phone IS NULL;
+-- Then: ALTER TABLE users ALTER COLUMN phone SET NOT NULL;
+```
+
+Rules:
+- Never rename or drop a column in a single migration — it breaks running code
+- Instead: add new column, deploy code that reads both, migrate data, deploy
+  code that reads only new, drop old column
+- Keep migrations small and reversible
+- Test migrations against a production-size dataset before deploying
+
+### 5. Read Replicas
+
+Route read-heavy queries to replicas, writes to the primary.
+
+```typescript
+const primary = new Pool({ connectionString: process.env.DATABASE_PRIMARY });
+const replica = new Pool({ connectionString: process.env.DATABASE_REPLICA });
+
+function getPool(operation: 'read' | 'write'): Pool {
+  return operation === 'write' ? primary : replica;
+}
+
+// Be aware of replication lag — after a write, read from primary briefly
+async function createAndReturn(data: CreateInput) {
+  const created = await primary.query('INSERT INTO ... RETURNING *', [data]);
+  return created.rows[0]; // read from primary, not replica
+}
+```
+
+### 6. Row-Level Security (PostgreSQL)
+
+Let the database enforce access control, not just the application.
+
+```sql
+-- Enable RLS on the table
+ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
+
+-- Users can only see their own documents
+CREATE POLICY user_documents ON documents
+  USING (owner_id = current_setting('app.current_user_id')::uuid);
+
+-- Admins can see everything
+CREATE POLICY admin_all ON documents
+  USING (current_setting('app.current_role') = 'admin');
+```
+
+Set the session variable before queries:
+
+```typescript
+await pool.query(`SET app.current_user_id = $1`, [userId]);
+await pool.query(`SET app.current_role = $1`, [userRole]);
+const docs = await pool.query('SELECT * FROM documents'); // RLS filters automatically
+```
+
+### 7. Soft Deletes and Archival
+
+```sql
+ALTER TABLE orders ADD COLUMN deleted_at TIMESTAMPTZ;
+
+-- Partial index for non-deleted rows (most queries)
+CREATE INDEX idx_orders_active ON orders(user_id, created_at)
+  WHERE deleted_at IS NULL;
+
+-- View for convenience
+CREATE VIEW active_orders AS
+  SELECT * FROM orders WHERE deleted_at IS NULL;
+```
+
+### 8. JSONB for Flexible Data
+
+```sql
+-- Store semi-structured metadata
+ALTER TABLE events ADD COLUMN metadata JSONB DEFAULT '{}';
+
+-- Index for fast key lookups
+CREATE INDEX idx_events_metadata ON events USING GIN (metadata);
+
+-- Query nested fields
+SELECT * FROM events WHERE metadata->>'source' = 'api';
+SELECT * FROM events WHERE metadata @> '{"tags": ["urgent"]}';
+```
+
+## Examples
+
+| Problem | Solution |
+|---------|----------|
+| Slow list queries | Composite index on filter + sort columns |
+| 50 queries per page load | Eager loading or DataLoader batching |
+| 100 idle connections | Connection pooling with max 10-20 |
+| Column rename breaks prod | Two-phase migration (add, migrate, drop) |
+| Multi-tenant data leaks | Row-level security policies |
+
+## Checklist
+
+- [ ] Every foreign key column has an index
+- [ ] Composite indexes match the most common query patterns
+- [ ] `EXPLAIN ANALYZE` is run for new queries touching large tables
+- [ ] No N+1 queries — verified with query logging in development
+- [ ] Connection pool max is tuned to server capacity (not default 100)
+- [ ] Migrations are backward-compatible — no column drops or renames in one step
+- [ ] Read replicas handle read-heavy workloads with replication lag awareness
+- [ ] Sensitive tables use row-level security or application-level tenant filtering
+- [ ] JSONB columns have GIN indexes when queried frequently