Bunのbun:sqliteでSQLiteを読み書きする方法

​​Bun​SQLite,TypeScript

Bun には SQLite のドライバーが組み込まれていて、bun:sqlite から import するだけで使えます。npm でパッケージを入れる必要はありません。

CLI ツールの設定や履歴の保存、小さな Web アプリのデータ置き場、テスト用のデータベースなど、ローカルに1ファイルのデータベースを持たせたい場面で使えます。テーブルを作って読み書きする基本の形と、つまずきやすい点(パラメーターの書き忘れ、transaction と async、型の変換)、1万行を書き込んだときの時間を、実際の出力で確かめました。

補足

検証環境は Ubuntu 24.04(x86_64)、Bun 1.4.4 です。Bun に組み込まれた SQLite は 3.53.4 でした。コードは TypeScript で書き、bun ファイル名.ts で実行しています。複数のプロセスからの同時書き込み、拡張機能の読み込み(loadExtension)、ORM との組み合わせ、Windows と macOS は試していません。公式ドキュメントは、検証に使った版(タグ bun-v1.4.4)の元ファイルを GitHub で確認し、リンクもそこに張っています。

テーブルを作り、追加・検索・更新・削除をする

次の basic.ts で、猫の名前と年齢を入れるテーブルを作り、ひととおりの操作をしました。

ts
import { Database } from "bun:sqlite";

// ファイルがなければ作られる
const db = new Database("cats.sqlite");

db.run(`CREATE TABLE IF NOT EXISTS cats (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL UNIQUE,
  age INTEGER
)`);

// 追加:$name と $age に値を渡す
const insert = db.query("INSERT INTO cats (name, age) VALUES ($name, $age)");
console.log(insert.run({ $name: "たま", $age: 3 }));
console.log(insert.run({ $name: "みけ", $age: 5 }));
console.log(insert.run({ $name: "くろ", $age: 1 }));

// 1件だけ取り出す
const byName = db.query("SELECT * FROM cats WHERE name = ?");
console.log(byName.get("みけ"));
console.log(byName.get("しろ"));

// すべて取り出す
console.log(db.query("SELECT * FROM cats WHERE age >= ? ORDER BY age").all(2));

// 配列の配列で取り出す
console.log(db.query("SELECT name, age FROM cats ORDER BY id").values());

// 更新と削除も run() で、変わった行の数が返る
console.log(db.query("UPDATE cats SET age = age + 1").run());
console.log(db.query("DELETE FROM cats WHERE name = ?").run("くろ"));

console.log(db.query("SELECT sqlite_version() AS version").get());
db.close();

new Database("cats.sqlite") は、ファイルがなければ作ります。実行後、cats.sqlite ができていました。メモリ上だけで使うなら new Database(":memory:") と書きます(公式ドキュメントの、データベースを開く方法の説明)。

API はすべて同期で、await は要りません。db.query() で SQL をコンパイルし、返ってきた Statement のメソッドで実行します。メソッドごとに、結果の形が違います。

メソッド 返るもの
run() 変わった行の数(changes)と、最後に追加した行の ID(lastInsertRowid)
get() 最初の1行をオブジェクトで。行がなければ null
all() すべての行を、オブジェクトの配列で
values() すべての行を、配列の配列で

実行すると、次のように出力されました(見やすいよう、出力の間に空行を入れています)。

text
{
  changes: 1,
  lastInsertRowid: 1,
}
{
  changes: 1,
  lastInsertRowid: 2,
}
{
  changes: 1,
  lastInsertRowid: 3,
}

{
  id: 2,
  name: "みけ",
  age: 5,
}
null

[
  {
    id: 1,
    name: "たま",
    age: 3,
  }, {
    id: 2,
    name: "みけ",
    age: 5,
  }
]

[
  [ "たま", 3 ], [ "みけ", 5 ], [ "くろ", 1 ]
]

{
  changes: 3,
  lastInsertRowid: 3,
}
{
  changes: 1,
  lastInsertRowid: 3,
}

{
  version: "3.53.4",
}

INSERT の run() では、lastInsertRowid に追加した行の id が入りました。ない名前(しろ)で get() すると null です。UPDATE はすべての行に当たるので changes: 3、DELETE は1行なので changes: 1 になりました。UPDATE と DELETE の lastInsertRowid は、最後に INSERT した行の ID(3)のままです。

