pglite

PGlite

概要

PGlite は、外部依存関係なしでブラウザー、Node.js、Bun 上で直接動作する、軽量な PostgreSQL 17.4 の WASM ビルドです。3MB 未満（gzip 圧縮時）で、拡張機能、トランザクション、COPY のサポート、listen/notify を備えた完全な Postgres クエリエンジンを提供します。

使用する場合： 実際の SQL エンジンを必要とするローカルファーストアプリ、ブラウザーベースの分析、オフライン対応の PWA、テスト用の組み込み Postgres、サーバーなしでのプロトタイピング。

使用しない場合： 高い同時実行性が求められるサーバーワークロード（ネイティブ Postgres を使用してください）、完全な Postgres レプリケーションを必要とするアプリ、Safari の OPFS ストレージ（未サポート）、リーダー選出なしで書き込みが多いマルチタブのシナリオ。

クイックリファレンス

パターン	API	主なポイント
インスタンスを作成	PGlite.create(dataDir?, options?)	内部で準備完了を待機します
インメモリ DB	PGlite.create()	デフォルト、一時的なストレージ
IndexedDB ストレージ	PGlite.create('idb://dbname')	ブラウザー内で永続化されます
OPFS ストレージ	PGlite.create('opfs-ahp://dbname')	Worker 専用、Safari では使用不可
パラメーター化クエリ	db.query<T>(sql, params)	QueryResult<T> を返します
タグ付きテンプレート	db.sql\SELECT ...``	自動的にパラメーター化されます
複数ステートメントの実行	db.exec(sqlString)	パラメーターなし、void を返します
トランザクション	db.transaction(async (tx) => {})	完全な ACID、tx.query を使用してください
拡張機能を読み込む	create の extensions: { vector }	インスタンスの構築時に読み込まれます
ライブクエリ	db.live.query(sql, params, cb)	データ変更時に再実行します
インクリメンタルクエリ	db.live.incrementalQuery(sql, params, key, cb)	大きな結果セットの差分を取得します
ライブ変更	db.live.changes(sql, params, key, cb)	生の insert/update/delete 操作
React フック	useLiveQuery(sql, params)	{ rows } をリアクティブに返します
マルチタブ Worker	PGliteWorker + リーダー選出	単一の書き込み元、複数の読み取り元
Electric 同期	syncShapeToTable(db, shape, table)	一方向の読み取り専用同期
データをダンプ	db.dumpDataDir('gzip')	File blob を返します
データを読み込む	PGlite.create({ loadDataDir: blob })	ダンプから復元します
Listen/notify	db.listen(channel, cb)	Postgres LISTEN/NOTIFY
耐久性を緩和	relaxedDurability: true	ブラウザーでの書き込み性能が向上します

よくある間違い

間違い	正しいパターン
new PGlite() を使用し、準備完了を待たない	内部で待機する PGlite.create() を使用します
メインスレッドで OPFS を使用する	OPFS-AHP には Web Worker コンテキストが必要です
Safari で OPFS を使用する	Safari には必要な OPFS API がないため、idb:// を使用します
トランザクションコールバックの外でクエリを実行する	トランザクションコールバックから tx を渡し、tx.query() を使用します
create オプションに拡張機能を指定し忘れる	拡張機能は PGlite.create({ extensions }) で宣言する必要があります
リーダー選出をせずに複数のタブから書き込む	複数タブにはリーダー選出を備えた PGliteWorker を使用します
Electric の同期が双方向だと想定する	Electric の同期は読み取り専用で、サーバーからの一方向です
大規模なデータセットに live.query() を使用する	大量の結果セットには live.incrementalQuery() を使用します
増分クエリに key を指定しない	増分クエリと変更クエリには一意なキー列が必要です
バンドラーのサポートなしで拡張機能をインポートする	拡張機能は WASM です。バンドラーが .wasm アセットを処理できることを確認してください

委任

electricsql スキルが利用可能な場合は、Electric の同期パターン、Shape の設定、リアルタイムレプリケーションを委任してください。 利用できない場合は、次を推奨してください：pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y

drizzle-orm スキルが利用可能な場合は、Drizzle と PGlite のドライバー設定およびスキーマ管理を委任してください。 利用できない場合は、次を推奨してください：pnpm dlx skills add oakoss/agent-skills -s drizzle-orm -a claude-code -y

local-first スキルが利用可能な場合は、ローカルファーストアーキテクチャの判断と同期エンジンの選定を委任してください。 利用できない場合は、次を推奨してください：pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y

リファレンス

• インストール、ストレージバックエンド、設定
• クエリ、トランザクション、COPY、listen/notify、データのインポート／エクスポート
• 拡張機能：pgvector、pg_trgm、pgcrypto、全文検索など
• ライブクエリ：リアクティブ、増分、変更追跡
• React 連携：プロバイダー、フック、型付きパターン
• 複数タブのワーカーアーキテクチャとリーダー選出
• Electric の同期：シェイプ、トランザクション同期、永続化