跳到正文
Drizzle

事务

使用 db.transaction 保证多条写入的原子性,理解回滚、隔离级别、保存点与驱动差异。

当多条写入必须「同生共死」时,就需要事务。Drizzle 的事务 API 是一层薄封装:回调中的 tx 与 db 用法一致,回调正常返回则提交,抛出异常则回滚。

基本用法

import { eq, sql } from 'drizzle-orm';
import { db } from './db';
import { accounts, ledger } from './db/schema';

await db.transaction(async (tx) => {
  await tx
    .update(accounts)
    .set({ balance: sql`${accounts.balance} - ${100}` })
    .where(eq(accounts.id, fromId));

  await tx
    .update(accounts)
    .set({ balance: sql`${accounts.balance} + ${100}` })
    .where(eq(accounts.id, toId));

  await tx.insert(ledger).values({
    fromId,
    toId,
    amount: 100,
  });
});

回调中的任何一条语句失败,或者你主动抛出异常,整个事务都会回滚。

主动回滚

class InsufficientFunds extends Error {}

try {
  await db.transaction(async (tx) => {
    const [account] = await tx
      .select()
      .from(accounts)
      .where(eq(accounts.id, fromId));

    if (!account || account.balance < amount) {
      throw new InsufficientFunds();
    }

    await tx
      .update(accounts)
      .set({ balance: sql`${accounts.balance} - ${amount}` })
      .where(eq(accounts.id, fromId));
  });
} catch (error) {
  if (error instanceof InsufficientFunds) {
    // 事务已回滚,返回业务错误
  }
  throw error;
}

不要在事务里吞掉异常

如果在回调内部捕获了错误却没有重新抛出,Drizzle 会认为事务成功并提交。业务错误应在事务外处理,或捕获后重新抛出。

返回值

const newOrder = await db.transaction(async (tx) => {
  const [order] = await tx
    .insert(orders)
    .values({ userId, total: 199 })
    .returning();

  await tx.insert(orderItems).values({
    orderId: order.id,
    productId,
    quantity: 1,
  });

  return order;
});

回调的返回值会作为 db.transaction() 的结果。

隔离级别与访问模式

PostgreSQL 与 MySQL 支持在事务选项中指定隔离级别:

await db.transaction(
  async (tx) => {
    // ...
  },
  {
    isolationLevel: 'serializable',
    accessMode: 'read only',
  },
);

常见级别:

级别说明
read committed默认级别,可能发生不可重复读与幻读
repeatable read同一事务内多次读取结果一致
serializable最高隔离,冲突时可能要求重试

可序列化事务在高并发下可能因序列化冲突而失败,应用需要实现重试逻辑。

SQLite 的事务选项不同,它通过 behavior 控制锁的获取时机:

await db.transaction(async (tx) => {
  // ...
}, { behavior: 'immediate' });

嵌套事务与保存点

在 PostgreSQL 与 MySQL 中,在事务内再次调用 tx.transaction() 会创建保存点(savepoint),内层回滚不会影响外层已执行的语句:

await db.transaction(async (tx) => {
  await tx.insert(auditLogs).values({ event: 'start' });

  try {
    await tx.transaction(async (inner) => {
      await tx.insert(orders).values(order);
      throw new Error('业务校验失败');
    });
  } catch {
    // 仅内层保存点回滚,外层仍可提交
  }

  await tx.insert(auditLogs).values({ event: 'end' });
});

不同驱动的嵌套行为可能不同,SQLite 的保存点支持也受驱动版本影响,使用前请确认目标驱动的文档。

行级锁

在 PostgreSQL/MySQL 中,可以在事务内对读取的行加锁,避免并发修改:

const [account] = await tx
  .select()
  .from(accounts)
  .where(eq(accounts.id, accountId))
  .for('update');

SQLite 没有 SELECT ... FOR UPDATE,写事务本身会锁定数据库。

实践建议

  • 保持事务短小:不要在事务中调用外部 API、发送邮件或等待用户输入。
  • 顺序一致:多张表、多行加锁时保持固定顺序,降低死锁概率。
  • 设置超时:通过连接池或数据库参数设置语句与锁等待超时。
  • 失败可重试:对序列化冲突、死锁等可重试错误实现退避重试。
  • 区分读写:只读事务可以指定 read only,减少锁与开销。

边缘数据库的限制

Cloudflare D1 等边缘数据库对交互式事务的支持有限,通常只能通过批量语句保证原子性。请根据驱动能力调整方案,不要在 Worker 中假设可以开启长事务。

下一步