メインコンテンツまでスキップ

SQLite ストレージ

NeoTavern はすべての構造化データを単一の SQLite データベースに保存します。厳格なプラグマ、STRICT テーブル、FTS5 検索、バージョン管理されたマイグレーションを備えています。

データベース設定​

接続は次の設定で開かれます:

  • foreign_keys = ON — 参照整合性が強制されます。
  • WAL ジャーナルモード — リーダーがライターによってブロックされることはありません。
  • busy_timeout — 同時ライターは即座に失敗する代わりに待機します。
  • synchronous = NORMAL — WAL セーフなパフォーマンスで耐久性を実現します。
  • プリペアドステートメント — すべてのクエリは Drizzle のプリペアドステートメントを通ります。生の SQL 文字列補間はありません。
  • 可能な場所では STRICT テーブル — SQLite が列型を強制します。
  • FTS5 — キャラクター、チャット、メッセージの全文検索。

安定した ID​

すべてのエンティティは安定した文字列 ID を持ち、できれば UUIDv7 です。ID が配列インデックスになることはありません。ゴミ箱が必要な場所では、行は削除される代わりに deleted_at でソフト削除されます。

スキーマ概要​

メインテーブルはライブラリとランタイム状態をカバーします: キャラクター、ペルソナ、チャット、ブランチ、メッセージとメッセージバリアント、タグ、ロアブックとロアエントリ、プリセット、プロバイダー構成とシークレット、設定とケイパビリティ付与を持つプラグインレジストリ、テーマレジストリ、プロンプトコンテキスト監査、インポートジョブとアーティファクト、キャッシュメタデータ。

プラグイン作者にとって重要な 2 つのパターンがあります:

  • plugin_state はプラグイン所有の状態をインストールレジストリとは別に保存し、データ形式用の schema_version と compare-and-swap 用の revision を持ちます。
  • provider_secrets は API キーを書き込み専用の値として保存します: マスクされたプレビューだけがリポジトリを離れることができます。

FTS5 検索​

仮想テーブル characters_fts、chats_fts、messages_fts が検索を支え、unicode61 と remove_diacritics で構築されています。INSERT/UPDATE/DELETE のトリガーがそれらをトランザクション的に同期させます。検索はプレフィックス語（token*）、タグフィルター、bm25 関連度ランキングをサポートします。完全再構築は POST /api/v2/search/rebuild で利用できます。

マイグレーション​

すべてのスキーマ変更はマイグレーションとして出荷されます:

  • マイグレーションはバージョン管理され、冪等です — IF NOT EXISTS と厳格なバージョンで再実行が安全です。
  • マイグレーションはトランザクション的に実行されます。失敗したマイグレーションは全体がロールバックされます。
  • 自動の down マイグレーションはありません。ロールバックはマイグレーション前のバックアップの復元を意味し、ランナーは危険なマイグレーションの前に、データが入ったデータベースに対して自動的にバックアップを作成します。
  • データの読み取りが隠れた破壊的変更を引き起こすことはありません。

マイグレーションランナーの安全バックアップの仕組みはバックアップ を参照してください。

プラグインの分離​

プラグインは直接の SQLite 接続を決して受け取りません。すべての永続化はプラグイン SDK のストレージ API を通じて行われ、それらはプラグインに代わって plugin_storage と plugin_state テーブルを所有します。これによりプラグインデータはバージョン管理され、取り消し可能で、生の SQL 事故から安全です。ストレージ API はプラグイン SDK を参照してください。

データベースに決して入れないもの​

  • 画像と音声はメインのデータベースの BLOB ではなくディスクに保存されます。ファイルと画像 を参照してください。
  • 未知のキャラクターカードフィールドと拡張機能メタデータは ext 列に保持され、エクスポートとインポートを生き延びます。