db.query() は、同じ SQL の文字列なら、準備済みの Statement を使い回します。使い回すのは SQL をコンパイルした結果だけで、検索の結果ではありません。値はそのつど渡すので、上の byName のように、1つの Statement に違う値を渡して何度も実行できます(公式ドキュメントの、query() のキャッシュについての説明)。

パラメーターの書き忘れは、既定では NULL になる

SQL に値を埋め込むときは、文字列をつなげずに、? や $name のパラメーターを使います。$name の値は、{ $name: "たま" } のようにキーに $ を付けても、{ name: "たま" } のように付けなくても渡せます(公式ドキュメントの、名前付きパラメーターのキーの説明)。

注意したいのは、パラメーターの値を渡し忘れたときです。既定では、エラーにならず NULL が入ります(公式ドキュメントの strict モードの説明)。次の params.ts で、$age を $agee と打ち間違えた場合を、strict を付けないときと付けたときで比べました。

ts
import { Database } from "bun:sqlite";

for (const strict of [false, true]) {
  const db = new Database(":memory:", { strict });
  db.run("CREATE TABLE cats (name TEXT, age INTEGER)");
  const insert = db.query("INSERT INTO cats (name, age) VALUES ($name, $age)");
  console.log(`--- strict: ${strict}`);
  try {
    // $ を付けずに書く
    insert.run({ name: "たま", age: 3 });
    // age を書き忘れる(agee と打ち間違える)
    insert.run({ $name: "みけ", $agee: 5 });
  } catch (e) {
    console.log(`${(e as Error).name}: ${(e as Error).message}`);
  }
  console.log(db.query("SELECT * FROM cats").all());
}
text
--- strict: false
[
  {
    name: "たま",
    age: 3,
  }, {
    name: "みけ",
    age: null,
  }
]
--- strict: true
Error: Missing parameter "age"
[
  {
    name: "たま",
    age: 3,
  }
]

strict を付けないと、打ち間違えた行も何も言わずに追加され、age が null になりました。strict: true では Missing parameter "age" のエラーになり、その行は追加されていません。新しく書くコードでは、new Database("cats.sqlite", { strict: true }) のように付けておくと、書き間違いにすぐ気づけます。

複数の書き込みは transaction でまとめる

db.transaction() に関数を渡すと、その関数をトランザクションの中で実行する関数が返ります。中で例外が起きると、それまでの書き込みはロールバックされます(公式ドキュメントのトランザクションの説明)。次の tx.ts では、name に UNIQUE 制約があるテーブルに、3件目で重複する名前を入れました。

ts
import { Database } from "bun:sqlite";

const db = new Database(":memory:");
db.run("CREATE TABLE cats (id INTEGER PRIMARY KEY, name TEXT NOT NULL UNIQUE)");
const insert = db.query("INSERT INTO cats (name) VALUES (?)");

const insertCats = db.transaction((names: string[]) => {
  for (const name of names) insert.run(name);
  return names.length;
});

console.log(`追加: ${insertCats(["たま", "みけ"])}件`);

try {
  // 「たま」はもうあるので、3件目で UNIQUE 制約に反する
  insertCats(["くろ", "しろ", "たま"]);
} catch (e) {
  console.log(`${(e as Error).name}: ${(e as Error).message}`);
}
console.log(db.query("SELECT name FROM cats ORDER BY id").values());

// トランザクションを使わずに同じことをすると、途中までの行が残る
try {
  for (const name of ["くろ", "しろ", "たま"]) insert.run(name);
} catch (e) {
  console.log(`${(e as Error).name}: ${(e as Error).message}`);
}
console.log(db.query("SELECT name FROM cats ORDER BY id").values());
text
追加: 2件
SQLiteError: UNIQUE constraint failed: cats.name
[
  [ "たま" ], [ "みけ" ]
]
SQLiteError: UNIQUE constraint failed: cats.name
[
  [ "たま" ], [ "みけ" ], [ "くろ" ], [ "しろ" ]
]

transaction の中で失敗したときは、先に入れた「くろ」と「しろ」も取り消され、2件のままでした。transaction を使わずに run() を続けると、失敗する前の2件が残りました。

