drizzle-orm

Drizzle ORM

最小化・gzip 圧縮後で約7.4kb、依存関係ゼロ、サーバーレス対応です。

クイックスタート

インストール

# PostgreSQL
npm i drizzle-orm pg
npm i -D drizzle-kit @types/pg

# MySQL
npm i drizzle-orm mysql2
npm i -D drizzle-kit

# SQLite
npm i drizzle-orm better-sqlite3
npm i -D drizzle-kit @types/better-sqlite3

# Turso / LibSQL
npm i drizzle-orm @libsql/client
npm i -D drizzle-kit

# Bun SQL (PostgreSQL — zero extra deps)
bun add drizzle-orm
bun add -D drizzle-kit

# Bun SQLite (zero extra deps, sync APIs)
bun add drizzle-orm
bun add -D drizzle-kit

設定

// drizzle.config.ts
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql", // "postgresql" | "mysql" | "sqlite" | "turso" | "singlestore"
  schema: "./src/db/schema.ts",
  out: "./drizzle",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

スキーマ

// src/db/schema.ts
import { pgTable, serial, text, integer, timestamp } from "drizzle-orm/pg-core";

export const users = pgTable("users", {
  id: serial().primaryKey(),
  name: text().notNull(),
  email: text().unique(),
  createdAt: timestamp().defaultNow(),
});

export const posts = pgTable("posts", {
  id: serial().primaryKey(),
  title: text().notNull(),
  content: text(),
  authorId: integer("author_id").references(() => users.id),
});

接続とクエリ

import { drizzle } from "drizzle-orm/node-postgres";
import { eq } from "drizzle-orm";
import * as schema from "./schema";

const db = drizzle(process.env.DATABASE_URL!, { schema });

// select
const allUsers = await db.select().from(schema.users);

// insert
const [user] = await db.insert(schema.users)
  .values({ name: "Dan", email: "[email protected]" })
  .returning();

// update
await db.update(schema.users)
  .set({ name: "Daniel" })
  .where(eq(schema.users.id, 1));

// delete
await db.delete(schema.users).where(eq(schema.users.id, 1));

各プロバイダー（Neon、Turso、Supabase、D1 など）のセットアップについては、references/connections.md を参照してください。

スキーマ宣言

方言固有のモジュールからテーブル／カラムビルダーをインポートします。

// PG:     import { pgTable, serial, text, ... } from "drizzle-orm/pg-core";
// MySQL:  import { mysqlTable, int, varchar, ... } from "drizzle-orm/mysql-core";
// SQLite: import { sqliteTable, integer, text, ... } from "drizzle-orm/sqlite-core";

一般的なカラム型（PG）

型	用途	備考
serial()	自動インクリメントのPK	新規プロジェクトでは integer().generatedAlwaysAsIdentity() を使用してください
integer()	4バイト整数
bigint({ mode: "number" })	8バイト整数	2^53を超える場合は "bigint" モードを使用します
text()	長さ制限なしのテキスト	TS のユニオン型には { enum: [...] } を使用します
varchar({ length: n })	可変長
boolean()	true／false
timestamp()	日時	{ withTimezone: true }、mode: "date"
date()	暦日	JavaScript の Date には mode: "date" を使用します
json() / jsonb()	JSON データ	型付けには .$type<T>() を使用します
uuid()	UUID	gen_random_uuid() には .defaultRandom() を使用します
numeric({ precision, scale })	正確な小数	デフォルトでは文字列を返します

制約修飾子

column.notNull()
column.default(value)
column.default(sql`now()`)
column.$defaultFn(() => createId())   // runtime default
column.$onUpdate(() => new Date())    // runtime on update
column.primaryKey()
column.unique()
column.references(() => other.id, { onDelete: "cascade" })
column.$type<CustomType>()            // branded types

大文字・小文字の自動マッピング

// drizzle.config.ts
export default defineConfig({
  casing: "snake_case", // camelCase TS keys -> snake_case DB columns
});

カラム型の一覧については、PG | MySQL | SQLite | MSSQL/CockroachDB/SingleStore を参照してください。

CRUD 操作

すべての演算子は "drizzle-orm" からインポートします。

import { eq, ne, gt, gte, lt, lte, and, or, not, like, ilike, inArray, between, isNull, sql } from "drizzle-orm";

Select

// basic
await db.select().from(users);

// partial + where
await db.select({ id: users.id, name: users.name })
  .from(users)
  .where(and(eq(users.role, "admin"), gt(users.age, 18)))
  .orderBy(asc(users.name))
  .limit(10).offset(20);

// aggregation
await db.select({ role: users.role, count: sql<number>`count(*)` })
  .from(users).groupBy(users.role).having(gt(sql`count(*)`, 5));

Insert

