8. ヘッドレスモード（サーバー）

注釈

このセクションでは、サーバーへのデプロイ、マルチユーザー、自動化を対象とした、blunderDBの高度かつ任意のモードについて説明します。blunderDBの通常かつ推奨される使用方法は、前章で説明したデスクトップアプリケーションのままです。自分のコンピューター上でblunderDBを単独で使用する場合、このモードは必要ありません：分析機能を一切失うことなく、この章を読み飛ばすことができます。

8.1. 概要

同じバイナリ blunderdb は、デスクトップアプリケーションやコマンドライン（コマンドラインインターフェース（CLI） を参照）に加えて、ヘッドレスモード で動作することができます：グラフィカルインターフェースなしで、コマンドラインまたはネットワークから完全に操作されます。このモードは3つの用途をまとめています：

• デーモン serve — blunderDBのエンジンをHTTP + JSONサービスとして公開し、共有データベースをサーバー上で稼働させ、複数人でアクセスできるようにします；

• 汎用ディスパッチャ call — スクリプティングやテストのために、任意のストレージ操作をローカルで直接呼び出します；

• migrate コマンド — シングルユーザーのSQLiteデータベースをマルチユーザーのPostgreSQLバックエンドに転送します。

これら3つの用途は、2つのバックエンドと対話できる共通のストレージレイヤーに依存しています：SQLite（デスクトップアプリケーションの通常の .db ファイル形式）と PostgreSQL（マルチユーザーのサーバーデプロイ向け）です。

8.2. デーモン serve

blunderdb serve は、JSONで応答するHTTPサービスとしてエンジンを起動します。これにより、ポジションのデータベースを1台のマシン上でホストし、複数のクライアントからアクセスできるようになります。

# Servir une base SQLite locale sur le port 8080
blunderdb serve --db ma_base.db --addr :8080

# Servir un backend PostgreSQL
blunderdb serve --backend postgres \
    --dsn "postgres://user:pass@host:5432/blunderdb?sslmode=disable" \
    --addr :8080

警告

デーモンは認証を一切行いません。 リクエストヘッダー X-Tenant-ID を信頼しており、認証を担うリバースプロキシ（nginx、Caddy…）の背後で動作させる**必要があります**。決して公開インターネット上に直接公開しないでください。

オプション：

オプション	デフォルト	意味
--db <chemin>	–	SQLiteファイル（--backend sqlite --dsn <chemin> のショートカット）
--backend <type>	sqlite	ストレージバックエンド：sqlite または postgres
--dsn <chaîne>	$BLUNDERDB_DSN	バックエンドの接続文字列
--addr <hôte:port>	:8080	待ち受けアドレス
--log-level <niveau>	info	ログレベル：debug|info|warn|error
--metrics	true	/metrics を公開する（Prometheus形式）
--cors-allow-origin <origine>	–	このオリジンに対してCORSを有効にする（デフォルトでは無効）
--rate-limit-rps <n>	0	テナントごとの秒間リクエスト数の制限（0 = 無効）
--rate-limit-burst <n>	2×rps	リクエストのピークに対応するトークンバケットのサイズ
--rls	false	PostgreSQL：テナントごとのRow-Level Securityを有効にする（多層防御、オプション）

ほとんどのオプションは環境変数（BLUNDERDB_BACKEND、BLUNDERDB_DSN、BLUNDERDB_ADDR、BLUNDERDB_LOG_LEVEL、BLUNDERDB_RLS）でも指定できます。

8.2.1. エンドポイント

サービスは、常に利用可能な運用用のエンドポイントを公開しています：

• GET /healthz — 生存確認（プロセスが稼働中）；

• GET /readyz — 準備状態（ストレージが応答している）；

• GET /metrics — Prometheusメトリクス（--metrics が有効な場合）。

ビジネスロジックのインターフェースは POST /v1/<famille>.<méthode> のスキーマに従います（例：/v1/positions.save、/v1/matches.get）。ファミリーには、ポジション、分析、マッチ、コメント、コレクション、トーナメント、Ankiカード、フィルター、セッション、検索、メタデータ、統計、インポートが含まれます。一覧取得のエンドポイントはNDJSONストリーム（1行につき1つのJSONオブジェクト）を返します。サーバーは SIGINT / SIGTERM で正常に停止します。

positions ファミリーの2つのメソッドは、局面を保存せずにデコードします。positions.fromXGID は XGID 文字列から局面を再構築し、positions.fromXGP は単一局面ファイル .xgp から再構築します。

