electricsql

ElectricSQL

概要

ElectricSQL は、Shapes を介して Postgres データの部分レプリカをローカルクライアントにストリーミングする同期エンジンです。読み取りパスを処理し、論理レプリケーションを使って Postgres の行をクライアントにリアルタイムで同期します。書き込みは既存の API を経由し、Electric は確定した状態をすべての接続済みクライアントに同期します。

使用するケース： Postgres からクライアントアプリへのリアルタイム同期、Postgres のライブデータを必要とするローカルファーストアーキテクチャ、ポーリングからストリーミング更新への置き換え、Electric コレクションを使う TanStack DB アプリ、Postgres を基盤とする複数クライアントのコラボレーションアプリ。

使用しないケース： Postgres 以外のデータベース、エンジンに組み込まれたクライアントからサーバーへの同期が必要なアプリ（Electric が処理するのは読み取りのみです）、リアルタイム機能を必要としないシンプルな REST CRUD、ローカルデータのメリットを活かせないアプリ。

クイックリファレンス

パターン	API／アプローチ	要点
Shape リクエスト	GET /v1/shape?table=items&offset=-1	初回同期では完全なスナップショットを取得します
ライブ更新	?live=true&handle=...&offset=...	初回同期後のリアルタイム変更をロングポーリングします
SSE ストリーミング	?live=true&live_sse=true	持続的な Server-Sent Events 接続
Where 句	?where=status='active'	サーバー側で SQL スタイルの行フィルタリング
パラメーター化された Where 句	?where=user_id=$1&params[1]=abc	SQL インジェクションを防止するパラメーター化フィルタリング
列の選択	?columns=id,title,status	必要な列だけを同期して帯域幅を削減
完全なレプリカ	?replica=full	更新と削除の際に完全な行データを返します
変更のみ	?log=changes_only	初回スナップショットを省略し、新しい変更のみを受信します
ShapeStream（JS）	new ShapeStream({ url, params: { table } })	自動再接続機能を備えた低レベルのストリーミングクライアント
Shape（JS）	new Shape(stream)	ストリームを現在の値の Map に実体化します
useShape（React）	useShape({ url, params: { table } })	読み込み／エラー状態を扱う React フック
認証プロキシ	API サーバー経由で Shapes をルーティング	トークンを検証し、ユーザーごとに Where 句を挿入
Docker のセットアップ	docker run -e DATABASE_URL=... electricsql/electric	単一コンテナーで動作します。wal_level=logical が必要です
Electric シークレット	ELECTRIC_SECRET=key env var	本番環境では必須です。開発環境では ELECTRIC_INSECURE=true を使用します

よくある間違い

間違い	正しいパターン
Electric をインターネットに直接公開する	トークンを検証する認証プロキシの背後に Electric を配置します
Postgres の設定で wal_level=logical を忘れる	論理レプリケーションに必須です。設定しないと Electric は起動しません
Electric を書き込みに使用する	Electric は読み取り専用です。書き込みは API 経由で行います
書き込みハンドラーから txid を返さない	{ txid } を返して、Electric が同期完了を確認できるようにします
すべてのクライアントにテーブル全体を同期する	部分レプリケーションには where 句とカラム選択を使用します
クライアントコードに shape URL をハードコードする	認証と where 句をサーバー側で追加するプロキシエンドポイントを使用します
すべてのリクエストで offset=-1 を使用する	offset=-1 は初回同期時のみ使用し、その後は返された offset を使用します
ShapeStream で FetchError 401 を処理しない	onError コールバックを使用してトークンを更新し、再試行します

委任

local-first スキルが利用可能な場合は、アーキテクチャの決定と同期エンジンの比較をそのスキルに委任します。 利用できない場合は、次を推奨します：pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y tanstack-db スキルが利用可能な場合は、コレクションのセットアップ、ライブクエリ、楽観的ミューテーションのパターンをそのスキルに委任します。 利用できない場合は、次を推奨します：pnpm dlx skills add oakoss/agent-skills -s tanstack-db -a claude-code -y tanstack-start スキルが利用可能な場合は、サーバー関数を使用した shape プロキシの実装をそのスキルに委任します。 利用できない場合は、次を推奨します：pnpm dlx skills add oakoss/agent-skills -s tanstack-start -a claude-code -y

• セットアップとデプロイ：Docker と Postgres の設定には Task エージェントを使用します
• アーキテクチャレビュー：認証プロキシと書き込みパターンの設計には Plan エージェントを使用します

参考資料

• セットアップ、Docker、Postgres の設定
• Shapes、ShapeStream、React フック
• 認証とセキュリティのパターン
• オンラインから through-the-DB までの書き込みパターン
• 可観測性とモニタリング
• 同期パフォーマンスの最適化
• エラー処理、再試行パターン、txid フロー、制御メッセージ