name: Bun Drizzle 集成 description: 用于将 Drizzle ORM 与 Bun 的 SQLite 驱动程序集成，以实现类型安全的模式定义和迁移。 version: 1.0.0

Bun Drizzle 集成

Drizzle ORM 通过 Bun 的 SQLite 驱动程序提供类型安全的数据库访问。

快速开始

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

模式定义

// src/db/schema.ts
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";

export const users = sqliteTable("users", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  name: text("name").notNull(),
  email: text("email").notNull().unique(),
  createdAt: integer("created_at", { mode: "timestamp" })
    .notNull()
    .default(sql`(unixepoch())`),
});

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

数据库设置

// src/db/index.ts
import { drizzle } from "drizzle-orm/bun-sqlite";
import { Database } from "bun:sqlite";
import * as schema from "./schema";

const sqlite = new Database("app.db");
export const db = drizzle(sqlite, { schema });

配置

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

export default {
  schema: "./src/db/schema.ts",
  out: "./drizzle",
  dialect: "sqlite",
  dbCredentials: {
    url: "./app.db",
  },
} satisfies Config;

迁移

# 生成迁移
bun drizzle-kit generate

# 应用迁移
bun drizzle-kit migrate

# 直接推送模式（仅开发环境）
bun drizzle-kit push

# 打开 Drizzle Studio
bun drizzle-kit studio

CRUD 操作

插入

import { db } from "./db";
import { users, posts } from "./db/schema";

// 单次插入
const user = await db.insert(users).values({
  name: "Alice",
  email: "alice@example.com",
}).returning();

// 多次插入
await db.insert(users).values([
  { name: "Bob", email: "bob@example.com" },
  { name: "Charlie", email: "charlie@example.com" },
]);

// 插入或忽略
await db.insert(users)
  .values({ name: "Alice", email: "alice@example.com" })
  .onConflictDoNothing();

// 更新插入
await db.insert(users)
  .values({ name: "Alice", email: "alice@example.com" })
  .onConflictDoUpdate({
    target: users.email,
    set: { name: "Alice Updated" },
  });

查询

import { eq, gt, like, and, or, desc, asc } from "drizzle-orm";

// 所有行
const allUsers = await db.select().from(users);

// 带条件
const activeUsers = await db
  .select()
  .from(users)
  .where(eq(users.status, "active"));

// 多重条件
const filtered = await db
  .select()
  .from(users)
  .where(and(
    gt(users.age, 18),
    like(users.name, "%Alice%")
  ));

// 特定列
const names = await db
  .select({ name: users.name, email: users.email })
  .from(users);

// 排序和限制
const topUsers = await db
  .select()
  .from(users)
  .orderBy(desc(users.createdAt))
  .limit(10);

// 首个结果
const first = await db.query.users.findFirst({
  where: eq(users.id, 1),
});

更新

// 带条件更新
await db
  .update(users)
  .set({ name: "Alice Updated" })
  .where(eq(users.id, 1));

// 更新多字段
await db
  .update(users)
  .set({
    name: "New Name",
    updatedAt: new Date(),
  })
  .where(eq(users.email, "alice@example.com"));

删除

// 带条件删除
await db.delete(users).where(eq(users.id, 1));

// 删除多个
await db.delete(users).where(gt(users.createdAt, cutoffDate));

关系

// schema.ts
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],
  }),
}));

// 带关系查询
const usersWithPosts = await db.query.users.findMany({
  with: {
    posts: true,
  },
});

// 嵌套关系
const detailed = await db.query.users.findFirst({
  where: eq(users.id, 1),
  with: {
    posts: {
      with: {
        comments: true,
      },
    },
  },
});

事务

// 事务
await db.transaction(async (tx) => {
  const [user] = await tx.insert(users)
    .values({ name: "Alice", email: "alice@example.com" })
    .returning();

  await tx.insert(posts).values({
    title: "First Post",
    authorId: user.id,
  });
});

// 错误时回滚
await db.transaction(async (tx) => {
  await tx.insert(users).values({ name: "Bob" });

  if (someCondition) {
    tx.rollback(); // 抛出以回滚
  }

  await tx.insert(posts).values({ ... });
});

预处理语句

// 创建预处理语句
const getUserById = db
  .select()
  .from(users)
  .where(eq(users.id, sql.placeholder("id")))
  .prepare();

// 带参数执行
const user = await getUserById.execute({ id: 1 });

// 重用以提高性能
for (const id of userIds) {
  const user = await getUserById.execute({ id });
  processUser(user);
}

原生 SQL

import { sql } from "drizzle-orm";

// 原生查询
const result = await db.run(sql`
  UPDATE users SET last_login = ${new Date()} WHERE id = ${userId}
`);

// 在查询中
const users = await db.select({
  name: users.name,
  upperName: sql<string>`UPPER(${users.name})`,
}).from(users);

// 原生表达式在条件中
await db.select().from(users).where(
  sql`${users.age} > 18 AND ${users.status} = 'active'`
);

列类型参考

import {
  sqliteTable,
  text,
  integer,
  real,
  blob,
  numeric,
} from "drizzle-orm/sqlite-core";

const example = sqliteTable("example", {
  // 整数
  id: integer("id").primaryKey(),
  age: integer("age"),

  // 文本
  name: text("name"),
  status: text("status", { enum: ["active", "inactive"] }),

  // 实数（浮点数）
  price: real("price"),

  // 二进制大对象
  data: blob("data", { mode: "buffer" }),

  // 布尔值（存储为整数）
  active: integer("active", { mode: "boolean" }),

  // 时间戳（存储为整数）
  createdAt: integer("created_at", { mode: "timestamp" }),
  updatedMs: integer("updated_ms", { mode: "timestamp_ms" }),

  // JSON（存储为文本）
  metadata: text("metadata", { mode: "json" }),
});

常见错误

错误	原因	修复
`SQLITE_CONSTRAINT`	外键/唯一约束违规	检查约束条件
`no such column`	模式不匹配	运行迁移
`Cannot find module`	缺少驱动程序	使用 `drizzle-orm/bun-sqlite`
类型不匹配	错误的列类型	检查模式定义

何时加载参考资料

加载 references/migrations.md 当：

复杂的迁移场景
迁移压缩
数据库种子数据

加载 references/performance.md 当：

查询优化
索引策略
连接池管理