SnapOtter/apps/docs/ja/guide/database.md

description, i18n_source_hash, i18n_provenance, i18n_output_hash, i18n_hash_version

description	i18n_source_hash	i18n_provenance	i18n_output_hash	i18n_hash_version
SnapOtter の PostgreSQL データベーススキーマ、テーブル、マイグレーション、バックアップ手順。	a68264552836	machine	f5d73e5b3f07	2

データベース

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

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

{#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

このデータベース ダンプには、/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 に残していることがよくあります。