Drizzle ORM Conventions

drizzledatabasetypescript

Conventions for writing type-safe, performant database code with Drizzle ORM, covering schema definition, migrations, query patterns, and transaction handling.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

# Drizzle ORM Conventions ## Schema Definition - Define all schemas in `src/db/schema/`. One file per domain entity: `users.ts`, `orders.ts`, `products.ts`. - Re-export all schemas from `src/db/schema/index.ts` for easy imports. - Use `pgTable` / `mysqlTable` / `sqliteTable` — match the function to your database. - Name tables in `snake_case` plural: `users`, `order_items`, `refresh_tokens`. - Name columns in `snake_case`: `.name('first_name')` or configure `casing: 'snake_case'` globally. ## Column Conventions - Always define a primary key: prefer `id: uuid('id').primaryKey().defaultRandom()` over serial integers for new tables. - Add `createdAt` and `updatedAt` to every mutable entity table: ```ts createdAt: timestamp('created_at').defaultNow().notNull(), updatedAt: timestamp('updated_at').defaultNow().$onUpdate(() => new Date()).notNull(), ``` - Use `notNull()` unless the column is genuinely optional. Null safety is enforced at the schema level. - Use `text()` for variable-length strings. Use `varchar(n)` only when a strict length limit is a DB-level constraint. - Use `boolean()` for flags, `integer()` for counts, `numeric(p, s)` for money (never `float`). ## Relations - Define relations using `relations()` helper in the same schema file as the table. - Use explicit foreign key constraints: `.references(() => users.id, { onDelete: 'cascade' })`. - Name foreign key columns consistently: `userId`, `orderId`, `productId` (camelCase in TS, `user_id` in DB). - Define both sides of a relation (one and many) for accurate type inference. ## Migrations - Use `drizzle-kit generate` to generate migrations — never write migrations by hand. - Store migrations in `src/db/migrations/`. Commit all generated migration files. - Run migrations at application startup (for small apps) or via a dedicated migration job (for production). - Never modify a committed migration file — generate a new one for corrections. - Review generated SQL before applying to production — `drizzle-kit generate` + `drizzle-kit migrate --dry-run`. ## Query Patterns - Import `db` from a single `src/db/index.ts` module. Never instantiate `drizzle()` in application code. - Use the query builder (not raw SQL) for all standard CRUD. Use `db.execute(sql\`...\`)` only for complex queries that the builder cannot express. - Select only needed columns: `db.select({ id: users.id, email: users.email }).from(users)` — avoid `select *` for large tables. - Use `db.query.users.findFirst()` / `findMany()` for relational queries with typed `with:` eager loading. - Always add `limit()` to `findMany()` queries — never return unbounded result sets. ## Filtering & Ordering - Use Drizzle's `eq`, `and`, `or`, `gt`, `gte`, `lt`, `lte`, `like`, `inArray` helpers — never string interpolation. - Always parameterize values. Raw SQL via `sql\`...\`` must use `sql.placeholder()` or `sql\`${value}\`` (auto-escaped). - Apply `orderBy()` explicitly. Do not rely on database default ordering for pagination. ## Transactions - Use `db.transaction(async (tx) => { ... })` for operations that must be atomic. - Pass `tx` instead of `db` to all operations inside a transaction. - Roll back by throwing inside the transaction callback — Drizzle handles rollback automatically. - Keep transactions short — do not perform external HTTP calls or long computations inside a transaction. ## Anti-Patterns - Do not use `db.execute(sql\`SELECT * FROM ${tableName}\`)` with dynamic table names — this is a SQL injection risk. - Do not call `db.query` from UI components in Next.js pages — always go through a server action or API route. - Do not store `db` in React state or context — it is a singleton module export. - Do not skip migrations for schema changes — modify the schema file and generate a migration.

CLI

npx mindaxis apply drizzle-orm-rules --target cursor --scope project

Используется в паках

Frontend Build Tooling

Vite, Webpack, Turbo, and modern frontend build pipeline setup

Открыть пак →

← Правила