db.md

db

import { db, DbError, type TxContext } from "@sfmc-bds/sdk/sapi/db";

HTTP 映射见 数据库。

defineTable

只在 init 调用，不要放进 tx：

await db.defineTable(
  "lands",
  [
    { name: "id", type: "TEXT", primaryKey: true },
    { name: "owner_player_id", type: "TEXT" },
  ],
  { softDelete: true }
);

单步 CRUD（tx 外）

const rows = await db.query("lands", { where: { /* WhereExpr */ } });
const row = await db.get("lands", id);
await db.insert("lands", { id, owner_player_id: "..." });
await db.update("lands", id, { version: 2 });
await db.delete("lands", id);
await db.audit("lands", id, "transfer", { to: "..." });

事务

db.tx 走交互会话；回调内 await tx.* / tx.call 返回真实结果，可据此分支。

await db.tx(async (tx: TxContext) => {
  const row = await tx.get("lands", landId);
  if (!row) throw new Error("missing");
  await tx.update("lands", landId, { owner_player_id: newOwner });
  await tx.audit("lands", landId, "transfer", { from, to });
  const debit = await tx.call<{ ok: boolean }>("economy.debit", {
    playerId,
    amount: 100,
  });
  return { ok: true, debit };
});

tx 内不要混用外面的 db.query 等。

幂等

await db.idempotent("pay:order-123", async () => {
  /* 只执行一次的业务 */
});

WhereExpr

表达式树（如 { field, op, value }）。禁止 SQL 字符串。

错误

DbError 含平台错误码；权限不足、表冲突等由 HTTP 层返回 4xx。