Prefer generate + migrate even locally; follow the repo's ban on push if documented
When unsure, use generate + migrate. Project rules win if they forbid push entirely.
Drizzle Kit Workflow
# 1. Edit schema file (e.g. src/db/schema.ts)
# 2. Generate migration SQL
npx drizzle-kit generate
# 3. Apply with migration tracking
npx drizzle-kit migrate
# Optional — throwaway local only
# npx drizzle-kit push
# 4. Commit schema + migration + code together
git add -A && git commit -m "feat(db): add user preferences table"
Query Patterns
Preserve organization, customer, and tenant filters on every query — never return unscoped data
Use Drizzle's type-safe query builder; avoid raw SQL unless performance requires it
Use drizzle-kit studio to inspect data during development — never query production directly
Prefer soft delete (deletedAt timestamp) for financial, audit, and compliance data
Common Pitfalls
Do not run drizzle-kit push against production or shared environments — it applies changes without migration tracking
Do not rename columns in production without a two-step migration (add new → migrate data → drop old)
Do not use drizzle-kit drop without explicit team approval
Raw content
Copy into your project — e.g. .instructions.md, .agent.md, or SKILL.md
## Overview
Database work is high-risk because schema changes often combine tenant scoping, production data, and generated migrations.
## Schema and Migration Rules
- Inspect the relevant schema, migration, query, or action before changing database logic
- Keep schema changes, generated SQL, and dependent code in the **same commit** — never split across commits
- Avoid destructive migrations by default — prefer additive changes (new columns, new tables)
- Use `drizzle-kit generate` to create migration SQL after schema edits
- Use `drizzle-kit migrate` for deployments with migration tracking
## `push` vs migration-bundle products
| Environment | Allowed? |
|-------------|----------|
| Throwaway local DB (ephemeral / personal docker) | `drizzle-kit push` may be OK for fast iteration |
| Shared, staging, or production databases | **Never** `push` — use generate + migrate only |
| Migration-bundle products (CI checks migration SQL) | Prefer generate + migrate even locally; follow the repo's ban on `push` if documented |
When unsure, use `generate` + `migrate`. Project rules win if they forbid `push` entirely.
## Drizzle Kit Workflow
```bash
# 1. Edit schema file (e.g. src/db/schema.ts)
# 2. Generate migration SQL
npx drizzle-kit generate
# 3. Apply with migration tracking
npx drizzle-kit migrate
# Optional — throwaway local only
# npx drizzle-kit push
# 4. Commit schema + migration + code together
git add -A && git commit -m "feat(db): add user preferences table"
```
## Query Patterns
- Preserve organization, customer, and tenant filters on every query — never return unscoped data
- Use Drizzle's type-safe query builder; avoid raw SQL unless performance requires it
- Use `drizzle-kit studio` to inspect data during development — never query production directly
- Prefer soft delete (`deletedAt` timestamp) for financial, audit, and compliance data
## Common Pitfalls
- Do not run `drizzle-kit push` against production or shared environments — it applies changes without migration tracking
- Do not rename columns in production without a two-step migration (add new → migrate data → drop old)
- Do not use `drizzle-kit drop` without explicit team approval