データベース

SnapOtter はデータの永続化に PostgreSQL 17 と Drizzle ORM（pg-core / node-postgres）を使用します。スキーマは apps/api/src/db/schema.ts で定義されています。

接続は DATABASE_URL 環境変数（デフォルト postgres://snapotter:snapotter@postgres:5432/snapotter）で設定します。Docker Compose では、Postgres コンテナが SnapOtter-pgdata という名前付きボリュームにデータを保存します。 リクエストは、後述の 最小権限ロール で説明するとおり、行の読み取りと書き込みしかできないロールで処理されます。

テーブル

users

ユーザーアカウントを保存します。初回起動時に DEFAULT_USERNAME と DEFAULT_PASSWORD から自動的に作成されます。

カラム	型	備考
id	uuid	主キー
username	varchar	一意、必須
passwordHash	varchar	scrypt ハッシュ
role	varchar	admin、editor、または user
mustChangePassword	boolean	パスワードの強制リセットフラグ
createdAt	timestamp	作成日時
updatedAt	timestamp	最終更新日時

sessions

アクティブなログインセッション。各行はセッショントークンをユーザーに紐付けます。

カラム	型	備考
id	varchar	主キー（セッショントークン）
userId	uuid	users.id への外部キー
expiresAt	timestamp	有効期限
createdAt	timestamp	作成日時

teams

ユーザーを整理するためのグループ。管理者はユーザーをチームに割り当てられます。

カラム	型	説明
id	uuid	主キー
name	varchar（一意、最大 50 文字）	チーム名
createdAt	timestamp	作成日時

api_keys

プログラムからのアクセス用の API キー。生のキーは作成時に一度だけ表示され、保存されるのはハッシュのみです。

カラム	型	備考
id	uuid	主キー
userId	uuid	users.id への外部キー
keyHash	varchar	キーの scrypt ハッシュ
name	varchar	ユーザーが指定したラベル
createdAt	timestamp	作成日時
lastUsedAt	timestamp	認証済みリクエストごとに更新

キーは si_ を接頭辞とし、その後に 96 桁の 16 進数（48 バイトのランダム値）が続きます。

pipelines

ユーザーが UI で作成する、保存されたツールチェーン。

カラム	型	備考
id	uuid	主キー
name	varchar	パイプライン名
description	varchar	任意の説明
steps	jsonb	{ toolId, settings } オブジェクトの配列
createdAt	timestamp	作成日時

user_files

永続的なファイルライブラリ。保存された編集は、デフォルトでは独立したルート行として挿入され（「新規として保存」: version 1、parentId null なので元のファイルは一覧に残ります）、元のファイルを上書きした場合は親にリンクされたバージョンとして挿入されます（parentId が設定され、version が増加し、元のファイルを置き換えます）。toolChain カラムには適用されたツールが記録されます。

カラム	型	説明
id	uuid	主キー
userId	uuid	users への FK（CASCADE DELETE）
originalName	varchar	アップロード時の元のファイル名
storedName	varchar	ディスク上のファイル名
mimeType	varchar	MIME タイプ
size	integer	ファイルサイズ（バイト）
width	integer	画像の幅（ピクセル）
height	integer	画像の高さ（ピクセル）
version	integer	バージョン番号（1 = オリジナル）
parentId	uuid または null	user_files への FK（親バージョン）
toolChain	jsonb	このバージョンを生成するために順に適用されたツール ID
createdAt	timestamp	作成日時

jobs

進捗報告とクリーンアップのために処理ジョブを追跡します。

カラム	型	備考
id	uuid	主キー
type	varchar	ツールまたはパイプラインの識別子
status	varchar	queued、processing、completed、または failed
progress	real	0.0〜1.0 の割合
inputFiles	jsonb	入力ファイルパスの配列
outputPath	varchar	結果ファイルへのパス
settings	jsonb	使用されたツール設定
error	varchar	失敗した場合のエラーメッセージ
createdAt	timestamp	作成日時
completedAt	timestamp	完了日時

settings

管理者が UI から変更できる、サーバー全体の設定のためのキーバリューストア。

カラム	型	備考
key	varchar	主キー
value	varchar	設定値
updatedAt	timestamp	最終更新日時

