ravnhq/tech-drizzle

Drizzle ORM TypeSafe Database Access

Lightweight, headless TypeScript ORM with zero dependencies. Drizzle excels at:

• Type inference — Full TypeScript types from schema; no generated types or separate schema language
• Relational queries — Fetch nested data with .with() without manual joins
• Prepared statements — Pre-compile queries for repeated execution; significant performance boost
• Migrations — Version-controlled schema changes with drizzle-kit; rollback support
• Transactions — Atomic multi-operation commits with savepoints for nested transactions

Core patterns: one table per file, relational API for nested queries, prepared statements for hot paths, transactions for consistency.

Workflow

When working with Drizzle ORM:

1. Design schema — Tables, columns, constraints; one file per table
2. Define relations — defineRelations() for one-to-many, many-to-many; enables nested queries
3. Choose query style — Relational API for nested data (prefer), SQL builder for flexibility
4. Optimize hot paths — Use prepared statements with placeholders for repeated queries
5. Handle transactions — Wrap multi-operation writes in db.transaction()
6. Test migrations — drizzle-kit migrate:dev before push; review generated SQL
7. Type extraction — Use InferSelectModel for runtime types from schema

Rules

Patterns are organized by concern:

• Schema — Table design, column types, constraints, one file per table
• Relational Queries — with() for nested data, partial columns, filtering
• Query Builder — SQL builder for aggregations and complex queries
• Prepared Statements — Pre-compile for performance; use placeholders for parameters
• Migrations — Version control, review SQL, push vs generate
• Transactions — Atomic operations, savepoints, error handling

See rules/ for implementation patterns and examples.

Examples

Positive Trigger

User: "Define a Drizzle schema for orders with relations to users and products."

Expected behavior: Use tech-drizzle guidance, apply schema design with relational queries and type inference.

Non-Trigger

User: "Write a raw SQL migration for adding a column to the users table."

Expected behavior: Do not prioritize tech-drizzle; choose a more relevant skill or proceed without it.

• Error: Running unprepared queries in tight loops

• Cause: Query compiled every execution; no reuse of parsed SQL

• Solution: Use .prepare() with placeholders; execute multiple times with different params

• Error: Manual joins in code; fetching parent then children separately

• Cause: Not using relational API; writing complex join logic

• Solution: Define relations, use .with() to fetch nested data in single query

Troubleshooting

• Error: Column not included in result when selecting from relation

• Cause: Selecting from nested relation without explicitly including columns

• Solution: Use columns: { id: true, name: true } to specify nested relation columns

• Error: Transaction rolls back unexpectedly; no clear error

• Cause: Unhandled promise rejection inside db.transaction()

• Solution: Wrap transaction operations in try/catch; all errors must be caught

• Error: Schema types not updating after migration

• Cause: drizzle-kit didn't regenerate types; cache stale

• Solution: Run drizzle-kit generate after migration changes