gh-jezweb-claude-skills-skills-drizzle-orm-d1/references/migration-workflow.md

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:

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

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:

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

4. Apply to Local Database

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

5. Test Locally

npm run dev
# Test your changes

6. Commit Migration

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

7. Deploy Code

npm run deploy

8. Apply to Production

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

# 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:

-- 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);