pitfalls-drizzle-orm

name	pitfalls-drizzle-orm
description	Drizzle ORM patterns and migration safety rules. Use when defining schemas, running migrations, or debugging database issues. Triggers on: Drizzle, schema, migration, db:push, $inferSelect, array column.

Drizzle ORM Pitfalls

Common pitfalls and correct patterns for Drizzle ORM.

When to Use

• Defining database schemas
• Running migrations (db:push)
• Creating insert/select types
• Working with array columns
• Reviewing Drizzle ORM code

Workflow

Step 1: Verify Schema Types

Check that types are exported correctly.

Step 2: Check Array Syntax

Verify array columns use correct syntax.

Step 3: Test Migrations Safely

Never change primary key types in production.

---

Critical Rules

// ❌ NEVER change primary key types
// serial → varchar or varchar → uuid BREAKS migrations

// ✅ Array columns - correct syntax
allowedTokens: text('allowed_tokens').array()  // CORRECT
// ❌ WRONG: array(text('allowed_tokens'))

// ✅ Always create insert/select types
export type Strategy = typeof strategies.$inferSelect;
export type NewStrategy = typeof strategies.$inferInsert;

// ✅ Use drizzle-zod for validation
import { createInsertSchema } from 'drizzle-zod';
export const insertStrategySchema = createInsertSchema(strategies);

Migration Safety

# Safe schema sync
npm run db:push

# If data-loss warning and you're sure
npm run db:push --force

# NEVER in production without backup

Type Inference Pattern

// ✅ Infer types from schema
import { strategies } from './schema';

type Strategy = typeof strategies.$inferSelect;
type NewStrategy = typeof strategies.$inferInsert;

// ✅ With Zod validation
import { createInsertSchema, createSelectSchema } from 'drizzle-zod';
import { z } from 'zod';

const insertSchema = createInsertSchema(strategies);
type StrategyInput = z.infer<typeof insertSchema>;

Quick Checklist

• No primary key type changes
• Array columns use text().array() syntax
• Insert/select types exported for models
• Using drizzle-zod for validation
• Migration tested in dev before prod