{"name":"drizzle-best-practices","url":"https://skills.sh/honra-io/drizzle-best-practices/drizzle-best-practices","install":"npx skills add honra-io/drizzle-best-practices","sdk":"drizzle","key":"drizzle/drizzle-best-practices","description":"|","hasContent":true,"content":"---\nname: drizzle-best-practices\ndescription: |\n  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.\n\n  Typical intents to trigger on:\n  - Designing or debugging Postgres table schemas, columns, identity PKs, enums, JSONB, arrays\n  - Modeling one-to-many or many-to-many relations and join tables in Drizzle\n  - Writing, optimizing, or preparing Drizzle queries (placeholders, `.prepare()`)\n  - Generating Zod validators from Drizzle tables\n  - Setting up TypeScript + Postgres projects (Neon, Supabase, postgres.js, node-postgres) with Drizzle\n  - Migrating from Prisma, TypeORM, or Sequelize **to Drizzle**\n  - Resolving Drizzle type errors; choosing between v1 RC and 0.45.x APIs\n\n  Do NOT trigger for Drizzle with MySQL/SQLite, raw SQL without an ORM, or other ORMs when Drizzle is not the target.\nlicense: MIT\ncompatibility: TypeScript projects using Node.js or edge runtimes with drizzle-orm and a PostgreSQL database.\nmetadata:\n  author: Marc A. Maceira Zayas\n  abstract: >\n    Comprehensive Drizzle ORM best practices guide for TypeScript developers building on\n    PostgreSQL. Contains guidance across 8 categories from critical (schema design, query\n    patterns) to incremental (advanced features). Each reference includes explanations,\n    correct vs incorrect code examples, and rationale for why the pattern matters.\n    Engine-specific Postgres patterns (identity columns, JSONB, arrays, enums, etc.) are\n    documented in a dedicated reference file to keep the skill modular.\n---\n\n# Drizzle ORM Best Practices (PostgreSQL)\n\nComprehensive best practices guide for Drizzle ORM with PostgreSQL. Contains guidance across\n8 categories, prioritized by impact to help you write correct, performant, and maintainable\ndatabase code.\n\n## Version & API Detection (read this first)\n\nDrizzle is mid-transition to **v1**, and the relations + relational-query APIs differ between\nthe two major lines. **Check the project's `package.json` before writing code** so you emit the\nright syntax:\n\n| Installed `drizzle-orm` | API to use | Install command |\n|---|---|---|\n| `^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` |\n| `^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) |\n\nThe current release candidate is **`drizzle-orm@1.0.0-rc.3`** (the `@rc` tag), which supersedes the\nolder `@beta` tag the docs still reference in places.\n\nThree things that routinely trip up agents:\n\n- **`@latest` is still `0.45.2`, not v1.** `npm i drizzle-orm` does *not* get you v1 — a new project\n  that wants the v1 API must ask for `@rc` explicitly.\n- **The SQL-like query builder is unchanged across versions.** `db.select().from(t).where(eq(t.id, 1))`,\n  `db.insert()`, `db.update()`, `db.delete()` work identically in 0.45.x and v1. Only the relational\n  query API (`db.query`) and relation *definitions* changed. Never rewrite `db.select()` operator\n  filters into the relational object syntax.\n- **On v1, the relational query API (`db.query`) is driven by `defineRelations`.** Passing a\n  legacy `schema` does *not* populate `db.query`. The old `relations()` helper is still importable\n  from `drizzle-orm/_relations` so existing relation modules keep compiling during a port, but to\n  query relationally on v1 you convert them to `defineRelations`. (Earlier betas exposed a\n  `db._query` path; it was removed before `1.0.0-rc.3`.) See `references/relations-defining.md`.\n\nWhen the version is unstated, default to **v1 (RC)** for new code, but match the existing codebase's\nAPI if you already see legacy `relations()` / callback-style `db.query` patterns in use. Throughout\nthe reference files, version-specific differences are marked with **\"Legacy (v0.45.x)\"** callouts.\n\n## When to Apply\n\nReference these guidelines when:\n\n- Defining table schemas with `pgTable`\n- Writing select, insert, update, or delete queries\n- Setting up relations between tables using `defineRelations` or the legacy `relations` API\n- Configuring `drizzle-kit` for migrations (`generate`, `push`, `pull`)\n- Inferring TypeScript types from your schema\n- Choosing between the SQL-like API and the relational query API\n- Optimizing query performance with prepared statements or batch operations\n- Integrating Drizzle with serverless Postgres providers (Neon, Supabase, etc.)\n\n## Rule Categories by Priority\n\n| Priority | Category | Impact | Prefix |\n|----------|----------|--------|--------|\n| 1 | Schema Design | CRITICAL | `schema-` |\n| 2 | Query Patterns | CRITICAL | `query-` |\n| 3 | Relations | HIGH | `relations-` |\n| 4 | Migrations | HIGH | `migrations-` |\n| 5 | Type Safety | MEDIUM-HIGH | `types-` |\n| 6 | Performance | MEDIUM | `perf-` |\n| 7 | Database Drivers | MEDIUM | `driver-` |\n| 8 | Advanced Patterns | LOW | `advanced-` |\n\n## How to Use\n\nRead individual reference files for detailed explanations and code examples:\n\n```\nreferences/engine-postgres.md          # Postgres-specific types, features, and patterns\nreferences/schema-table-definitions.md\nreferences/query-select-patterns.md\nreferences/relations-defining.md\nreferences/_sections.md                # Full index of all references\n```\n\nEach reference file contains:\n\n- Brief explanation of why it matters\n- Incorrect code example with explanation\n- Correct code example with explanation\n- Links to official Drizzle documentation\n\n## References\n\n- https://orm.drizzle.team/docs/overview\n- https://orm.drizzle.team/docs/sql-schema-declaration\n- https://orm.drizzle.team/docs/relations-v2\n- https://orm.drizzle.team/docs/perf-queries\n- https://orm.drizzle.team/docs/kit-overview\n- https://orm.drizzle.team/llms.txt\n","contentSource":"skills.sh/api/download/honra-io/drizzle-best-practices/drizzle-best-practices","contentFetchedAt":"2026-07-27T08:59:30.022Z"}