8.3. PostgreSQLバックエンドとマルチユーザー

共有デプロイの場合、blunderDBはSQLiteファイルではなく PostgreSQL にデータを保存できます。バックエンドは --backend postgres と接続文字列 --dsn で選択します。スキーマは起動時に自動的に作成・マイグレーションされます。

データは**テナント（利用者）ごとに分離**されています：各リクエストにはスコープ識別子（ヘッダー X-Tenant-ID、デフォルトは default）が付与され、これにより複数のユーザーが他者のデータを見ることなく同じインスタンスを共有できます。--rls オプションは、補完的にPostgreSQLの Row-Level Security を有効にします：テナントごとの分離ポリシーがインストールされ、app.tenant_id が接続ごとに設定されます。これは任意の多層防御であり、デフォルトでは無効です。

8.4. SQLiteデータベースをPostgreSQLへ移行する

blunderdb migrate は、シングルユーザーのSQLiteデータベースを、選択したテナントスコープのもとでPostgreSQLバックエンドにコピーします — これは、デスクトップのライブラリをサーバーデプロイへ「アップロード」するための手段です。

blunderdb migrate \
    --from sqlite:///chemin/vers/base.db \
    --to   "postgres://user:pass@host:5432/db?sslmode=disable" \
    --tenant-id mon-tenant

# Prévisualiser sans rien écrire
blunderdb migrate --from sqlite:///chemin/vers/base.db \
    --tenant-id mon-tenant --dry-run

このマイグレーションは、ポジション、その分析とコメント、マッチ（ゲーム + 手）、トーナメント（そのマッチリンクを含む）、コレクション（その構成を含む） をコピーし、主キーと外部キーを再割り当てします。これらはすべて、宛先側の**単一のトランザクション**内で行われます：操作はアトミックです（失敗しても宛先はそのまま残るため、再実行するだけで済みます）。進捗と最終的な集計は、標準出力にNDJSONで出力されます。

オプション	デフォルト	意味
--from <uri>	–	ソースのSQLiteデータベース（sqlite:///chemin または単なるパス）
--to <dsn>	–	宛先のPostgreSQL DSN（postgres://…）
--tenant-id <scope>	–	宛先のテナントスコープ（--dry-run 以外では必須）
--dry-run	–	何も書き込まずに、コピーされる内容を数える
--on-conflict <politique>	""	"" はテナントにすでにデータがある場合に中断します；skip はマージします（Zobristハッシュによるポジションの重複排除）

注釈

アプリケーションの状態は（まだ）移行されません：Ankiのデッキ/カード、フィルターライブラリ、検索およびコマンドの履歴、セッションのメタデータ。優先されるのは、ポジションライブラリとマッチ履歴の移行です。

8.5. 汎用ディスパッチャ call

従来のサブコマンド（コマンドラインインターフェース（CLI））を補完するものとして、blunderdb call は**すべての**ストレージ操作をローカルで直接公開します。デーモン serve と同じハンドラを経由するため、動作は POST /v1/<famille>.<méthode> と同一です。スクリプティングや統合テストに便利です。

# Lister toutes les méthodes disponibles
blunderdb call --list

# Lectures
blunderdb call metadata.counts --db ma_base.db
blunderdb call positions.list  --db ma_base.db --json '{"limit":10}'
blunderdb call matches.get     --db ma_base.db --json '{"id":1}'

# Écritures
blunderdb call positions.save  --db ma_base.db --json '{"position":{...}}'
blunderdb call matches.delete  --db ma_base.db --json '{"id":42}'

オプション：

オプション	デフォルト	意味
--db <chemin>	–	SQLiteファイル（--backend sqlite --dsn <chemin> のショートカット）
--backend <type>	sqlite	sqlite または postgres
--dsn <chaîne>	$BLUNDERDB_DSN	バックエンドの接続文字列
--scope <chaîne>	default	テナントスコープ（X-Tenant-ID として送信される）
--json <chaîne>	{}	JSON形式のリクエストボディ
--json-file <chemin>	–	ファイルからリクエストボディを読み込む
--list	–	すべての <famille>.<méthode> メソッドを表示して終了する

JSONレスポンス（または *.list エンドポイントの場合はNDJSONストリーム）は標準出力に書き込まれます。エラーが発生した場合、プロセスは非ゼロのコードで終了し、解析可能な状態を保つために（例えば jq で）、{"error":{…}} というエンベロープが標準出力に出力されます。