// single + returning
const [user] = await db.insert(users).values({ name: "Dan" }).returning();

// bulk
await db.insert(users).values([{ name: "A" }, { name: "B" }]);

// upsert (PG/SQLite)
await db.insert(users).values({ id: 1, name: "Dan" })
  .onConflictDoUpdate({ target: users.id, set: { name: "Dan" } });

// upsert (MySQL)
await db.insert(users).values({ id: 1, name: "Dan" })
  .onDuplicateKeyUpdate({ set: { name: "Dan" } });

Update / Delete

await db.update(users).set({ name: "Jane" }).where(eq(users.id, 1)).returning();
await db.delete(users).where(eq(users.id, 1)).returning();

クエリの詳細については、references/queries.md を参照してください。

JOIN

// inner join
await db.select().from(users)
  .innerJoin(posts, eq(users.id, posts.authorId));

// left join
await db.select().from(users)
  .leftJoin(orders, eq(users.id, orders.userId));

// self-join with alias
import { alias } from "drizzle-orm/pg-core";
const parent = alias(users, "parent");
await db.select().from(users).leftJoin(parent, eq(users.managerId, parent.id));

リレーション

V1（安定版）

import { relations } from "drizzle-orm";

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

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

リレーショナルクエリ

db.query を有効にするには、drizzle に schema を渡します。

const db = drizzle(url, { schema });

const result = await db.query.users.findMany({
  columns: { id: true, name: true },
  with: { posts: { with: { comments: true } } },
  where: (users, { eq }) => eq(users.id, 1),
  orderBy: (users, { desc }) => desc(users.createdAt),
  limit: 10,
});

const user = await db.query.users.findFirst({
  where: (users, { eq }) => eq(users.name, "Dan"),
  with: { posts: true },
});

V2（ベータ版）

import { defineRelations } from "drizzle-orm";

export const relations = defineRelations(schema, (r) => ({
  users: { posts: r.many.posts() },
  posts: { author: r.one.users({ from: r.posts.authorId, to: r.users.id }) },
}));

V2 では .through() が追加され、ジャンクションテーブルの定型コードなしで多対多を実現できます。

リレーションの詳細については、references/relations.md を参照してください。

Drizzle Kit

コマンド	説明
npx drizzle-kit generate	スキーマの差分から SQL マイグレーションファイルを作成します
npx drizzle-kit migrate	保留中のマイグレーションを適用します
npx drizzle-kit push	スキーマを直接同期します（プロトタイピング専用）
npx drizzle-kit pull	DB をイントロスペクトし、Drizzle スキーマを作成します
npx drizzle-kit check	マイグレーションの整合性を検証します
npx drizzle-kit studio	ビジュアルデータベースブラウザー

マイグレーションの詳細については、references/migrations.md を参照してください。

トランザクション

const result = await db.transaction(async (tx) => {
  const [user] = await tx.insert(users).values({ name: "Dan" }).returning();
  await tx.insert(accounts).values({ userId: user.id, balance: 0 });
  return user;
});

tx.rollback() でロールバックできます。ネストされたトランザクションはセーブポイントを作成します。

詳細については、references/transactions-and-batch.md を参照してください。

生 SQL

import { sql } from "drizzle-orm";

// typed expression
const lower = sql<string>`lower(${users.name})`;

// full raw query
await db.execute(sql`SELECT * FROM ${users} WHERE ${users.id} = ${id}`);

// placeholder for prepared statements
const prepared = db.select().from(users)
  .where(eq(users.id, sql.placeholder("id")))
  .prepare("get_user");
await prepared.execute({ id: 1 });

リファレンス一覧

トピック	ファイル
PostgreSQL のカラム型、列挙型、スキーマ、インデックス、ビュー、RLS	references/schema-postgresql.md
MySQL のカラム型、列挙型、インデックス、ビュー	references/schema-mysql.md
SQLite のカラム型、インデックス、ビュー	references/schema-sqlite.md
MSSQL、CockroachDB、SingleStore の型	references/column-types-minor-dialects.md
クエリー演算子の全一覧、高度な select、結合、CTE、集合演算、$count	references/queries.md
Relations v1 + v2、リレーショナルクエリー API	references/relations.md
Drizzle Kit の設定、コマンド、プログラムによるマイグレーション	references/migrations.md
トランザクション、セーブポイント、バッチ API	references/transactions-and-batch.md
drizzle-zod、drizzle-valibot、drizzle-typebox など	references/schema-validation.md
プロバイダーごとの接続設定（Neon、Turso、Supabase、D1、PGlite、Expo など）	references/connections.md
drizzle-seed によるデータベースのシーディング、バージョン管理	references/drizzle-seed.md
読み取りレプリカ、カスタム型、キャッシュ、ESLint、注意点、drizzle-graphql	references/advanced-patterns.md