1万行の書き込みは、transaction でまとめると8秒から7.6ミリ秒に縮んだ

transaction でまとめると、書き込みの速さも大きく変わります。ファイルのデータベースに1万行を INSERT する bench.ts を作り、1行ずつ run() した場合と、同じ処理を transaction でまとめた場合の時間を、performance.now() で測りました。ジャーナルの設定を3通りに変え、それぞれ3回ずつ実行しています。

ts
measure("1行ずつ", (db) => {
  const insert = db.query("INSERT INTO logs (message, at) VALUES (?, ?)");
  for (let i = 0; i < N; i++) insert.run(`message ${i}`, i);
});

measure("transaction でまとめる", (db) => {
  const insert = db.query("INSERT INTO logs (message, at) VALUES (?, ?)");
  const insertAll = db.transaction(() => {
    for (let i = 0; i < N; i++) insert.run(`message ${i}`, i);
  });
  insertAll();
});
設定 1行ずつ(3回) transaction(3回)
既定(journal_mode=delete、synchronous=2) 8,113.5 / 7,810.7 / 8,184.0 ms 7.6 / 8.5 / 6.0 ms
WAL 1,213.2 / 1,284.9 / 1,466.2 ms 5.5 / 7.0 / 8.2 ms
WAL + synchronous=NORMAL 113.2 / 119.8 / 98.9 ms 4.5 / 6.9 / 4.3 ms
1万行の INSERT にかかった時間の横棒グラフ。既定の設定(journal_mode=delete、synchronous=2)では1行ずつが 8,113.5 ms、transaction が 7.6 ms。WAL では 1,284.9 ms と 7.0 ms。WAL と synchronous=NORMAL では 113.2 ms と 4.5 ms
1万行の INSERT にかかった時間(各設定3回の中央値)

既定の設定では、1行ずつだと8秒前後かかり、transaction でまとめると10ミリ秒もかかりませんでした。中央値どうしで比べると、約1,000倍の差です。WAL にすると1行ずつでも1.2〜1.5秒、さらに synchronous = NORMAL にすると0.1秒前後まで縮みましたが、それでも transaction でまとめたほうが速い結果でした。この数字は、検証用VMのディスクでの結果です。

transaction に async 関数を渡さない

transaction に渡す関数は、同期の関数でなければいけません。公式ドキュメントによると、async 関数は最初の await で返るので、そこでコミットされます。それより後の処理はトランザクションの外で動き、そこで例外が起きてもロールバックされません(公式ドキュメントの、transaction に渡す関数についての注意)。次の tx-async.ts で確かめました。

ts
import { Database } from "bun:sqlite";

const db = new Database(":memory:");
db.run("CREATE TABLE cats (name TEXT)");
const insert = db.query("INSERT INTO cats (name) VALUES (?)");

const insertAsync = db.transaction(async (names: string[]) => {
  insert.run(names[0]);
  await Promise.resolve(); // ここで関数がいったん返り、コミットされる
  insert.run(names[1]);
  throw new Error("2件目のあとで失敗");
});

try {
  await insertAsync(["たま", "みけ"]);
} catch (e) {
  console.log(`${(e as Error).name}: ${(e as Error).message}`);
}
console.log(`inTransaction: ${db.inTransaction}`);
console.log(db.query("SELECT name FROM cats").values());
text
Error: 2件目のあとで失敗
inTransaction: false
[
  [ "たま" ], [ "みけ" ]
]

例外は呼び出し側に届きましたが、2件とも残りました。API から取ってきたデータを保存するときなどは、await で待つ処理を先に済ませ、そろった値を同期の transaction 関数に渡します。

WAL にすると、開いている間だけファイルが2つ増える

公式ドキュメントは、たいていのアプリで WAL モードを使うことを勧めています。PRAGMA synchronous = NORMAL を足すと、WAL ファイルをディスクへ同期するのが、コミットのたびではなくチェックポイントのときになります。そのかわり、電源が落ちると最後のいくつかのコミットが失われることがありますが、データベースが壊れることはないとされています(公式ドキュメントの WAL モードの説明)。

