はじめに#

ブラウザにはリレーショナルではないものの、構造化データを大量に保存できる IndexedDB が組み込まれています。
PWA やローカルファーストなアプリでは避けて通れないストレージですが、
生の API はコールバックベースで冗長、トランザクション管理が煩雑、型の恩恵もありません。

Dexie.js は IndexedDB の上に Promise ベースの薄いラッパーを提供するライブラリです。
TypeScript との相性がよく、スキーマのバージョン管理も宣言的に書けます。
この記事では Dexie.js v4 の導入から日常的な CRUD、スキーマ移行までを紹介します。

生の IndexedDB がつらい理由#

IndexedDB の API をそのまま使うと、データベースのオープンだけでこれだけのコードが必要です。

1
const request = indexedDB.open("mydb", 1);
2
request.onupgradeneeded = (event) => {
3
  const db = (event.target as IDBOpenDBRequest).result;
4
  if (!db.objectStoreNames.contains("tasks")) {
5
    db.createObjectStore("tasks", { keyPath: "id", autoIncrement: true });
6
  }
7
};
8
request.onsuccess = (event) => {
9
  const db = (event.target as IDBOpenDBRequest).result;
10
  // ここからトランザクションを開いて操作...
11
};
12
request.onerror = (event) => {
13
  console.error("DB open failed", event);
14
};

イベントハンドラのネスト、型の不在、エラーハンドリングの散在。
localStorage の手軽さと比べると、導入コストが高すぎます。

Dexie.js のセットアップ#

$ pnpm add dexie

データベースの定義は class ベースで書きます。

1
import Dexie, { type EntityTable } from "dexie";
2

3
interface Task {
4
  id: number;
5
  title: string;
6
  done: boolean;
7
  createdAt: Date;
8
}
9

10
const db = new Dexie("taskdb") as Dexie & {
11
  tasks: EntityTable<Task, "id">;
12
};
13

14
db.version(1).stores({
15
  tasks: "++id, done, createdAt",
16
});
17

18
export { db };
19
export type { Task };

"++id, done, createdAt" はインデックスの定義です。
++ は自動採番の主キー、カンマ区切りでセカンダリインデックスを追加します。
ここに書かなかったプロパティもデータとしては保存されますが、インデックスで検索できないだけです。

CRUD 操作#

Dexie の API は直感的です。Promise を返すので async/await でそのまま書けます。

1
await db.tasks.add({
2
  title: "記事を書く",
3
  done: false,
4
  createdAt: new Date(),
5
});

1
// 全件取得
2
const allTasks = await db.tasks.toArray();
3

4
// 条件付き取得
5
const pending = await db.tasks.where("done").equals(false).toArray();
6

7
// 主キーで取得
8
const task = await db.tasks.get(1);

1
await db.tasks.update(1, { done: true });

1
await db.tasks.delete(1);

スキーマのバージョン管理#

アプリの進化に伴い、テーブル構造を変更したくなるのは必然です。
Dexie はバージョンを積み上げる宣言的な移行をサポートしています。

1
db.version(1).stores({
2
  tasks: "++id, done, createdAt",
3
});
4

5
db.version(2).stores({
6
  tasks: "++id, done, createdAt, priority",
7
});
8

9
db.version(3)
10
  .stores({
11
    tasks: "++id, done, createdAt, priority",
12
    tags: "++id, name",
13
  })
14
  .upgrade((tx) => {
15
    return tx
16
      .table("tasks")
17
      .toCollection()
18
      .modify((task) => {
19
        task.priority = task.priority ?? "medium";
20
      });
21
  });

バージョン 2 で priority インデックスを追加し、バージョン 3 で tags テーブルを追加しつつ既存データにデフォルト値を埋めています。
upgrade コールバックでデータマイグレーションも書けるのがポイントです。

過去のバージョン定義は消さずに残す必要があります。
ユーザーがバージョン 1 のまま久しぶりにアクセスした場合、Dexie は 1 → 2 → 3 と順番にマイグレーションを実行してくれます。

実践的なパターン#

1
const recentPending = await db.tasks
2
  .where("done")
3
  .equals(false)
4
  .and((task) => task.createdAt > oneWeekAgo)
5
  .sortBy("createdAt");

1
await db.tasks.bulkAdd([
2
  { title: "タスク A", done: false, createdAt: new Date() },
3
  { title: "タスク B", done: false, createdAt: new Date() },
4
  { title: "タスク C", done: false, createdAt: new Date() },
5
]);
6

7
await db.tasks.where("done").equals(true).delete();

注意点#

• 容量制限はブラウザ依存
  Chrome はオリジンごとにディスク空き容量の一定割合（目安で数百 MB〜数 GB）まで。
  Safari 17 以降も同様にディスクベースの上限が適用されます。
  ただし、ユーザーがストレージをクリアすればデータは消えるため、永続化が必須ならサーバーとの同期を別途設計する必要があります。

• Web Worker からもアクセス可能
  IndexedDB はメインスレッドと Web Worker の両方から使えます。
  重い集計処理は Worker に逃がすと UI がブロックされません。

• DevTools で中身を確認できる
  Chrome DevTools の Application タブ → IndexedDB からテーブルの中身をリアルタイムで確認できます。
  デバッグ時に重宝します。

まとめ#

• IndexedDB はブラウザ内蔵の強力なストレージだが、生の API は実用にはつらすぎる
• Dexie.js を入れれば Promise ベースの直感的な API で CRUD が 1 行で書ける
• スキーマのバージョン管理が宣言的に書けるため、アプリの進化に追従しやすい
• ローカルファーストなアプリや PWA のデータ層として、導入コストに対するリターンが大きい

次の記事では、IndexedDB とは異なるアプローチでブラウザ内にリレーショナル DB を持ち込む SQLite WASM + OPFS を紹介します。