roles

きめ細かな権限を持つカスタムロール。

カラム	型	備考
id	uuid	主キー
name	varchar	一意のロール名
description	varchar	任意の説明
permissions	jsonb	権限文字列の配列
createdAt	timestamp	作成日時

audit_log

セキュリティに関わるアクションのログ。

カラム	型	備考
id	uuid	主キー
userId	uuid	users への FK
action	varchar	アクションの種類
details	jsonb	アクション固有のデータ
createdAt	timestamp	アクション日時

user_preferences

ユーザーごとの UI 状態を、設定名をキーとして保持します。ホームページのピン留めしたツールは PUT /api/v1/preferences 経由でここに書き込まれます。

カラム	型	備考
userId	text	users への FK、削除時にカスケード。key と合わせて主キー
key	text	設定の名前。userId と合わせて主キー
value	jsonb	設定の内容
updatedAt	timestamp	最終書き込み日時

マイグレーション

Drizzle がスキーマのマイグレーションを処理します。マイグレーションファイルは apps/api/drizzle/ にあります。開発中は次のとおりです。

cd apps/api
npx drizzle-kit generate   # generate a migration from schema changes
npx drizzle-kit migrate    # apply pending migrations

本番環境では、保留中のマイグレーションが起動時に自動的に適用されます。

最小権限ロール

2 つのロールに、2 つの役割。DATABASE_URL はリクエストを処理するためのもので、アプリのテーブルに対する SELECT、INSERT、UPDATE、DELETE、およびそれらのシーケンスに対する USAGE と SELECT を持ちます。権限はこれがすべてです。テーブルの作成や削除、拡張機能のインストール、TRUNCATE、pg_authid の読み取り、データベースの作成、ロールの変更はできず、マイグレーション履歴が置かれている drizzle スキーマに触れることもできません。

特権を持つのは DATABASE_MIGRATION_URL の方です。起動中にマイグレーションを実行してランタイムロールに権限を付与し、リクエストを 1 件も処理しないうちに接続を閉じます。

Compose とオールインワンイメージは、既存のインストールも含めてすでにこの構成になっています。SnapOtter は起動時に、ランタイムロールがなければ作成して権限を付与し、マイグレーションを実行したうえで、以前から存在していたテーブルにも権限を行き渡らせます。アップグレードのために手作業で SQL を実行する必要はありません。

DATABASE_MIGRATION_URL を空のままにすると単一ロールで動作し、分割前とまったく同じように DATABASE_URL が両方の役割を担います。これは非推奨ではなく、サポートされた構成です。ロールの作成が自分の裁量では行えないことも多いマネージド Postgres では、こちらが適切な選択です。

外部およびマネージドの Postgres

RDS、Supabase、Cloud SQL、あるいは自分で運用しているクラスタでは、この分割はオプトインです。ランタイムロールを一度だけ作成します。

CREATE ROLE snapotter_app LOGIN PASSWORD 'choose-a-strong-password'
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOBYPASSRLS;

そのうえで、同じホスト、ポート、データベースを指す 2 つの接続文字列を SnapOtter に渡します。

DATABASE_URL=postgres://snapotter_app:[email protected]:5432/snapotter
DATABASE_MIGRATION_URL=postgres://snapotter:[email protected]:5432/snapotter

作業はここまでです。権限の付与は SnapOtter 自身が行い、マイグレーションのたびに付与し直すため、将来のリリースで追加されるテーブルについても、誰かが SQL を実行しなくてもカバーされます。

DATABASE_MIGRATION_URL に指定するロールは、SnapOtter のテーブルを所有している必要があります。テーブルに対して権限を付与できるのは、その所有者だけだからです。既存のインストールでは、そのために新しく作ったロールではなく、これまで SnapOtter を動かしてきたロールがこれに当たります。何も所有していない新規ロールを指定すると、まさにその旨を伝えるエラーで起動に失敗します。さらに、ランタイムロールを作成して維持するための CREATEROLE と、drizzle スキーマを作成する権限も必要です。

