Database work is high-risk in Neexo projects 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 push for local development against throwaway databases
Use drizzle-kit migrate for production deployments with migration tracking
Drizzle Kit Workflow
# 1. Edit schema file (e.g. src/db/schema.ts)
# 2. Push to local dev database
npx drizzle-kit push
# 3. Generate migration SQL for production
npx drizzle-kit generate
# 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 — 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 this into your project — e.g. .instructions.md, .agent.md, or SKILL.md
## Overview
Database work is high-risk in Neexo projects 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 push` for local development against throwaway databases
- Use `drizzle-kit migrate` for production deployments with migration tracking
## Drizzle Kit Workflow
```bash
# 1. Edit schema file (e.g. src/db/schema.ts)
# 2. Push to local dev database
npx drizzle-kit push
# 3. Generate migration SQL for production
npx drizzle-kit generate
# 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 — 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