Drizzle ORM は、テーブルの形を TypeScript のコードで書き、SQL に近い書き方で型付きのクエリを書く ORM です。 マイグレーション(テーブル定義の変更を SQL ファイルにして順に当てる仕組み)は、別パッケージの drizzle-kit が受け持ちます。
npm i drizzle-orm pg dotenv
npm i -D drizzle-kit tsx @types/pg
| コマンド | 何をするか | 履歴(__drizzle_migrations) |
|---|---|---|
drizzle-kit generate |
スキーマとの差分から SQL ファイルを作る(DB には触らない) | ― |
drizzle-kit migrate |
まだ当てていない SQL ファイルを DB に当てる | 記録する |
drizzle-kit push |
スキーマを直接 DB に反映する(SQL ファイルを作らない) | 記録しない |
drizzle-kit check |
マイグレーションのファイルどうしの矛盾を調べる | ― |
drizzle-kit drop |
作ったマイグレーションのファイルを消す | ― |
drizzle-kit introspect(ドキュメントでは pull) |
既存の DB からスキーマのコードを作る | ― |
drizzle-kit export |
スキーマ全体を SQL で出力する | ― |
drizzle-kit studio |
ブラウザでデータを見る・編集する | ― |
確認環境:drizzle-orm 0.45.4・drizzle-kit 0.31.11・pg(node-postgres)8.23.1・tsx 4.23.15・Node.js 22.22.2・PostgreSQL 16.15(Ubuntu 24.04)。本文の SQL ファイル・ターミナル出力・クエリの結果は、この環境で実行して得たものです。設定の既定値は Drizzle 公式ドキュメントで確かめました(確認日 2026年10月13日)。
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「Drizzle ORMの使い方|スキーマ定義とマイグレーション」
版について:latest は 0.45、1.0 はリリース候補
2026年10月13日時点の npm の latest は drizzle-orm 0.45.4(10月8日公開)と drizzle-kit 0.31.11 でした。 rc タグには 1.0.0-rc.4 があり、公式ドキュメントの Get Started では npm i drizzle-orm@rc と rc を入れる手順になっていました。この記事は latest(0.45.4)で書いています。
準備:設定ファイルと接続
my-app/
├── .env DATABASE_URL=postgres://user:pass@localhost:5432/app
├── drizzle.config.ts drizzle-kit の設定
├── drizzle/ generate で作られる SQL(out)
└── src/db/
├── schema.ts テーブル定義
└── index.ts 接続(db)
// drizzle.config.ts
import 'dotenv/config'
import { defineConfig } from 'drizzle-kit'
export default defineConfig({
out: './drizzle',
schema: './src/db/schema.ts',
dialect: 'postgresql',
dbCredentials: { url: process.env.DATABASE_URL! },
})
// src/db/index.ts
import 'dotenv/config'
import { drizzle } from 'drizzle-orm/node-postgres'
import * as schema from './schema.js'
export const db = drizzle(process.env.DATABASE_URL!, {
schema, // db.query.〇〇 を使うために渡す
logger: process.env.SQL_LOG === '1', // 実行した SQL を表示
})
| 設定 | 既定値(公式ドキュメント) | 意味 |
|---|---|---|
dialect |
なし(必須) | postgresql・mysql・sqlite・turso など |
schema |
なし | スキーマのファイル(glob も可) |
out |
drizzle |
SQL ファイルの出力先 |
migrations.table |
__drizzle_migrations |
適用履歴のテーブル名 |
migrations.schema |
drizzle |
履歴テーブルを置く PostgreSQL のスキーマ |
breakpoints |
true |
SQL 文の間に --> statement-breakpoint を入れる |
verbose |
false |
push で実行する SQL を表示 |
スキーマを定義する
// src/db/schema.ts
import { relations } from 'drizzle-orm'
import { pgTable, integer, varchar, text, boolean, timestamp, index } from 'drizzle-orm/pg-core'
export const users = pgTable('users', {
id: integer().primaryKey().generatedAlwaysAsIdentity(),
name: varchar({ length: 100 }).notNull(),
email: varchar({ length: 255 }).notNull().unique(),
createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
})
export const posts = pgTable('posts', {
id: integer().primaryKey().generatedAlwaysAsIdentity(),
authorId: integer('author_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
title: varchar({ length: 200 }).notNull(),
body: text(),
published: boolean().notNull().default(false),
}, (t) => [index('posts_author_id_idx').on(t.authorId)])
// db.query で with を使うためのリレーション定義(DB の制約は作らない)
export const usersRelations = relations(users, ({ many }) => ({ posts: many(posts) }))
export const postsRelations = relations(posts, ({ one }) => ({
author: one(users, { fields: [posts.authorId], references: [users.id] }),
}))
export type User = typeof users.$inferSelect // select で返る型
export type NewUser = typeof users.$inferInsert // insert で渡す型
列名を省くと、プロパティ名がそのまま列名になります。 createdAt を created_at にしたいときは、timestamp('created_at', ...) のように1つ目の引数で書きます。
| よく使う列の型(PostgreSQL) | 作られる SQL の型 |
|---|---|
integer() / bigint({ mode: 'number' }) |
integer / bigint |
integer().generatedAlwaysAsIdentity() |
GENERATED ALWAYS AS IDENTITY |
serial() |
serial |
varchar({ length: 100 }) / text() |
varchar(100) / text |
boolean() |
boolean |
timestamp({ withTimezone: true }) |
timestamp with time zone |
numeric({ precision: 10, scale: 2 }) |
numeric(10, 2) |
jsonb() / uuid().defaultRandom() |
jsonb / uuid DEFAULT gen_random_uuid() |
| 制約・既定値 | 書き方 |
|---|---|
| NOT NULL | .notNull() |
| 主キー | .primaryKey() |
| 一意 | .unique() |
| 既定値 | .default(false)・.defaultNow()・.default(sql`now()`) |
| 外部キー | .references(() => users.id, { onDelete: 'cascade' }) |
| インデックス | 第3引数で index('名前').on(t.列) |
serial と IDENTITY の違いは、関連記事「PostgreSQL連番|serialとIDENTITYの違いとsetval修正」で扱っています。
generate → migrate を動かす
$ npx drizzle-kit generate
Reading config file '/.../drizzle.config.ts'
2 tables
posts 5 columns 1 indexes 1 fks
users 4 columns 0 indexes 0 fks
[✓] Your SQL migration file ➜ drizzle/0000_married_black_panther.sql 🚀
ファイル名の後ろは自動で付く名前です。--name init で名前を付けられます。作られた SQL です。
CREATE TABLE "posts" (
"id" integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY (sequence name "posts_id_seq" INCREMENT BY 1 MINVALUE 1 MAXVALUE 2147483647 START WITH 1 CACHE 1),
"author_id" integer NOT NULL,
"title" varchar(200) NOT NULL,
"body" text,
"published" boolean DEFAULT false NOT NULL
);
--> statement-breakpoint
CREATE TABLE "users" (
"id" integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY (sequence name "users_id_seq" INCREMENT BY 1 MINVALUE 1 MAXVALUE 2147483647 START WITH 1 CACHE 1),
"name" varchar(100) NOT NULL,
"email" varchar(255) NOT NULL,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
CONSTRAINT "users_email_unique" UNIQUE("email")
);
--> statement-breakpoint
ALTER TABLE "posts" ADD CONSTRAINT "posts_author_id_users_id_fk" FOREIGN KEY ("author_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
CREATE INDEX "posts_author_id_idx" ON "posts" USING btree ("author_id");
drizzle/meta/ には、そのときのスキーマの写し(0000_snapshot.json)と、ファイルの一覧(_journal.json)ができます。次の generate は、この写しとの差分で SQL を作ります。 DB の今の状態とは比べていません。
$ npx drizzle-kit migrate
Using 'pg' driver for database querying
[✓] migrations applied successfully!
当てた記録は drizzle スキーマの __drizzle_migrations に入りました。もう一度 migrate しても、同じファイルは当てられません。
drizzle_demo=# select * from drizzle.__drizzle_migrations;
id | hash | created_at
----+------------------------------------------------------------------+---------------
1 | 6318a8b6a189cfd7064f1998d7bb583183bf121b29b8d8a5c7ce1d649fcaab0a | 1791874760514
push は SQL ファイルを作らず、履歴も残しませんでした。 空の DB に drizzle-kit push --verbose --force を実行すると、CREATE TABLE を表示して [✓] Changes applied となり、drizzle.__drizzle_migrations は作られていませんでした。push は開発中の試行錯誤、generate + migrate は本番に当てる履歴を残したいとき、と分けると混乱しません。
つまずき①:NOT NULL の列を足すと migrate が止まる
行があるテーブルに、既定値の無い NOT NULL の列を足しました。
role: varchar({ length: 20 }).notNull(),
-- generate で作られた SQL
ALTER TABLE "users" ADD COLUMN "bio" text;--> statement-breakpoint
ALTER TABLE "users" ADD COLUMN "role" varchar(20) NOT NULL;
drizzle-kit migrate は終了コード 1 で止まりましたが、画面には applying migrations... までしか出ず、エラーの文は出ませんでした。 PostgreSQL のログには原因が出ていました。
ERROR: column "role" of relation "users" contains null values
同じファイルを、drizzle-orm の migrate() 関数でプログラムから当てると、原因が例外で取れました。
// src/migrate.ts
import 'dotenv/config'
import { drizzle } from 'drizzle-orm/node-postgres'
import { migrate } from 'drizzle-orm/node-postgres/migrator'
const db = drizzle(process.env.DATABASE_URL!)
try {
await migrate(db, { migrationsFolder: './drizzle' })
console.log('migrated')
} catch (e: any) {
console.error('migrate failed:', e.cause?.code, e.cause?.message)
process.exitCode = 1
} finally {
await db.$client.end()
}
migrate failed: 23502 column "role" of relation "users" contains null values
同じファイルの bio の追加も当たっていませんでした。 ファイル全体が1つのトランザクションで巻き戻ったためです。直し方は、まだ当てていないマイグレーションを drizzle-kit drop で消し、スキーマに既定値を付けて作り直すことです。
role: varchar({ length: 20 }).notNull().default('member'),
ALTER TABLE "users" ADD COLUMN "role" varchar(20) DEFAULT 'member' NOT NULL;
これで migrate が通り、既存の行の role は member になりました。drizzle-kit check は Everything's fine と出ました。
つまずき②:列名の変更は「作るか、変えるか」を聞かれる
bio を profile に変えて generate すると、対話の質問が出ました。
Is profile column in users table created or renamed from another column?
❯ + profile create column
~ bio › profile rename column
そのまま Enter を押すと「create column」が選ばれ、次の SQL になりました。 列を消して作り直すので、bio のデータは消えます。
ALTER TABLE "users" ADD COLUMN "profile" text;--> statement-breakpoint
ALTER TABLE "users" DROP COLUMN "bio";
下矢印で「rename column」を選ぶと、名前を変える SQL になりました。
ALTER TABLE "users" RENAME COLUMN "bio" TO "profile";
CI のような端末の無い環境で実行すると、質問を出せずにエラーになりました。
Error: Interactive prompts require a TTY terminal (process.stdin.isTTY or process.stdout.isTTY is false). This can happen when running in CI, piped input, or non-interactive shells.
名前の変更・削除を含む generate は、手元の端末で実行して SQL を確かめてからコミットします。generate の SQL ファイルは手で直すこともできます。
select・insert・update・delete
import { eq, and, gt, like, desc, count, sql } from 'drizzle-orm'
import { db } from './db/index.js'
import { users, posts } from './db/schema.js'
// insert ... returning
const [alice] = await db.insert(users).values({ name: 'Alice', email: 'alice@example.com' }).returning()
// { id: 1, name: 'Alice', email: 'alice@example.com', createdAt: 2026-10-13T06:59:45.127Z }
const many = await db.insert(users).values([
{ name: 'Bob', email: 'bob@example.com' },
{ name: 'Carol', email: 'carol@example.com' },
]).returning({ id: users.id, name: users.name })
// [ { id: 2, name: 'Bob' }, { id: 3, name: 'Carol' } ]
// select(列を選ぶ・条件)
await db.select({ id: users.id, name: users.name }).from(users)
.where(and(gt(users.id, 1), like(users.email, '%@example.com')))
// [ { id: 2, name: 'Bob' }, { id: 3, name: 'Carol' } ]
// update
await db.update(posts).set({ published: true }).where(eq(posts.title, '下書き'))
.returning({ id: posts.id, published: posts.published })
// [ { id: 2, published: true } ]
// upsert(email が重複したら name を更新)
await db.insert(users).values({ name: 'Alice2', email: 'alice@example.com' })
.onConflictDoUpdate({ target: users.email, set: { name: 'Alice (updated)' } })
// select すると [ { name: 'Alice (updated)' } ]
// delete(posts は ON DELETE cascade で一緒に消えた)
await db.delete(users).where(eq(users.name, 'Eve')).returning({ id: users.id })
.toSQL() で、実行する SQL とパラメーターを確かめられます。
db.select().from(users).where(eq(users.id, 1)).toSQL()
// { sql: 'select "id", "name", "email", "created_at" from "users" where "users"."id" = $1', params: [ 1 ] }
演算子(drizzle-orm から import) |
SQL |
|---|---|
eq(a, b) / ne(a, b) |
a = b / a <> b |
gt / gte / lt / lte |
> / >= / < / <= |
like(a, '%x%') / ilike(...) |
LIKE / ILIKE |
inArray(a, [1, 2]) |
a IN (1, 2) |
isNull(a) / isNotNull(a) |
IS NULL / IS NOT NULL |
and(...) / or(...) / not(...) |
AND / OR / NOT |
sql`...` |
そのまま SQL を書く(値はパラメーターになる) |
一意制約の違反は DrizzleQueryError になり、PostgreSQL のエラーは cause に入っていました。
DrizzleQueryError | Failed query: insert into "users" ("id", "name", "email", "created_at") values (default, $1, $2, default)
cause: 23505 duplicate key value violates unique constraint "users_email_unique"
エラーコード(23505 など)を見るときは e.cause.code です。 e.code ではありませんでした。duplicate key の原因は、関連記事「PostgreSQL duplicate keyの直し方|シーケンスのずれ」で扱っています。
join と、リレーションのクエリ(db.query)
// inner join
await db.select({ author: users.name, title: posts.title })
.from(posts).innerJoin(users, eq(posts.authorId, users.id)).orderBy(posts.id)
// [ { author: 'Alice', title: 'Drizzle入門' },
// { author: 'Alice', title: '下書き' },
// { author: 'Bob', title: 'Bobの記事' } ]
// left join + 件数
await db.select({ name: users.name, posts: count(posts.id) })
.from(users).leftJoin(posts, eq(posts.authorId, users.id))
.groupBy(users.id).orderBy(users.id)
// [ { name: 'Alice', posts: 2 }, { name: 'Bob', posts: 1 }, { name: 'Carol', posts: 0 } ]
relations() を定義し、drizzle() に schema を渡しておくと、入れ子の形で取れます。
await db.query.users.findMany({
columns: { name: true },
with: { posts: { columns: { title: true } } },
orderBy: [users.id],
})
// [{"name":"Alice","posts":[{"title":"Drizzle入門"},{"title":"下書き"}]},
// {"name":"Bob","posts":[{"title":"Bobの記事"}]},{"name":"Carol","posts":[]}]
logger: true で SQL を表示すると、findMany + with は1本の SQL でした。 left join lateral (select coalesce(json_agg(...), '[]'::json) ...) の形で、投稿を JSON にまとめて取っています。ユーザーごとに別の SQL が飛ぶ形(N+1)にはなっていませんでした。
| 書き方 | 向いている場面 |
|---|---|
db.select().from().innerJoin() |
列を選んで平らな行で欲しい、集計したい |
db.query.〇〇.findMany({ with }) |
親子を入れ子のオブジェクトで欲しい |
db.execute(sql`...`) |
複雑な SQL をそのまま書く(結果は rows) |
トランザクション
const id = await db.transaction(async (tx) => {
const [u] = await tx.insert(users).values({ name: 'Eve', email: 'eve@example.com' }).returning()
await tx.insert(posts).values({ authorId: u.id, title: 'Eveの初投稿' })
return u.id // 戻り値がそのまま返る
})
| 中で起きたこと | 結果 |
|---|---|
| 最後まで終わった | コミット。戻り値 8 が返った |
| 2つ目の insert が一意制約違反 | 例外(cause.code は 23505)。1つ目の insert も残っていなかった |
tx.rollback() を呼んだ |
TransactionRollbackError: Rollback の例外。insert は残っていなかった |
tx.rollback() は例外を投げて巻き戻します。 呼んだあとは、db.transaction() の外で try/catch が要ります。
戻り値の ID が 8 だったのは、失敗した insert でも IDENTITY の番号が使われるためです。PostgreSQL の仕様で、番号は巻き戻りません。
Prisma との違い
| 比べること | Drizzle ORM 0.45 | Prisma ORM 7 |
|---|---|---|
| スキーマの書き方 | TypeScript(pgTable) |
専用の言語(schema.prisma) |
| クライアントの生成 | 無い(スキーマのコードをそのまま import) | prisma generate が要る |
| クエリの書き方 | SQL に近い select().from().where() と db.query |
prisma.user.findMany({ where }) |
| マイグレーション | drizzle-kit generate → migrate |
prisma migrate dev / migrate deploy |
| 履歴テーブル | drizzle.__drizzle_migrations |
_prisma_migrations |
| DB への接続 | node-postgres などのドライバーを直接渡す | ドライバーアダプターが必須(v7) |
Prisma 7 の列は、関連記事「Prismaの使い方|schemaの書き方・migrate・よくあるエラー」で確かめた内容です。SQL を知っていて、SQL に近い形で書きたいなら Drizzle、モデル中心の API と周辺ツールをまとめて使いたいなら Prisma、という分け方が目安になります。
よくある質問
Q. SQLite や MySQL でも同じ書き方ですか。
A. テーブル定義の関数が sqliteTable(drizzle-orm/sqlite-core)・mysqlTable(drizzle-orm/mysql-core)に変わり、drizzle.config.ts の dialect を sqlite・mysql にします。クエリの書き方(select().from().where())は同じです。SQLite 自体の使い方は、関連記事「SQLiteの使い方|コマンド早見表とPython連携を実行例で解説」で扱っています。
Q. 本番の DB にはどう当てますか。
A. generate した SQL ファイルをリポジトリに入れ、デプロイのときに drizzle-kit migrate か、上の migrate() 関数で当てます。drizzle-kit の migrate は失敗の理由が画面に出なかったので、migrate() 関数で cause を出す形にすると原因を追えます。
Q. down(戻す)マイグレーションはありますか。 A. generate は「進める」SQL だけを作りました。戻すときは、スキーマを戻して新しいマイグレーションを generate します。
Q. マイグレーションのファイルを間違えて作りました。
A. まだ当てていなければ、drizzle-kit drop で選んで消せます。drizzle/ のファイルと meta/ の写し・一覧がまとめて消えました。手でファイルだけ消すと、_journal.json とずれます。
まとめ
- Drizzle は TypeScript でスキーマを書き、SQL に近い形でクエリを書く ORM。マイグレーションは drizzle-kit
- generate は SQL ファイルを作るだけ、migrate が当てる。push は履歴を残さない
- 既定値の無い NOT NULL 列の追加は migrate が止まる。drizzle-kit の画面に理由が出ず、
migrate()関数のcauseに出た - 列名の変更は rename を選ぶ。Enter のままだと DROP + ADD でデータが消える
- エラーコードは
e.cause.code。tx.rollback()は例外で巻き戻す
参考・出典
確認日はいずれも 2026年10月13日です。
- Drizzle ORM ドキュメント「Get Started with Drizzle and PostgreSQL」:https://orm.drizzle.team/docs/get-started/postgresql-new
- Drizzle ORM ドキュメント「Drizzle Kit overview」:https://orm.drizzle.team/docs/kit-overview
- Drizzle ORM ドキュメント「drizzle.config.ts」:https://orm.drizzle.team/docs/drizzle-config-file
- Drizzle ORM ドキュメント「Migrations」:https://orm.drizzle.team/docs/migrations
- Drizzle ORM ドキュメント「Transactions」:https://orm.drizzle.team/docs/transactions
- drizzle-orm(npm):https://www.npmjs.com/package/drizzle-orm
- drizzle-kit(npm):https://www.npmjs.com/package/drizzle-kit
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「Drizzle ORMの使い方|スキーマ定義とマイグレーション」
株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。
WE ARE HIRING
RJCで一緒に開発しながら、
成長を楽しみませんか?
RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!
- 127日年間休日
- 12時間平均残業時間
- 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!
ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。