env.db
ワーカーで使うデータベース API です。exec、tryExec、session、identity を提供します。
export interface Db {
exec(sql: string, params?: unknown[]): Promise<unknown[]>;
tryExec(sql: string, params?: unknown[]): Promise<TryExecResult>;
session(): Promise<DbSession>;
identity(): Promise<{ project: string; epoch: number }>;
}exec
成功すると行の配列を返し、SQL の実行に失敗するとエラーを送出します。
const rows = await env.db.exec(
"insert into posts (title) values ($1) returning id",
["hello"],
);バインドパラメータの番号は $1 から始まります。SQL 文字列を連結せず、2 番目の引数としてパラメータを渡してください。
1 文には 10 秒の上限 があります。超えると 57014 で打ち切られます。
tryExec
エラーを送出せず、結果オブジェクトを返します。コードから SQLSTATE を確実に確認したい場合は、この API を使用してください。
const r = await env.db.tryExec("insert into users (email) values ($1)", [email]);
if (!r.ok) {
if (r.error.code === "23505") return new Response("このメールアドレスは既に登録されています", { status: 409 });
throw new Error(r.error.message);
}成功した結果の形式は次のとおりです。
{
ok: true,
columns: [{ name: "id", typeOid: 23 }],
values: [[1]], // 位置ベースの配列: 同じ列名があっても値を保持します
rows: [{ id: 1 }],
commandTag: "SELECT 1",
transactionStatus: "I",
}失敗した結果の形式は次のとおりです。
{
ok: false,
error: { code: "23505", message: "…", detail: null, hint: null, position: null, severity: "ERROR" },
}exec が送出する Error には .code プロパティがありません。ワーカーの境界を越えるエラーオブジェクトでは、カスタムプロパティが保持されないためです。エラーメッセージの先頭には [42P01] のように SQLSTATE を付けますが、プログラムで利用すべき値は tryExec(...).error.code です。@runlot/pg を使う場合は、ワーカー内部の JavaScript で処理するため err.code を利用できます。session
BEGIN … COMMIT のように、複数の SQL 文を同じセッションで実行する必要がある場合に使用します。
const s = await env.db.session();
try {
await s.exec("begin");
await s.exec("update accounts set balance = balance - $1 where id = $2", [100, 1]);
await s.exec("update accounts set balance = balance + $1 where id = $2", [100, 2]);
await s.exec("commit");
} finally {
await s.close();
}close() は複数回呼び出しても安全で、開いているトランザクションはロールバックします。コミットするには close() に頼らず、自分で COMMIT を送信してください。詳しくはセッションを参照してください。
identity
現在のリクエストが接続されているプロジェクトと、データベースの世代番号を返します。デバッグやログ記録に利用できます。
const { project, epoch } = await env.db.identity();SQL の値が JavaScript に変換される方法
値を暗黙のうちに失わないことを原則としています。
| SQL 型 | JavaScript の値 |
|---|---|
int2 int4 float4 float8 | number |
int8 numeric | string — number に変換して丸めることはありません |
bool | boolean |
text varchar uuid | string |
bytea | ArrayBuffer |
json jsonb | パースした値。パースに失敗した場合は元の文字列 |
timestamp timestamptz date | string — タイムゾーンと精度を保持します |
| 配列、ドメイン、拡張型 | { text, typeOid } または string |
表にない型は文字列として返します。基になる型を推測して変換することはありません。
timestamptz の文字列は PostgreSQL の表記 (2026-09-04 13:38:14+00) です。ブラウザの new Date() がこの形をどこでも読めるわけではありません (Safari は Invalid Date を返します)。ISO 8601 が必要なら SQL で to_json(col) を使うか、@runlot/pg を使ってください。
timestamptz と date が Date オブジェクトとして返されます。2 つの API で日付型が異なる点にご注意ください。