WAL にすると、データベースのファイルの横に -wal と -shm のファイルができます。次の files.ts で、開いている間と close() の後のファイルを比べました。読み取り専用で開くオプションと、ファイルがないときに作らないオプションも試しています。

ts
import { Database } from "bun:sqlite";
import { mkdirSync, readdirSync, rmSync } from "node:fs";

rmSync("memo", { recursive: true, force: true });
mkdirSync("memo");
const db = new Database("memo/app.sqlite");
console.log(db.query("PRAGMA journal_mode = WAL;").get());
db.run("CREATE TABLE notes (body TEXT)");
db.run("INSERT INTO notes VALUES ('hello')");
console.log("開いている間:", readdirSync("memo"));
db.close();
console.log("close() のあと:", readdirSync("memo"));

try {
  new Database("memo/nothing.sqlite", { create: false });
} catch (e) {
  console.log(`${(e as Error).name}: ${(e as Error).message}`);
}
const ro = new Database("memo/app.sqlite", { readonly: true });
try {
  ro.run("INSERT INTO notes VALUES ('x')");
} catch (e) {
  console.log(`${(e as Error).name}: ${(e as Error).message}`);
}
console.log(ro.query("SELECT * FROM notes").all());
text
{
  journal_mode: "wal",
}
開いている間: [ "app.sqlite", "app.sqlite-shm", "app.sqlite-wal" ]
close() のあと: [ "app.sqlite" ]
SQLiteError: unable to open database file
SQLiteError: attempt to write a readonly database
[
  {
    body: "hello",
  }
]

検証環境(Ubuntu)では、close() の後に -wal と -shm が消え、app.sqlite だけが残りました。公式ドキュメントによると、macOS の Bun は Apple が用意した SQLite を使うため、この2つのファイルが close() の後も残ります。消したいときの書き方も、WAL のファイルの後片付けについての説明に載っています。

{ create: false } を付けると、ファイルがないときに新しく作らず、unable to open database file のエラーになりました。{ readonly: true } で開いたデータベースに書き込むと、attempt to write a readonly database になり、読み出しはできました。

注意

WAL のデータベースを開いたまま、.sqlite のファイルだけをコピーしてバックアップしないでください。検証環境で、3行を書き込んだ直後に開いたままコピーしたところ、コピーしたファイルには notes テーブルそのものがなく、no such table: notes のエラーになりました。close() の後にコピーしたファイルには、3行とも入っていました。

JavaScript の値と SQLite の型の変換

値を渡すときと受け取るときの型も、次の types.ts で確かめました。

ts
import { Database } from "bun:sqlite";

const db = new Database(":memory:");
db.run("CREATE TABLE t (b, blob, big, d)");
db.query("INSERT INTO t VALUES (?, ?, ?, ?)").run(
  true,
  new Uint8Array([1, 2, 3]),
  2n ** 53n + 1n,
  new Date("2026-11-14T00:00:00Z").toISOString(),
);
console.log(db.query("SELECT b, typeof(b) AS b_type, blob, big, d FROM t").get());

const safe = new Database(":memory:", { safeIntegers: true });
console.log(safe.query("SELECT ? AS big").get(2n ** 53n + 1n));

try {
  db.query("SELECT ?").get(new Date() as any);
} catch (e) {
  console.log(`${(e as Error).name}: ${(e as Error).message}`);
}
text
{
  b: 1,
  b_type: "integer",
  blob: Uint8Array(3) [ 1, 2, 3 ],
  big: 9007199254740992,
  d: "2026-11-14T00:00:00.000Z",
}
{
  big: 9007199254740993n,
}
TypeError: Binding expected string, TypedArray, boolean, number, bigint or null

出力から、次のことが分かります。

  • true は整数の 1 として保存され、読み出しても true には戻りません。
  • Date はそのままでは渡せず、TypeError になりました。上のように ISO 形式の文字列にしてから渡します。
  • 2の53乗を超える整数は、既定では number で返るため、9007199254740993 が 9007199254740992 に変わりました。safeIntegers: true を付けると bigint で返り、値が保たれました。

渡せる型と SQLite の型の対応は、公式ドキュメントの型の対応表にまとまっています。整数の扱いは、整数についての節に説明があります。大きな整数の ID を読むときは、safeIntegers を付けておくと丸められません。

​Posted by 86