@mr.dj2u/knowledge 0.1.0

package/dist/content/patterns/database/migrations.md

@@ -0,0 +1,365 @@
+# Drizzle Migrations Pattern
+
+## Description
+
+Migrations are TypeScript files generated by Drizzle that track database schema changes over time. They provide version control for your database structure, enabling rollback, forward migration, and reproducible deployments across environments. Migrations are auto-generated when you modify schema files and run `drizzle-kit generate`.
+
+## When to Use
+
+**Generate migrations when:**
+- ✅ Adding or removing table columns
+- ✅ Creating new tables
+- ✅ Modifying column types or constraints
+- ✅ Adding/removing indexes
+- ✅ Changing relationships or foreign keys
+- ✅ Preparing for production deployment
+- ✅ Collaborating with team (schema changes shared via git)
+
+## Core Concepts
+
+**Migration Lifecycle:**
+1. Define schema changes in TypeScript (`*Schema.ts` files)
+2. Run `drizzle-kit generate` → generates SQL migration file
+3. Review migration SQL (in `drizzle/` folder)
+4. Apply migration with `drizzle-kit migrate`
+5. Migration recorded in `__drizzle_migrations_journal__` table
+6. Future deployments run only unapplied migrations
+
+**Why Migrations Matter:**
+- **Version Control**: Track all schema changes with git
+- **Reproducibility**: Any environment can reach exact schema state
+- **Rollback Safety**: Each migration can be reversed
+- **Collaborative**: Team members sync schema via migrations
+- **Auditability**: See who changed what and when
+
+## Code Examples
+
+### Schema Definition (Input for Migrations)
+
+```typescript
+// File: src/db/usersSchema.ts
+import { pgTable, uuid, text, timestamp, integer } from 'drizzle-orm/pg-core';
+
+export const users = pgTable('users', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  email: text('email').notNull().unique(),
+  username: text('username').notNull().unique(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});
+
+// File: src/db/postsSchema.ts
+export const posts = pgTable('posts', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  userId: uuid('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  title: text('title').notNull(),
+  content: text('content').notNull(),
+  likes: integer('likes').default(0).notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+});
+```
+
+### Generated Migration File
+
+```sql
+-- File: drizzle/0001_create_users_table.sql
+CREATE TABLE IF NOT EXISTS users (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  email TEXT NOT NULL UNIQUE,
+  username TEXT NOT NULL UNIQUE,
+  created_at TIMESTAMP NOT NULL DEFAULT now(),
+  updated_at TIMESTAMP NOT NULL DEFAULT now()
+);
+
+-- File: drizzle/0002_create_posts_table.sql
+CREATE TABLE IF NOT EXISTS posts (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  likes INTEGER NOT NULL DEFAULT 0,
+  created_at TIMESTAMP NOT NULL DEFAULT now()
+);
+```
+
+### Applying Migrations
+
+```typescript
+// File: src/db/migrate.ts
+import { migrate } from 'drizzle-orm/postgres-js/migrator';
+import { db, client } from './index';
+import path from 'path';
+
+/**
+ * Run pending migrations
+ * This updates the database schema to match current schema files
+ */
+export async function runMigrations() {
+  try {
+    console.log('Running migrations...');
+    await migrate(db, {
+      migrationsFolder: path.join(process.cwd(), 'drizzle'),
+    });
+    console.log('Migrations completed!');
+  } catch (error) {
+    console.error('Migration failed:', error);
+    throw error;
+  }
+}
+
+// File: api-server.ts (on startup)
+import { runMigrations } from './db/migrate';
+
+async function startServer() {
+  try {
+    // Run migrations before starting server
+    await runMigrations();
+    
+    // Start Express server
+    app.listen(PORT, () => {
+      console.log(`Server running on port ${PORT}`);
+    });
+  } catch (error) {
+    console.error('Server startup failed:', error);
+    process.exit(1);
+  }
+}
+```
+
+### Schema Modification Example
+
+```typescript
+// File: src/db/usersSchema.ts
+// BEFORE: Original schema
+export const users = pgTable('users', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  email: text('email').notNull().unique(),
+  username: text('username').notNull().unique(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});
+
+// AFTER: Added new column
+export const users = pgTable('users', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  email: text('email').notNull().unique(),
+  username: text('username').notNull().unique(),
+  bio: text('bio'),  // NEW COLUMN
+  profileImageUrl: text('profile_image_url'),  // NEW COLUMN
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});
+
+// ✅ Run: npm run db:generate
+// This generates migration file:
+// drizzle/0003_add_user_profile_columns.sql
+```
+
+### Generated Migration for Schema Changes
+
+```sql
+-- File: drizzle/0003_add_user_profile_columns.sql
+-- Migration automatically generated from schema changes
+
+ALTER TABLE users
+ADD COLUMN bio TEXT,
+ADD COLUMN profile_image_url TEXT;
+```
+
+## Migration Workflow
+
+### Development Workflow
+
+```bash
+# Step 1: Modify schema file (e.g., src/db/usersSchema.ts)
+# Add new column, new table, new index, etc.
+
+# Step 2: Generate migration from schema changes
+npm run db:generate
+# Creates: drizzle/XXXX_description.sql
+
+# Step 3: Review generated migration
+cat drizzle/XXXX_description.sql
+
+# Step 4: Apply migration to development database
+npm run db:migrate
+
+# Step 5: Test changes locally
+
+# Step 6: Commit to git
+git add src/db/*Schema.ts drizzle/XXXX_description.sql
+git commit -m "feat: add bio to users table"
+```
+
+### Team Collaboration
+
+```bash
+# Teammate pulls schema changes
+git pull
+
+# New migration file appears in drizzle/
+# Run migrations to sync local database
+npm run db:migrate
+
+# Now both teammates have identical schema
+```
+
+### Production Deployment
+
+```bash
+# In production environment:
+npm install  # Install app + dependencies
+npm run build  # Build app
+npm run db:migrate  # Apply pending migrations
+
+# Server starts with updated schema
+npm run start
+```
+
+## Migration Best Practices
+
+### ✅ DO
+
+1. **Generate migrations for every schema change**
+   ```bash
+   # After modifying schema file
+   npm run db:generate
+   
+   # Creates numbered migration: drizzle/0123_change_name.sql
+   ```
+
+2. **Review migration SQL before applying**
+   ```bash
+   # Always check generated SQL
+   cat drizzle/XXXX_change_name.sql
+   
+   # Verify it matches your intent
+   ```
+
+3. **Commit migrations to git**
+   ```bash
+   git add drizzle/0123_change_name.sql
+   git commit -m "chore: add migration for users table changes"
+   ```
+
+4. **Test migrations in development first**
+   ```bash
+   npm run db:migrate  # Test locally
+   # Verify changes work
+   # Then deploy with confidence
+   ```
+
+5. **Keep migration descriptions clear**
+   ```
+   drizzle/0001_create_users_table.sql
+   drizzle/0002_create_posts_table.sql
+   drizzle/0003_add_likes_to_posts.sql  ✅ Clear
+   drizzle/0004_xyz.sql  ❌ Unclear
+   ```
+
+### ❌ DON'T
+
+1. **Don't manually edit generated migrations**
+   ```sql
+   -- ❌ WRONG - Manual edits get overwritten
+   -- Don't modify drizzle/XXXX.sql directly
+   
+   -- ✅ RIGHT - Regenerate from schema
+   // Modify src/db/schema.ts
+   // Run: npm run db:generate
+   ```
+
+2. **Don't skip migrations in development**
+   ```bash
+   # ❌ WRONG - Database schema out of sync
+   // Modify schema file but don't run migrations
+   
+   # ✅ RIGHT - Apply migrations immediately
+   npm run db:migrate
+   ```
+
+3. **Don't apply migrations without backup**
+   ```bash
+   # ❌ WRONG - Production data at risk
+   npm run db:migrate --production
+   
+   # ✅ RIGHT - Backup first
+   # Backup production database
+   npm run db:migrate --production
+   ```
+
+4. **Don't modify migrations after deployment**
+   ```bash
+   # ❌ WRONG - Team database out of sync
+   # Applied: 0123_users_table.sql
+   # Then: Modify 0123_users_table.sql
+   
+   # ✅ RIGHT - Create new migration
+   // Modify schema file
+   npm run db:generate  # Creates 0124_users_fix.sql
+   npm run db:migrate
+   ```
+
+## Advanced Patterns
+
+### Conditional Migrations
+
+```sql
+-- File: drizzle/0010_add_column_if_not_exists.sql
+-- Check if column exists before adding
+ALTER TABLE users
+ADD COLUMN IF NOT EXISTS bio TEXT;
+```
+
+### Data Migrations
+
+```typescript
+// File: src/db/migrations/0011_populate_defaults.ts
+// Sometimes you need to run code, not just SQL
+
+import { db } from '../index';
+import { users } from '../usersSchema';
+import { eq } from 'drizzle-orm';
+
+export async function populateDefaults() {
+  // Set default values for existing rows
+  await db
+    .update(users)
+    .set({ bio: 'New user' })
+    .where(eq(users.bio, null));
+}
+```
+
+### Rollback Handling
+
+```typescript
+// File: src/db/migrate.ts
+export async function rollbackMigration() {
+  // Drizzle doesn't support automatic rollback
+  // Instead, create inverse migrations:
+  
+  // If migration adds column:
+  // drizzle/0123_add_column.sql
+  //   ALTER TABLE users ADD COLUMN bio TEXT;
+  
+  // Create rollback:
+  // drizzle/0124_remove_column.sql
+  //   ALTER TABLE users DROP COLUMN bio;
+  
+  // Then run forward migration:
+  // npm run db:migrate
+}
+```
+
+## Related Patterns
+
+- [Drizzle Schema](./drizzle-schema.md) — Schema definitions
+- [Relations](./relations.md) — Table relationships
+- [Query Organization](./query-organization.md) — Query patterns
+
+---
+
+*Pattern extracted from production repositories: PokePages, quantum-api*
+*Files: drizzle/ directory, migration workflows from package.json scripts*