# Migration Workflow

Complete guide to database migrations with Drizzle Kit and Wrangler.

---

## Generate vs Push

### `drizzle-kit generate`
- Creates SQL migration files in `./migrations`
- Versioned, trackable in Git
- Can be reviewed before applying
- **Recommended for production**

### `drizzle-kit push`
- Pushes schema directly to database
- No SQL files generated
- Fast for prototyping
- **Not recommended for production**

---

## Complete Workflow

### 1. Make Schema Changes

Edit `src/db/schema.ts`:

```typescript
export const users = sqliteTable('users', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  email: text('email').notNull().unique(),
  name: text('name').notNull(),
  // Add new field
  role: text('role').notNull().default('user'),
});
```

### 2. Generate Migration

```bash
npx drizzle-kit generate
# or
npm run db:generate
```

Output:
```
Generated migration:
./migrations/0002_add_user_role.sql
```

### 3. Review Generated SQL

Check `./migrations/0002_add_user_role.sql`:

```sql
ALTER TABLE users ADD COLUMN role text DEFAULT 'user' NOT NULL;
```

### 4. Apply to Local Database

```bash
npx wrangler d1 migrations apply my-database --local
# or
npm run db:migrate:local
```

### 5. Test Locally

```bash
npm run dev
# Test your changes
```

### 6. Commit Migration

```bash
git add migrations/0002_add_user_role.sql
git commit -m "Add user role field"
git push
```

### 7. Deploy Code

```bash
npm run deploy
```

### 8. Apply to Production

```bash
npx wrangler d1 migrations apply my-database --remote
# or
npm run db:migrate:remote
```

---

## Best Practices

1. **Always test locally first**
2. **Review generated SQL** before applying
3. **Commit migrations to Git**
4. **Apply migrations in CI/CD** for production
5. **Never skip migrations** - apply in order
6. **Backup production database** before major changes

---

## Troubleshooting

### Migration Fails

```bash
# Delete failed migration
rm migrations/0002_bad_migration.sql

# Regenerate
npx drizzle-kit generate
```

### Need to Rollback

D1 doesn't support automatic rollback. Options:
1. Create a new migration to reverse changes
2. Restore from backup
3. Manually edit data with SQL

---

## Migration Naming

Drizzle auto-generates names like:
- `0001_initial_schema.sql`
- `0002_add_user_role.sql`
- `0003_create_posts_table.sql`

---

## Advanced: Custom Migrations

Sometimes you need custom SQL:

```sql
-- migrations/0004_custom.sql

-- Add data
INSERT INTO users (email, name, role) VALUES
  ('admin@example.com', 'Admin', 'admin');

-- Update existing data
UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';

-- Create index
CREATE INDEX idx_users_role ON users(role);
```