database-development

vm0-ai's avatarfrom vm0-ai

Database migrations and Drizzle ORM guidelines for the vm0 project

⭐38stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026
[SQL and Databases]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for managing database migrations and Drizzle ORM workflows within a development environment. It streamlines the process of schema synchronization, manual SQL migration handling, and critical journal maintenance to ensure database integrity and seamless CI/CD integration.

Use Cases

  • Automated Schema Evolution: Efficiently generate and apply migration files from TypeScript schema changes using standardized Drizzle ORM commands.
  • Manual Migration Management: Execute complex database refactoring, such as column renames or advanced ALTER statements, with a structured workflow that includes manual SQL script creation and journal entry validation.
  • CI/CD Pipeline Reliability: Prevent deployment failures by following strict protocols for migration metadata tracking, ensuring all changes are recognized by automated testing and deployment environments.
  • Local Development & Debugging: Facilitate rapid local setup and data inspection using integrated tools like Drizzle Studio and automated migration scripts.
nameDatabase Development
descriptionDatabase migrations and Drizzle ORM guidelines for the vm0 project

Database Development

Commands

cd turbo/apps/web

pnpm db:generate   # Generate migration from schema changes
pnpm db:migrate    # Run pending migrations
pnpm db:studio     # Open Drizzle Studio UI

Critical: _journal.json

Manual migrations MUST have an entry in src/db/migrations/meta/_journal.json.

Without this entry, the migration will NOT run and CI will fail.

{
  "idx": 25,                           // Next sequential number
  "version": "7",                      // Always "7"
  "when": 1765000000000,               // Timestamp (ms)
  "tag": "0025_my_migration",          // Must match filename without .sql
  "breakpoints": true
}

Migration Workflows

Auto-Generated (simple changes)

# 1. Edit schema in src/db/schema/
# 2. Generate (auto-updates _journal.json)
pnpm db:generate
# 3. Run locally
pnpm db:migrate

Manual (renames, complex ALTER)

# 1. Create: src/db/migrations/XXXX_name.sql
# 2. Add entry to _journal.json  ← DON'T FORGET!
# 3. Update schema file to match
# 4. Run locally
pnpm db:migrate

Checklist

Before committing:

  • Schema file updated in src/db/schema/
  • Schema exported in src/db/db.ts (if new table)
  • _journal.json updated (manual migrations)
  • pnpm db:migrate works locally
  • pnpm test passes