両方の URL に同じロールを指定すると分割は無効になり、SnapOtter はそれを取り繕わずログに記録します。テーブルを所有しつつ CREATEROLE も持てるロールがプロバイダ側で用意できない場合は、単一ロールで運用してください。

スーパーユーザー属性をそのままにしている理由

SnapOtter がロールから SUPERUSER を独自に外すことはありません。分割より前に作成されたインストールでは snapotter がクラスタで唯一のスーパーユーザーであり、これを降格させるとクラスタにスーパーユーザーが 1 つも残らず、サーバーを停止したうえでのシングルユーザーモードでしか復旧できなくなります。代わりに、長時間維持される接続を制限付きのロールへ移すことで保護を得ています。スーパーユーザーが接続に現れるのは起動時の数秒間だけで、あとは姿を消します。

新規のオールインワンインストールでは、この問題は起きません。ロールは 3 つ用意されます。postgres（ブートストラップ用のスーパーユーザーで、SnapOtter が使うどの接続文字列にも登場しません）、snapotter（NOSUPERUSER。データを所有し、接続するのは起動時だけです）、snapotter_app（行だけを扱い、リクエストを処理します）です。

それでも古い snapotter を降格させたい場合は、先に 2 つ目のスーパーユーザーを作成し、そのロールでログインできることを確認してください。そのうえで ALTER ROLE snapotter NOSUPERUSER を実行します。

{#backup-and-restore} のバックアップと復元

リレーショナル データベースは、アプリの /data ボリュームではなく、Postgres コンテナーの SnapOtter-pgdata ボリュームに存在します。

検証付きの論理バックアップ (推奨)

# Dump into PostgreSQL's portable custom archive format
docker exec SnapOtter-postgres \
  pg_dump --format=custom --no-owner -U snapotter snapotter > snapotter.dump
test -s snapotter.dump
docker exec -i SnapOtter-postgres pg_restore --list < snapotter.dump >/dev/null

# Restore into a fresh/disposable target first and fail on the first SQL error
docker exec -i SnapOtter-postgres \
  pg_restore --exit-on-error --clean --if-exists --no-owner \
  -U snapotter -d snapotter < snapotter.dump

どちらのコマンドも所有者である snapotter として接続しており、今後もそのままにしてください。ランタイムロールからは drizzle スキーマが見えないため、そのロールで取得したダンプは不完全になります。--no-owner を指定すると、リストアされたオブジェクトの所有者はリストアを実行した人になるので、所有者として実行すれば権限設定が前提とする所有関係どおりになります。新しいクラスタでは 1 つ注意点があります。pg_dump は権限の設定を含めますが、そこで名指しされているロールまでは含めません。そのため、リストアの前に snapotter_app を作成しておかないと、--exit-on-error によって最初の GRANT で停止します。いずれにせよ、SnapOtter は次回の起動時に権限を付与し直します。

このデータベース ダンプには、/data/files で保存されたライブラリ オブジェクトや、Redis の永続的な BullMQ 状態は含まれません。 セキュリティと強化 の連携手順でバックアップと復元を行ってください。

コールド ボリューム スナップショット

# Stop every service first, then use your storage platform to snapshot the
# PostgreSQL, app-data, and Redis volumes as one crash-consistent set.
docker compose -f docker/docker-compose.yml stop

tar を使用してライブ PostgreSQL データ ディレクトリをコピーしないでください。ボリューム名はプロジェクトごとにプレフィックスを作成するため、リテラル ラベル SnapOtter-pgdata を想定するのではなく、docker inspect またはストレージ プラットフォームからマウントされたボリューム ID を解決します。

1.x（SQLite）からの移行

SnapOtter 1.x からのアップグレードには専用のガイドがあります。1.x から 2.0 へのアップグレード を参照してください。要点としては、既存の /data ボリュームを再利用すれば、2.0 が初回起動時に /data/snapotter.db を自動検出してインポートします（または SQLITE_MIGRATE_PATH を設定して明示的に指定します）。まず snapotter.db だけでなく /data ボリューム全体をバックアップしてください。1.x は SQLite の WAL モードを使うため、停止したコンテナはデータの大半を、ほぼ空の snapotter.db のそばにある snapotter.db-wal に残していることがよくあります。