快速开始
从零安装 Drizzle ORM,连接 PostgreSQL,定义 schema,生成迁移并完成第一次查询。
本指南以 PostgreSQL + Node.js/Bun 为主,十分钟走完从安装到查询的完整流程。MySQL 与 SQLite 的差异放在文末。
准备环境
- Node.js 18+、Bun 1.x 或 Deno 任选其一
- 一个可用的 PostgreSQL 数据库
DATABASE_URL连接串,格式为postgres://user:password@host:5432/database
本地没有数据库时,可以用 Docker 快速启动一个:
docker run --name drizzle-pg \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=drizzle \
-p 5432:5432 \
-d postgres:16 对应的连接串为 postgres://postgres:postgres@localhost:5432/drizzle。
安装依赖
# 运行时依赖
bun add drizzle-orm pg dotenv
# 开发依赖:迁移工具与类型
bun add -d drizzle-kit @types/pg 使用 Bun 时 .env 会被自动加载;使用 Node.js 的脚本时,请在入口或 drizzle.config.ts 中引入 dotenv/config。
DATABASE_URL=postgres://postgres:postgres@localhost:5432/drizzle 连接数据库
import 'dotenv/config';
import { drizzle } from 'drizzle-orm/node-postgres';
import * as schema from './schema';
export const db = drizzle(process.env.DATABASE_URL!, { schema }); node-postgres 驱动会自动创建连接池。需要自定义连接池、SSL 或超时参数时,可以显式传入 pg.Pool,详见连接数据库。
定义 Schema
import { integer, pgTable, text, timestamp, varchar } from 'drizzle-orm/pg-core';
export const users = pgTable('users', {
id: integer('id').primaryKey().generatedAlwaysAsIdentity(),
name: varchar('name', { length: 255 }).notNull(),
email: varchar('email', { length: 255 }).notNull().unique(),
bio: text('bio'),
createdAt: timestamp('created_at').defaultNow().notNull(),
});
export type User = typeof users.$inferSelect;
export type NewUser = typeof users.$inferInsert; notNull()的列在插入时必填,bio这类可空列在类型中是string | null。$inferSelect/$inferInsert从 schema 推导查询结果与插入对象的类型。
配置 drizzle-kit
import 'dotenv/config';
import { defineConfig } from 'drizzle-kit';
export default defineConfig({
schema: './src/db/schema.ts',
out: './drizzle',
dialect: 'postgresql',
dbCredentials: {
url: process.env.DATABASE_URL!,
},
}); 生成并执行迁移
# 对比 schema 与迁移历史,生成 SQL 文件
bunx drizzle-kit generate
# 将待执行的迁移应用到数据库
bunx drizzle-kit migrate 生成的文件位于 drizzle/ 目录,打开它可以看到真实执行的 SQL:
CREATE TABLE "users" (
"id" integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
"name" varchar(255) NOT NULL,
"email" varchar(255) NOT NULL,
"bio" text,
"created_at" timestamp DEFAULT now() NOT NULL,
CONSTRAINT "users_email_unique" UNIQUE("email")
); 不要在生成后随意修改已应用的迁移
迁移文件一经应用,就应该视为不可变的历史。新增变更请生成新的迁移,而不是回头修改旧文件。
插入、查询、更新与删除
import { eq } from 'drizzle-orm';
import { db } from './db';
import { users } from './db/schema';
// 插入
await db.insert(users).values({
name: 'Ada Lovelace',
email: 'ada@example.com',
});
// 查询
const allUsers = await db.select().from(users);
// 更新并返回结果
const [updated] = await db
.update(users)
.set({ bio: ' mathematician & writer ' })
.where(eq(users.email, 'ada@example.com'))
.returning();
// 删除
await db.delete(users).where(eq(users.id, 1)); 所有查询都是 Promise,并且返回结果的类型完全来自 schema。把鼠标悬停在 allUsers 上,可以看到 { id: number; name: string; email: string; bio: string | null; createdAt: Date }[]。
运行脚本
bun run src/index.ts 如果需要持续同步 schema(仅在开发阶段),可以使用:
bunx drizzle-kit push push 直接把 schema 变更应用到数据库,不生成迁移文件,适合原型期;生产环境请使用 generate + migrate。
其他数据库
bun add drizzle-orm pg
bun add -d drizzle-kit @types/pg import { drizzle } from 'drizzle-orm/node-postgres';
export const db = drizzle(process.env.DATABASE_URL!); import { defineConfig } from 'drizzle-kit';
export default defineConfig({
dialect: 'postgresql',
schema: './src/db/schema.ts',
out: './drizzle',
dbCredentials: { url: process.env.DATABASE_URL! },
}); 表定义也要换成对应的核心包:drizzle-orm/pg-core、drizzle-orm/mysql-core 或 drizzle-orm/sqlite-core。
下一步
- Schema 与类型:索引、枚举、外键、类型推断
- 查询构建器:从
select到 CTE - 迁移:把迁移纳入 CI 与生产流程