跳到正文
Drizzle

快速开始

从零安装 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。

下一步