Db Migrations

---
name: db-migrations
description: Create a database migration with Drizzle on a fresh Neon branch. Use when changing the packages/db schema or generating migrations.
---

# DB migrations

- Always spin up a new neon branch to create migrations. Update our root .env files to point at the neon branch locally.
- Use drizzle to manage the migration. You can see the schema at packages/db/src/schema. Generating a migration is fine; never *apply* one yourself, and never against a shared or production database; migrations apply through the normal deploy flow.
- Create migrations by changing drizzle schema then running `bunx drizzle-kit generate --name="<sample_name_snake_case>"`
- `NEON_ORG_ID` and `NEON_PROJECT_ID` env vars are set in .env
- list_projects tool requires org_id passed in
- **NEVER manually edit files in `packages/db/drizzle/`** - this includes `.sql` migration files, `meta/_journal.json`, and snapshot files. These are auto-generated by Drizzle. Change only the schema files in `packages/db/src/schema/` and let `drizzle-kit generate` write the migration (hand-edits to generated files require explicit user confirmation).