データベースとバックアップ

デフォルトの SQLite はほとんどの環境で十分です。このページでは、切り替えるべき場合と、実際に復元できるバックアップ方法を説明します。

どれを使うべきか§

3つのドライバーはすべて同等にサポートされており、機能差はありません。違いは運用面です：

ドライバ	適している	コスト
SQLite	デフォルト、何もインストールする必要はありません。単一マシンへのデプロイでは推奨されます。	データはローカルファイルにあり、マシンとともに移動します
MySQL	すでに MySQL 運用体制があり、バックアップと監視を統一したい	さらに維持すべきサービスが1つ
PostgreSQL	上と同じ、PGエコシステムを優先	上と同じ

パフォーマンスのために変更する必要はない

2.0 は単一インスタンスでの運用向けです。外部データベースへ切り替えても横方向のスケーラビリティは得られません。また、データベースが性能ボトルネックになることはほとんどありません。主な理由は、既存のバックアップ手順など運用を統一することです。

DSN の書き方§

接続先はDATABASE_DSNで指定します。空欄の場合は管理対象のSQLiteで、DATA_DIR/gpt-load.dbにあります。

三種類のドライバのDSN

# 空欄：管理対象の SQLite（デフォルト）
DATABASE_DSN=

# 外部 SQLite：ファイルパスを指定
DATABASE_DSN=sqlite:///var/lib/gpt-load/data.db

# MySQL
DATABASE_DSN=mysql://user:password@db.example:3306/gpt_load

# PostgreSQL
DATABASE_DSN=postgres://user:password@db.example:5432/gpt_load

ドライバー固有の接続オプションはクエリ文字列に追加します：

パラメータ付き

# MySQL は TLS を使用
mysql://user:pass@db.example:3306/gpt_load?tls=true

# PostgreSQL は SSL が必要
postgres://user:pass@db.example:5432/gpt_load?sslmode=require

空でない DSN はすべて自分で管理するとみなされます

DATABASE_DSNが空でない場合、ゲートウェイはこのデータベースのディレクトリとファイル権限を引き継ぎません。外部 SQLite のパスがデフォルト位置と同じでも変わりません。権限、バックアップ、ディスク管理は利用者の責任です。

接続プールサイズは設定できます。環境変数を参照してください。

スキーママイグレーション§

バージョンアップでスキーマが変わる場合は、起動時に自動でマイグレーションを完了します。手動コマンドは不要です。3つのドライバーは同じ順序付きマイグレーションを使い、完了済みをスキップして残りを順番に適用します。

アップグレード前にバックアップする

マイグレーションは一方向です。新しいバージョンが適用したスキーマ変更を古いバージョンが認識できない場合があります。ロールバックできるよう、バージョンアップ前に必ずバックアップしてください。

マイグレーションが安全に復旧できない状態で中断した場合、プログラムは起動を拒否し、理由を表示します。破損したスキーマで動作を続けません。この場合はバックアップからの復元が最短です。

バックアップ§

データベースだけのバックアップでは不十分です

データベースには暗号化キーが同じインスタンス由来である必要があります。自動生成されたキーを使用している場合、auth.keyとencryption.keyはいずれもデータディレクトリにあります。環境変数またはシークレット管理サービスで明示的に設定している場合は、元の安全な保管元から別途バックアップしてください。このバージョンではマスターキーのローテーションをサポートしていません。

SQLite（公式 Compose のデフォルト構成）——まずサービスを停止し、既存コンテナから実際のボリューム名を取得して、データディレクトリ全体をアーカイブします。次のコマンドはdocker-compose.ymlがあるディレクトリで実行してください：

Compose を停止して実際のデータボリュームをバックアップする

docker compose stop gpt-load
container_id=$(docker compose ps -a -q gpt-load)
test -n "$container_id"
data_volume=$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/app/data"}}{{.Name}}{{end}}{{end}}' "$container_id")
test -n "$data_volume"
docker volume inspect "$data_volume" >/dev/null
backup_file="gpt-load-$(date +%F-%H%M%S).tar.gz"
docker run --rm --user 0:0 \
  --mount "type=volume,src=$data_volume,dst=/data,readonly" \
  --mount "type=bind,src=$PWD,dst=/backup" \
  alpine:3.24.1 sh -eu -c \
  'test -s /data/gpt-load.db; cd /data; tar -czf "/backup/$1" .' sh "$backup_file"
tar -tzf "$backup_file" | sed -n '1,20p'
docker compose start gpt-load

docker volume inspectとtest -sはいずれも成功し、アーカイブ一覧にgpt-load.dbが含まれている必要があります。Compose の論理ボリューム名gpt-load-dataをdocker run -vへ直接指定しないでください。実際のボリューム名は Compose プロジェクト名によって変わります。

外部データベース——データベース固有のツールでバックアップし、現在のインスタンスの安全な保管元から対応するAUTH_KEYとENCRYPTION_KEYをバックアップします：

データベース固有のバックアップツールを使用する

mysqldump -h db.example -u user -p gpt_load > gpt_load.sql
# または
pg_dump -h db.example -U user gpt_load > gpt_load.sql

バックアップファイルには復号可能な認証情報自体が含まれています。機密データとして暗号化保存し、公開クラウドストレージやリポジトリへ置かないでください。

復元§

復元ではデータベース、暗号化キー、アプリケーションのバージョンを一致させることが重要です。すでにデータが存在するディレクトリやボリュームへバックアップを直接上書きしないでください。

復元先のサービスを停止し、まず現在のデータをバックアップする
アーカイブを検証し、新しい空のディレクトリまたは空のボリュームへ復元する
データベースに対応するENCRYPTION_KEYを復元する。明示的に設定したキーは元の安全な保管元から復元する
初回起動にはバックアップと同じ GPT-Load バージョンを使用し、同時にアップグレードしない
ヘルス状態を確認し、管理画面へログインしてチャネルの認証情報を正常に復号できることを確認する

バックアップは復元できることを確認して初めて有効です。障害時に不完全だと判明しないよう、非本番環境で実際に手順をテストしてください。

データベースドライバーの変更§

自動データ移行ツールはありません。ドライバーの変更は新しいデータベースへの切り替えとなり、設定を再入力する必要があります。

設定量が多い場合はしばらく並行運用する。新しいデータベースへ接続するインスタンスを起動し、設定と検証後にトラフィックを切り替えます。1.xからの移行と同じ方法です。

ドライバー変更後もencryption.keyは変更しないでください。以前のバックアップと同じ暗号化方式を維持するには、既存のキーを使います。完全な新規構成で新しいキーを使う場合は、バックアップも更新してください。