drizzle-best-practices
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
- 最近更新
- 2026-07-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- drizzle-best-practices
- license
- MIT
- 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." }
- 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.
- compatibility
- TypeScript projects using Node.js or edge runtimes with drizzle-orm and a PostgreSQL database.
02 资源文件 29
- 其他.gitignore72 B
- 参考文档AGENTS.md3.5 KB
- 参考文档CLAUDE.md3.5 KB
- 参考文档evals/evals.json2.6 KB
- 参考文档evals/fixtures/eval-2/package.json438 B
- 许可证LICENSE1.0 KB
- 参考文档README.md6.5 KB
- 参考文档references/_sections.md3.2 KB
- 参考文档references/advanced-dynamic-queries.md3.5 KB
- 参考文档references/advanced-sql-operator.md4.5 KB
- 参考文档references/driver-postgres.md5.0 KB
- 参考文档references/driver-serverless.md4.7 KB
- 参考文档references/engine-postgres.md7.5 KB
- 参考文档references/migrations-config.md2.8 KB
- 参考文档references/migrations-workflow.md4.6 KB
- 参考文档references/perf-batch-operations.md3.2 KB
- 参考文档references/perf-prepared-statements.md2.7 KB
- 参考文档references/query-error-handling.md6.3 KB
- 参考文档references/query-filters-operators.md3.0 KB
- 参考文档references/query-mutations.md3.8 KB
- 参考文档references/query-select-patterns.md4.0 KB
- 参考文档references/relations-defining.md6.0 KB
- 参考文档references/relations-querying.md7.5 KB
- 参考文档references/schema-column-types.md3.5 KB
- 参考文档references/schema-indexes-constraints.md4.0 KB
- 参考文档references/schema-table-definitions.md3.0 KB
- 参考文档references/types-custom-types.md3.8 KB
- 参考文档references/types-inference.md3.5 KB
- 参考文档references/types-validators.md4.1 KB
03 SKILL.md 正文
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:
@latestis still0.45.2, not v1.npm i drizzle-ormdoes not get you v1 — a new project that wants the v1 API must ask for@rcexplicitly.- 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 rewritedb.select()operator filters into the relational object syntax. - On v1, the relational query API (
db.query) is driven bydefineRelations. Passing a legacyschemadoes not populatedb.query. The oldrelations()helper is still importable fromdrizzle-orm/_relationsso existing relation modules keep compiling during a port, but to query relationally on v1 you convert them todefineRelations. (Earlier betas exposed adb._querypath; it was removed before1.0.0-rc.3.) Seereferences/relations-defining.md.
When the version is unstated, default to v1 (RC) for new code, but match the existing codebase's
API if you already see legacy relations() / callback-style db.query patterns in use. Throughout
the reference files, version-specific differences are marked with "Legacy (v0.45.x)" callouts.
When to Apply
Reference these guidelines when:
- Defining table schemas with
pgTable - Writing select, insert, update, or delete queries
- Setting up relations between tables using
defineRelationsor the legacyrelationsAPI - Configuring
drizzle-kitfor migrations (generate,push,pull) - Inferring TypeScript types from your schema
- Choosing between the SQL-like API and the relational query API
- Optimizing query performance with prepared statements or batch operations
- Integrating Drizzle with serverless Postgres providers (Neon, Supabase, etc.)
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Schema Design | CRITICAL | schema- |
| 2 | Query Patterns | CRITICAL | query- |
| 3 | Relations | HIGH | relations- |
| 4 | Migrations | HIGH | migrations- |
| 5 | Type Safety | MEDIUM-HIGH | types- |
| 6 | Performance | MEDIUM | perf- |
| 7 | Database Drivers | MEDIUM | driver- |
| 8 | Advanced Patterns | LOW | advanced- |
How to Use
Read individual reference files for detailed explanations and code examples:
references/engine-postgres.md # Postgres-specific types, features, and patterns
references/schema-table-definitions.md
references/query-select-patterns.md
references/relations-defining.md
references/_sections.md # Full index of all references
Each reference file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Links to official Drizzle documentation
References
04 同仓库更多 Skills
vue
Use when editing .vue files, creating Vue 3 components, writing composables, or testing Vue code - provides Composition API patterns, props/emits best practices, VueUse integration, and reactive destructuring guidance
setup-solidity-contracts
Set up a Solidity smart contract project with OpenZeppelin Contracts. Use when users need to: (1) create a new Hardhat or Foundry project, (2) install OpenZeppelin Contracts dependencies for Solidity, (3) configure remappings for Foundry, or (4) understand Solidity import conventions for OpenZeppelin.
nuxthub
Use when building NuxtHub v0.10.6 applications - provides database (Drizzle ORM with sqlite/postgresql/mysql), KV storage, blob storage, and cache APIs. Covers configuration, schema definition, migrations, multi-cloud deployment (Cloudflare, Vercel), and the new hub:db, hub:kv, hub:blob virtual module imports.
nuxt
Nuxt application development and maintenance. Use for project structure, pages and routing, data fetching, SSR-safe state, middleware, plugins, server routes, runtime config, route rules, layers, built-in components, hydration, upgrades, and testing.
develop-secure-contracts
Develop secure smart contracts using OpenZeppelin Contracts libraries. Use when users need to integrate OpenZeppelin library components — including token standards (ERC20, ERC721, ERC1155), access control (Ownable, AccessControl, AccessManager), security primitives (Pausable, ReentrancyGuard), governance (Governor, timelocks), or accounts (multisig, account abstraction) — into existing or new contracts. Covers pattern discovery from library source, CLI contract generators, and library-first integration. Supports Solidity, Cairo, Stylus, Stellar, and Sui Move.