| name | drizzle-best-practices |
| description | Use this skill whenever the user is working with Drizzle ORM on PostgreSQL. This covers any mention of Drizzle, drizzle-orm, drizzle-kit, drizzle-zod, `pgTable`, `defineRelations`, `relations()`, `db.select()`, `db.query`, or insert/update/delete against Postgres.
Typical intents to trigger on:
- Designing or debugging Postgres table schemas, columns, identity PKs, enums, JSONB, arrays
- Modeling one-to-many or many-to-many relations and join tables in Drizzle
- Writing, optimizing, or preparing Drizzle queries (placeholders, `.prepare()`)
- Generating Zod validators from Drizzle tables
- Setting up TypeScript + Postgres projects (Neon, Supabase, postgres.js, node-postgres) with Drizzle
- Migrating from Prisma, TypeORM, or Sequelize **to Drizzle**
- Resolving Drizzle type errors; choosing between v1 RC and 0.45.x APIs
Do NOT trigger for Drizzle with MySQL/SQLite, raw SQL without an ORM, or other ORMs when Drizzle is not the target.
|
| license | MIT |
| compatibility | TypeScript projects using Node.js or edge runtimes with drizzle-orm and a PostgreSQL database. |
| metadata | {"author":"Marc A. Maceira Zayas","abstract":"Comprehensive Drizzle ORM best practices guide for TypeScript developers building on PostgreSQL. Contains guidance across 8 categories from critical (schema design, query patterns) to incremental (advanced features). Each reference includes explanations, correct vs incorrect code examples, and rationale for why the pattern matters. Engine-specific Postgres patterns (identity columns, JSONB, arrays, enums, etc.) are documented in a dedicated reference file to keep the skill modular.\n"} |
Drizzle ORM Best Practices (PostgreSQL)
Comprehensive best practices guide for Drizzle ORM with PostgreSQL. Contains guidance across
8 categories, prioritized by impact to help you write correct, performant, and maintainable
database code.
Version & API Detection (read this first)
Drizzle is mid-transition to v1, and the relations + relational-query APIs differ between
the two major lines. Check the project's package.json before writing code so you emit the
right syntax:
Installed drizzle-orm | API to use | Install command |
|---|
^1.0.0-rc or ^1.0.0-beta | v1 — the default in this skill. defineRelations, object-syntax relational queries (where: { … }, orderBy: { … }), validators from drizzle-orm/zod | npm i drizzle-orm@rc + npm i -D drizzle-kit@rc |
^0.4x (e.g. 0.45.2) | Legacy. relations() helper, callback/operator relational queries, validators from the separate drizzle-zod package | npm i drizzle-orm (resolves to 0.45.2) |
The current release candidate is drizzle-orm@1.0.0-rc.3 (the @rc tag), which supersedes the
older @beta tag the docs still reference in places.
Three things that routinely trip up agents:
@latest is still 0.45.2, not v1. npm i drizzle-orm does not get you v1 — a new project
that wants the v1 API must ask for @rc explicitly.- The SQL-like query builder is unchanged across versions.
db.select().from(t).where(eq(t.id, 1)),
db.insert(), db.update(), db.delete() work identically in 0.45.x and v1. Only the relational
query API (db.query) and relation definitions changed. Never rewrite db.select() operator
filters into the relational object syntax.
