Drizzle ORM for Cloudflare D1

Status: Production Ready ✅ Last Updated: 2026-01-20 Latest Version: drizzle-orm@0.45.1, drizzle-kit@0.31.8, better-sqlite3@12.5.0 Dependencies: cloudflare-d1, cloudflare-worker-base

---

Quick Start (5 Minutes)

# 1. Install
npm install drizzle-orm
npm install -D drizzle-kit

# 2. Configure drizzle.config.ts
import { defineConfig } from 'drizzle-kit';
export default defineConfig({
  schema: './src/db/schema.ts',
  out: './migrations',
  dialect: 'sqlite',
  driver: 'd1-http',
  dbCredentials: {
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
    databaseId: process.env.CLOUDFLARE_DATABASE_ID!,
    token: process.env.CLOUDFLARE_D1_TOKEN!,
  },
});

# 3. Configure wrangler.jsonc
{
  "d1_databases": [{
    "binding": "DB",
    "database_name": "my-database",
    "database_id": "your-database-id",
    "migrations_dir": "./migrations"  // CRITICAL: Points to Drizzle migrations
  }]
}

# 4. Define schema (src/db/schema.ts)
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
export const users = sqliteTable('users', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  email: text('email').notNull().unique(),
  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(() => new Date()),
});

# 5. Generate & apply migrations
npx drizzle-kit generate
npx wrangler d1 migrations apply my-database --local   # Test first
npx wrangler d1 migrations apply my-database --remote  # Then production

# 6. Query in Worker
import { drizzle } from 'drizzle-orm/d1';
import { users } from './db/schema';
const db = drizzle(env.DB);
const allUsers = await db.select().from(users).all();

---

D1-Specific Critical Rules

✅ Use db.batch() for transactions - D1 doesn't support SQL BEGIN/COMMIT (see Issue #1) ✅ Test migrations locally first - Always --local before --remote ✅ Use integer with mode: 'timestamp' for dates - D1 has no native date type ✅ Use .$defaultFn() for dynamic defaults - Not .default() for functions ✅ Set migrations_dir in wrangler.jsonc - Points to ./migrations

❌ Never use SQL BEGIN TRANSACTION - D1 requires batch API ❌ Never use drizzle-kit push for production - Use generate + apply ❌ Never mix wrangler.toml and wrangler.jsonc - Use wrangler.jsonc only

---

Drizzle Kit Tools

Drizzle Studio (Visual Database Browser)

npx drizzle-kit studio
# Opens http://local.drizzle.studio

# For remote D1 database
npx drizzle-kit studio --port 3001

Features:

• Browse tables and data visually
• Edit records inline
• Run custom SQL queries
• View schema relationships

Migration Commands

# Introspect existing D1 database
npx drizzle-kit pull

# Validate migrations haven't collided
npx drizzle-kit check

---

Advanced Query Patterns

Dynamic Query Building

Build queries conditionally with .$dynamic():

import { eq, and, or, like, sql } from 'drizzle-orm';

// Base query
function getUsers(filters: { name?: string; email?: string; active?: boolean }) {
  let query = db.select().from(users).$dynamic();

  if (filters.name) {
    query = query.where(like(users.name, `%${filters.name}%`));
  }
  if (filters.email) {
    query = query.where(eq(users.email, filters.email));
  }
  if (filters.active !== undefined) {
    query = query.where(eq(users.active, filters.active));
  }

  return query;
}

// Usage
const results = await getUsers({ name: 'John', active: true });

Upsert (Insert or Update on Conflict)

import { users } from './schema';

// Insert or ignore if exists
await db.insert(users)
  .values({ id: 1, email: 'test@example.com', name: 'Test' })
  .onConflictDoNothing();

// Insert or update specific fields on conflict
await db.insert(users)
  .values({ id: 1, email: 'test@example.com', name: 'Test' })
  .onConflictDoUpdate({
    target: users.email,  // Conflict on unique email
    set: {
      name: sql`excluded.name`,  // Use value from INSERT
      updatedAt: new Date(),
    },
  });

⚠️ D1 Upsert Caveat: Target must be a unique column or primary key.

Debugging with Logging

import { drizzle } from 'drizzle-orm/d1';

// Enable query logging
const db = drizzle(env.DB, { logger: true });

// Custom logger
const db = drizzle(env.DB, {
  logger: {
    logQuery(query, params) {
      console.log('SQL:', query);
      console.log('Params:', params);
    },
  },
});

// Get SQL without executing (for debugging)
const query = db.select().from(users).where(eq(users.

...