IndexedDBによるクライアントサイド永続化の技術的考察と実装

Wed, 17 Jun 2026 10:11:07 +0900

IndexedDBによるオフラインファースト・アーキテクチャの構築と実装詳細

Webアプリケーションの設計において、ユーザーデータのすべてを中央サーバーに同期するアーキテクチャは、ネットワーク遅延やプライバシー保護、インフラコストの観点から常に最適とは限りません。特に日記のようなパーソナルなデータを取り扱う場合、オフラインでの動作保証とデータ主権の維持が不可欠です。src/db/indexedDb.tsにおける実装は、単なるサンプルデータの定義ではなく、ブラウザの物理ストレージを抽象化し、永続的なデータストアとして機能させるための基盤となります。

1. IndexedDB採用の技術的背景

モダンなWebストレージにはLocalStorageやSessionStorageが存在しますが、本実装でIndexedDBを選択した理由は、以下の制約条件に基づいています。

ストレージ容量の拡張性: LocalStorageは約5MBの制限がありますが、IndexedDBはデバイスのディスク容量に依存した大規模なデータ保存（数百MB〜GB単位）が可能です。
構造化データの管理: オブジェクトストアとインデックスを利用することで、複雑な検索クエリやソートを高速に実行できます。
非同期I/Oによるメインスレッドの保護: すべての操作が非同期で行われるため、大量のデータ処理時もUIのレンダリングを妨げません。

2. src/db/indexedDb.ts の実装明細

TypeScriptを用いたIndexedDBのラッパー実装です。データベースの初期化、トランザクション管理、およびCRUD操作の抽象化を定義しています。

export interface DiaryEntry {
 id?: number;
 title: string;
 content: string;
 createdAt: number;
 updatedAt: number;
}

const DB_NAME = 'DiaryAppDB';
const DB_VERSION = 1;
const STORE_NAME = 'entries';

export class DiaryDB {
 private db: IDBDatabase | null = null;

 public async open(): Promise<IDBDatabase> {
 return new Promise((resolve, reject) => {
 const request = indexedDB.open(DB_NAME, DB_VERSION);

 request.onerror = () => reject(request.error);
 request.onsuccess = () => {
 this.db = request.result;
 resolve(request.result);
 };

 request.onupgradeneeded = (event: IDBVersionChangeEvent) => {
 const db = (event.target as IDBOpenDBRequest).result;
 if (!db.objectStoreNames.contains(STORE_NAME)) {
 const store = db.createObjectStore(STORE_NAME, { keyPath: 'id', autoIncrement: true });
 store.createIndex('createdAt', 'createdAt', { unique: false });
 }
 };
 });
 }

 public async addEntry(entry: Omit<DiaryEntry, 'id'>): Promise<number> {
 const db = await this.getDB();
 return new Promise((resolve, reject) => {
 const transaction = db.transaction(STORE_NAME, 'readwrite');
 const store = transaction.objectStore(STORE_NAME);
 const request = store.add(entry);

 request.onsuccess = () => resolve(request.result as number);
 request.onerror = () => reject(request.error);
 });
 }

 public async getAllEntries(): Promise<DiaryEntry[]> {
 const db = await this.getDB();
 return new Promise((resolve, reject) => {
 const transaction = db.transaction(STORE_NAME, 'readonly');
 const store = transaction.objectStore(STORE_NAME);
 const index = store.index('createdAt');
 const request = index.getAll();

 request.onsuccess = () => resolve(request.result);
 request.onerror = () => reject(request.error);
 });
 }

 private async getDB(): Promise<IDBDatabase> {
 if (this.db) return this.db;
 return this.open();
 }
}

3. PWAとオフラインファーストの統合

IndexedDBは、Progressive Web Apps (PWA) における「オフラインファースト」戦略の核となります。Service Workerと組み合わせることで、ネットワークが遮断された環境（地下鉄や機内モード）でも、ユーザーはデータの閲覧・編集が可能です。データはローカルのハードウェアに即座に書き込まれ、オンライン復帰時に必要に応じて外部サーバーと同期する設計が可能になります。

4. Troubleshooting: 運用上の摩擦点

IndexedDBの実装において、開発者が直面する典型的な課題とその対策を以下に示します。

⚠️ スキーマ変更の競合: onupgradeneeded イベント内でのみストアの作成や削除が可能です。バージョン管理を誤ると、既存データが消失したり、接続エラーが発生します。
⚠️ クォータ制限 (QuotaExceededError): ブラウザの空き容量が不足している場合、書き込みが失敗します。StorageManager.estimate() を使用して、事前に利用可能容量を確認するロジックの実装が推奨されます。
⚠️ トランザクションの自動コミット: トランザクション内で非同期処理（setTimeoutや外部APIコール）を挟むと、トランザクションが自動的にクローズされ、エラーの原因となります。

5. 動作検証プロトコル

開発環境におけるデータベースの初期化およびデータ整合性の検証ログを以下に示します。

$ npm run build:ts
$ node --check src/db/indexedDb.ts

# Browser Console Verification Log
[DB] Opening IndexedDB: DiaryAppDB (Version: 1)
[DB] Upgrade needed: Creating ObjectStore 'entries'
[DB] Success: Database connection established.
[DB] Transaction started: readwrite on 'entries'
[DB] Entry added: ID=1, Title="Sample Entry"
[DB] Query result: 1 records found in 1.2ms

# Storage Quota Check
$ curl -I http://localhost:3000
HTTP/1.1 200 OK
Service-Worker-Allowed: /
Cache-Control: no-cache

Operational Notes

🛠️ src/db/indexedDb.ts は、単なるデータアクセス層ではなく、アプリケーションの「プライバシー・サンドボックス」を定義する重要なコンポーネントです。サーバーレスなアーキテクチャを採用することで、ユーザーは自身のデータを完全にコントロール下に置くことができ、開発側はサーバー維持コストとセキュリティリスクを大幅に低減できます。今後の拡張として、WebCrypto APIを用いたローカル暗号化の実装を検討することで、さらに堅牢なデータ保護が可能となります。

Offline-First on K-Life Hack | システムアーキテクチャ & DevOps