Drizzle Orm D1

Drizzle ORM for Cloudflare D1

Quick Start (10 Minutes)

1. Install Drizzle

bun add drizzle-orm
bun add -D drizzle-kit

2. Configure Drizzle Kit

drizzle.config.ts at the project root:

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  schema: "./src/server/db/schema",
  out: "./src/server/db/migrations",
  dialect: "sqlite",
});

No driver, no dbCredentials. Drizzle Kit only generates SQL files. Wrangler applies them.

3. Define Schema

src/server/db/schema/users.ts:

import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
import { relations } from "drizzle-orm";
import { posts } from "./posts";

export const users = sqliteTable("users", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  email: text("email").notNull().unique(),
  name: text("name").notNull(),
  createdAt: integer("created_at", { mode: "timestamp" })
    .$defaultFn(() => new Date())
    .notNull(),
});

export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}));

src/server/db/schema/posts.ts:

import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
import { relations } from "drizzle-orm";
import { users } from "./users";

export const posts = sqliteTable("posts", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  title: text("title").notNull(),
  content: text("content").notNull(),
  authorId: integer("author_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
});

export const postsRelations = relations(posts, ({ one }) => ({
  author: one(users, { fields: [posts.authorId], references: [users.id] }),
}));

src/server/db/schema/index.ts re-exports everything (tables AND *Relations):

export * from "./users";
export * from "./posts";

src/server/db/client.ts:

import { drizzle } from "drizzle-orm/d1";
import * as schema from "./schema";

export function createDb(d1: D1Database) {
  return drizzle(d1, { schema });
}

export type DB = ReturnType<typeof createDb>;

The barrel re-export is mandatory: client.ts does import * as schema from "./schema" and passes it to drizzle, and the relational query API can only see relations exported there.

4. Generate & Apply Migrations (local)

bun run db:generate        # drizzle-kit generate → SQL in ./src/server/db/migrations
bun run db:migrate:local   # apply to local D1

Remote is a deliberate, separate step: bun run db:migrate:remote, then bun run deploy — the scripts bake in the production env selection (see MIGRATIONS.md); never run raw wrangler --remote/deploy.

5. Query in Worker

import { createDb } from "./server/db/client";
import { users } from "./server/db/schema";
import { eq } from "drizzle-orm";

export default {
  async fetch(req: Request, env: { DB: D1Database }) {
    const db = createDb(env.DB);
    const list = await db.select().from(users).all();
    return Response.json(list);
  },
};

Helpers downstream take db: DB, never a raw D1Database.

Critical Rules

Always Do

Never Do

D1 Limits & Quirks

Quirks: FKs are always enforced — PRAGMA foreign_keys is blocked, only PRAGMA defer_foreign_keys works (see MIGRATIONS.md). Other PRAGMAs are restricted to table_list/table_info/table_xinfo. D1 is single-threaded (one query at a time, backed by a Durable Object). No BigInt — values beyond JS's 53-bit safe-integer range lose precision. FTS5 virtual tables work but block wrangler d1 export.

Top 5 Critical Errors

See: ERRORS.md for the full catalog with code samples.

Common Patterns Summary

Configuration Summary

bun scripts:

{
  "db:generate": "drizzle-kit generate",
  "db:migrate:local": "wrangler d1 migrations apply DB --local",
  "db:migrate:remote": "wrangler d1 migrations apply DB --remote --env production",
  "db:seed": "wrangler d1 execute DB --local --file=./src/server/db/seed.sql"
}

--env production on the remote script is load-bearing — the top-level wrangler.jsonc config is dev-only; production bindings live under env.production.

Migration Workflow

See: MIGRATIONS.md for wrangler.jsonc setup, renames, hand-edit cases, and common workflow failures.

TypeScript Type Inference

import type { InferSelectModel, InferInsertModel } from "drizzle-orm";
import { users } from "./server/db/schema";

export type User = InferSelectModel<typeof users>;
export type NewUser = InferInsertModel<typeof users>;

InferSelectModel is the row shape returned by select. InferInsertModel is the shape accepted by insert, with autoIncrement and defaulted columns marked optional.

When to Load References

Bundled Resources

References: SCHEMA-PATTERNS.md, MIGRATIONS.md, QUERIES.md, ERRORS.md

Dependencies

{
  "dependencies": {
    "drizzle-orm": "^0.45.2"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.10"
  }
}

Official Documentation

• Drizzle ORM: https://orm.drizzle.team/
• Drizzle with D1: https://orm.drizzle.team/docs/connect-cloudflare-d1
• Drizzle Kit: https://orm.drizzle.team/docs/kit-overview
• Cloudflare D1: https://developers.cloudflare.com/d1/
• wrangler d1: https://developers.cloudflare.com/workers/wrangler/commands/#d1
• GitHub: https://github.com/drizzle-team/drizzle-orm

Token Savings: progressive disclosure via four sibling references Error Prevention: top 5 inline, full catalog in ERRORS.md