database-operation

データベース操作

すべてのスクリプトパスは、このスキルファイルからの相対パスです。

データベースへのアクセスには、scripts/mp-db.py を使用してください。プロンプトからデータベースのパスワード、API トークン、または PostgreSQL の完全な DSN を取り出さないでください。このスクリプトは MoviePilot のローカル設定を読み取り、内部で SQLite または PostgreSQL に接続します。

範囲と境界

このスキルは、SQL を直接実行するための境界です。Python スクリプトとして実装されており、エージェントがレコードの確認、データ統計の実行、スタック状態の修復、または明示的に依頼されたデータベースの更新を行う必要がある場合に適しています。

MoviePilot のプログラムディレクトリから、プロジェクトのランタイムを使って同梱のコピーを実行してください。たとえば、次のようにします。

cd <MOVIEPILOT_ROOT>
python skills/database-operation/scripts/mp-db.py tables

エージェントのコマンド環境では、利用可能な場合は python がプロジェクト固有の moviepilot-python エントリにルーティングされ、そうでない場合はプロジェクトまたは Docker の VENV_PATH にある Python が使用されます。

ランタイムは、コピーされたスキル用に MOVIEPILOT_ROOT を設定します。<CONFIG_PATH>/agent/skills/ からコピーしたスクリプトを直接実行する場合は、先にこの変数をプログラムディレクトリに設定してください。設定しないと、ヘルパーが移動方法を通知します。システムの python3 ではなく、プロジェクトのランタイムを使用してください。

より安全な製品機能を優先してください。

リクエスト	優先するスキル
通常の MoviePilot 製品操作	moviepilot-api の構造化操作
構造化 API カタログにない操作	より具体的なスキル、または未対応であることを明示した結果
スラッシュコマンドまたはプラグイン／システムコマンドのディスパッチ	command-dispatch
手動でのファイル整理	organize-files
失敗した転送履歴レコードの再試行	transfer-failed-retry

データへのアクセスや変更を行う際の最終手段として、このスキルを使用してください。同梱のスクリプトを通じて SELECT、INSERT、UPDATE、DELETE、およびスキーマ変更ステートメントを実行できますが、広範囲または破壊的な書き込みには、引き続きユーザーの明示的な許可が必要です。

システム設定には管理対象のソースが 2 つあり、通常はここで編集しないでください。

• ランタイムの Settings 変数は、moviepilot-api の config.system.get／config.system.update 操作で照会および更新します。更新時には型変換が行われ、app.env に保存されます。
• SystemConfigKey の値は、データベースの systemconfig テーブルに保存されます。ただし、登録済みキーの検証、プラグインによる変更の可否判定、値の正規化、シークレットのマスキング、設定変更イベントの発行が行われるため、同じ API 操作を優先してください。

管理 API では操作を完了できず、修復が明示的に許可されている場合に限り、systemconfig に対する直接 SQL を使用してください。スクリプトは --show-secrets を指定するまで、systemconfig を参照するすべてのステートメントをブロックします。そのため、まず対象の行を正確に確認し、広範囲の書き込みを避け、修復した値を管理 API から読み取れることを検証してください。

コマンド

テーブル一覧を表示します。

python scripts/mp-db.py tables

テーブルスキーマを表示します。

python scripts/mp-db.py schema downloadhistory

読み取りクエリを実行します。

python scripts/mp-db.py query "SELECT COUNT(*) AS total FROM downloadhistory"

標準入力またはファイルから SQL を読み取ります。

python scripts/mp-db.py query --file /path/to/query.sql

書き込みステートメントを実行します。

python scripts/mp-db.py write "UPDATE subscribe SET state = 'S' WHERE id = 123"

互換性のため query --write もサポートされていますが、INSERT、UPDATE、DELETE、およびスキーマ変更には write サブコマンドを優先してください。

SQLite は、各ステートメントの実行中に、シングルクォートで囲まれたテーブル名やビュー経由の読み取りも含め、実際のテーブルアクセスを確認します。一時的なオーソライザーは、ステートメントの終了時に削除されます。PostgreSQL では、以下で説明する識別子のチェックが引き続き行われます。

読み取りモードと書き込みモードのどちらでも、systemconfig を参照するステートメントは --show-secrets を追加するまで拒否されます。

python scripts/mp-db.py query "SELECT key, value FROM systemconfig WHERE key = 'TMDB_API_KEY'" --show-secrets

この制限は列単位ではなくテーブル単位で適用されるため、systemconfig に対する件数の確認やキーの一覧表示にもフラグが必要です。通常の設定は、シークレットがマスキングされる moviepilot-api の config.system.get から読み取ってください。このフラグは、修復が明示的に許可されている場合に限り指定してください。

ワークフロー

1. 通常の製品ワークフローでは、既存の MoviePilot ツールまたは API を優先してください。
2. 依頼に対応する既存のツールがない場合に限り、このスキルを使用してデータベースを直接調査してください。
3. スキーマが不明な場合は、まず tables を実行し、次に schema <table> を実行してください。
4. SELECT クエリは、行を読み取る際に対象を絞った射影と明示的な LIMIT を指定して、そのまま実行してください。
5. INSERT、UPDATE、DELETE、DROP、ALTER、TRUNCATE、CREATE、または REPLACE には write を使用し、影響を受けた行数を報告してください。

組み込みの安全対策

• query はデフォルトで読み取り専用モードです。
• write はデータ更新とスキーマ変更を伴うステートメントを直接実行します。
• query --write は、書き込みステートメントの互換性エイリアスとして引き続き使用できます。
• 1 回の呼び出しで複数の SQL ステートメントを実行することはできません。
• SQL リテラル、引用符で囲まれた識別子、コメント内のキーワードやセミコロンによって、クエリが書き込みや複数ステートメントの要求として扱われることはありません。閉じられていない構文要素は無効です。
• LIMIT が指定されていない場合、通常の SELECT クエリにはデフォルトで LIMIT 100 が適用されます。
• systemconfig はインスタンスレベルのすべての API キー、Cookie、パスワードを集約するため、--show-secrets を指定するまで読み取りも書き込みもできません。引用符で囲まれた識別子とスキーマ修飾名も認識されるため、テーブルに別名を付けてもこの制限は回避できません。
• その他のテーブルには制限はありません。site とプラグインのデータにはサイトごとの認証情報が保存されているため、行全体を選択するのではなく、対象を絞った射影を使用してください。
• 結果は保存されているとおりに返されます。必要に応じてエージェントが内部で機密情報を使用することはできますが、ユーザーがその値の確認を明示的に求めない限り、最終的なユーザー向けの応答に秘密情報を含めてはいけません。

安全規則

1. ユーザーが対象の変更をすでに明確に許可していない場合、破壊的な操作や広範囲に及ぶ書き込み操作を行う前に確認してください。
2. DELETE、DROP、TRUNCATE などの破壊的な操作の前に、バックアップを提案してください。
3. ユーザーがすべての行への影響を明示的に意図している場合を除き、WHERE 句なしで UPDATE や DELETE を実行してはいけません。
4. ツールの出力には、生の秘密情報、Cookie、パスキー、ハッシュ化されたパスワード、OTP シークレット、API キー、トークンが含まれる場合があります。これらは依頼された操作にのみ使用し、明示的に求められない限り、最終応答で繰り返さないでください。別の手段ですでに報告できる値を検索する範囲を広げるために、--show-secrets を追加してはいけません。
5. 出力は最小限にしてください。大量の結果はそのまま出力せず、要約してください。

コアテーブル

tables は、現在のインスタンスに存在するテーブルを返します。以下のカタログには、すべての MoviePilot ORM テーブルと Alembic メタデータが含まれています。常に、実行中の schema <table> の結果を正式な情報として扱ってください。

agentchat

• 目的：Web エージェントおよびメッセージングチャネルのセッションインデックス、タイトル、プレビュー、メッセージスナップショットを保存します。
• 便利なクエリ：ユーザー、セッション、更新時刻を基に、エージェントの履歴やコンテキストの復元を追跡します。
• 書き込みの境界：エージェント会話サービスが管理しています。メッセージ JSON、カウンター、所有権を書き換えてはいけません。
• 列：id、session_id、client_session_id、user_id、username、channel、source、original_chat_id、title、preview、agent_messages、display_messages、message_count、created_at、updated_at

agentinvocation

• 目的：永続的なエージェント書き込み呼び出しの識別情報と、確認済みの非同期送信を含む最後に観測された結果を記録します。
• 便利なクエリ：特定のプリンシパルとセッションについて、実行中、不明、保留中、成功、失敗のレシートを確認します。中断された書き込みを診断する際は、タイムスタンプを比較します。
• 書き込み境界：ホストのアトミックな要求取得と調整処理が管理します。重複防止を回避するために、ID、フィンガープリント、要求トークン、ステータスを変更しないでください。実行中および不明のレコードは復旧状態であり、通常の保持処理では削除されません。保留中は送信が確認されたことを意味し、外部タスクの完了を意味するものではありません。生の引数とツールの出力はここには保存されません。
• 列：id、principal_id、session_id、invocation_id、tool_name、arguments_digest、claim_token、status、summary、created_at、updated_at

agenttask

• 目的：単発または定期的なエージェントタスクの定義、トリガー、最新の実行概要を保存します。
• 便利なクエリ：タスクの所有者、有効化の状態、cron／run_at の設定、最新の結果を確認します。
• 書き込み境界：エージェントタスク API を通じて、タスクの作成、更新、有効化、無効化、削除を行います。
• 列：id、name、content、trigger_type、cron_expression、run_at、enabled、user_id、username、session_id、channel、source、original_chat_id、last_status、last_run_at、last_result、last_run_id、run_count、created_at、updated_at

agenttaskrun

• 目的：各エージェントタスク実行の入力スナップショット、ステータス、タイムスタンプ、結果を保存します。
• 便利なクエリ：1回の実行を監査したり、task_id、run_id、トリガーソースを使って失敗を関連付けたりします。
• 書き込み境界：実行の証跡はタスクランナーが管理します。レコードを捏造したり、実行ステータスを編集したりしないでください。
• 列：id、run_id、task_id、trigger_source、name、content、trigger_type、cron_expression、run_at、user_id、username、session_id、channel、message_source、original_chat_id、status、started_at、finished_at、result

alembic_version

• 目的：データベースに現在適用されている Alembic マイグレーションのリビジョンを記録します。
• 便利なクエリ：起動時のマイグレーション失敗や、データベースとコードのリビジョン不一致を診断します。
• 書き込み境界：直接編集しないでください。リビジョンの適用またはロールバックは、Alembic を通じてのみ行います。
• 列：version_num

downloadfailure

• 目的：失敗したダウンロードの安定したフィンガープリント、メディア／トレントのコンテキスト、エラー、再試行スケジュールを保存します。
• 便利なクエリ：失敗の原因、再試行回数、次回の再試行時刻、影響を受けるメディアやサイトを分析します。
• 書き込み境界：ダウンロード失敗時の補償処理が管理します。レコードの再試行やクリーンアップは、業務 API を通じて行います。
• 列：id、fingerprint、type、title、year、media_source、media_id、seasons、episodes、site、site_name、torrent_id、torrent_name、torrent_size、downloader、source、error_message、retry_count、first_failed_at、last_failed_at、next_retry_at

downloadfiles

• 目的：ダウンローダーのタスクハッシュを、フルパス、保存ディレクトリ、相対ファイル、稼働状態に関連付けます。
• 便利なクエリ：downloader／download_hash でタスクファイルを検索したり、保存パスの関連付けを診断したりします。
• 書き込み境界：ダウンロードと転送のフローが管理します。状態やパスの関連付けを手動で変更しないでください。
• 列：id、downloader、download_hash、fullpath、savepath、filepath、torrentname、state

downloadhistory

• 目的：送信されたダウンロードに関するメディアの識別情報、トレント、ダウンローダー、ユーザー、認識コンテキストを保存します。
• 便利なクエリ：ダウンロード履歴の確認や、メディアの識別情報またはハッシュをその出所まで追跡する際に役立ちます。
• 書き込み境界：ダウンロードのユースケースによって書き込まれます。レコードの削除や修正には、ダウンロード履歴 API を使用してください。
• 列：id、path、type、title、year、media_source、media_id、music_type、seasons、episodes、image、poster、downloader、download_hash、torrent_name、torrent_description、torrent_site、userid、username、channel、date、note、media_category_id、media_category、classification_rule_id、classification_policy_revision、classification_source、episode_group、custom_words

mediaserveritem

• 目的：メディアサーバーのライブラリから投影されたローカルインデックスと正規のメディア識別情報を保存します。
• 便利なクエリ：ライブラリへの登録状況、サーバー／ライブラリ／パスの配置、シーズン情報の確認に役立ちます。
• 書き込み境界：再構築可能な投影データです。書き込みとクリーンアップは、メディアサーバーとの同期処理に委ねてください。
• 列：id、server、library、item_id、item_type、title、original_title、year、media_source、media_id、path、seasoninfo、note、lst_mod_date

message

• 目的：受信メッセージと送信メッセージ、チャンネル、コンテンツ、添付ファイル、ユーザー、タイムスタンプを保存します。
• 便利なクエリ：通知履歴のページング、送受信方向の判別、出所に基づく重複の追跡に役立ちます。
• 書き込み境界：メッセージングサービスと通知サービスによって書き込まれます。メッセージ API または保持ジョブを使ってクリーンアップしてください。
• 列：id、channel、source、mtype、title、text、image、poster、link、userid、reg_time、action、note

outboxmessage

• 目的：ビジネストランザクションとアトミックにコミットされる、外部から確認可能な副作用の意図を保存します。
• 便利なクエリ：保留中／処理中／失敗の状態、リース、試行回数、直近のエラーの診断に役立ちます。
• 書き込み境界：Outbox Dispatcher の状態機械が所有します。未配信イベントを手動で完了扱いにしたり、削除したりしないでください。
• 列：id、event_key、topic、payload_version、payload、status、attempt、next_retry_at、lease_until、last_error、created_at、completed_at

passkey

• 目的：WebAuthn／PassKey の認証情報、公開鍵、署名カウンター、有効化状態を保存します。
• 便利なクエリ：所有者、有効化、最終使用日時など、許可された認証診断に役立ちます。
• 書き込み境界：セキュリティ上重要なデータです。PassKey API 経由でのみ管理し、認証情報の内容は決して開示しないでください。
• 列：id、user_id、credential_id、public_key、sign_count、name、aaguid、created_at、last_used_at、is_active、transports

plugindata

• 目的：plugin_id とキーごとに分離された、プラグイン所有の JSON 値を保存します。
• 便利なクエリ：明示的に指定された 1 つのプラグインとキーに関する永続化や移行の問題の診断に役立ちます。
• 書き込み境界：これらの値はプラグインが所有します。プラグインの機能またはプラグインデータ API の利用を優先してください。
• 列：id、plugin_id、key、value

pluginidentity

• 目的：物理プラグインパッケージの信頼済みソース、ペイロードソース、バージョン、受領情報、CAS リビジョンを保存します。
• 便利なクエリ：ソースの紐付け、パッケージの世代、ペイロードの適用、識別情報の競合の監査に役立ちます。
• 書き込み境界：プラグインのサプライチェーン状態です。インストールおよび更新トランザクションのみが所有します。
• 列：id、plugin_id、normalized_plugin_id、trusted_source_type、trusted_source_key、binding_basis、payload_source_type、payload_source_key、declared_version、package_generation、declared_metadata、payload_receipt、revision、created_at、updated_at、bound_at、payload_applied_at

plugininstallation

• 目的：プラグインのインストール段階、メンバーシップの対象、ID のリビジョン、バックアップ状態を保存します。
• 便利なクエリ：中断されたインストール、ロールバック条件、パッケージやバックアップの有無を診断します。
• 書き込み境界：プラグインのインストール状態マシンが管理します。段階を進めたり、証跡を手動で上書きしたりしないでください。
• カラム：id、transaction_id、plugin_id、phase、membership_before、host_enabled_before、membership_target、identity_before_revision、identity_target_revision、package_existed、persistent_backup_existed、created_at、updated_at、schema_version

plugininstance

• 目的：共有ソースのプラグインランタイムインスタンスごとに 1 行を保存します。クローンとホストプラグイン自体の両方が対象です（instance_id は source_plugin_id と等しく、等しい場合はホスト、異なる場合はクローンを示します）。各インスタンスの表示設定の上書き、そのインスタンス固有のログレベルの上書きと有効期限、およびプラグイン固有の構成ペイロードも保存します。クローンは、その行が存在する間だけ存在します。そのため、行を削除するとクローンがアンインストールされ、構成も破棄されます。
• 便利なクエリ：クローンの名前や所有者の診断、プラグインまたはそのクローンの構成の確認、現在グローバルログレベルを上書きしているインスタンスとその期限の特定に使います。
• 書き込み境界：プラグインインスタンス、プラグイン構成、プラグインのログレベル API が管理します。行を直接編集しないでください。
• カラム：id、instance_id、source_plugin_id、plugin_name、plugin_desc、plugin_icon、is_default_target、is_enabled、log_level、log_expires_at、config_data、created_at、updated_at

searchsession

• 目的：未完了の購読検索タスクについて、ページカーソルと保留中の候補を保存します。サイトの認証情報は含まず、タスクの終了時に削除され、更新がないまま 14 日が経過すると消去されます。
• 便利なクエリ：task_id、version、updated_at を使って、一時停止または再開されたページ分割検索を診断します。
• 書き込み境界：キュータスクのリース下で、バージョン CAS を使ってのみ書き込まれます。ペイロードを編集しないでください。ページのスキップや候補の再送信につながる可能性があります。
• カラム：id、task_id、version、payload、updated_at

site

• 目的：プライベートトラッカーの URL、RSS、認証情報、レート制限、プロキシ状態、ダウンローダーとの紐付けを保存します。
• 便利なクエリ：認証情報への露出を最小限に抑えながら、有効化の状態、ドメイン、レート制限、ダウンローダーとの紐付けを確認します。
• 書き込み境界：Cookie、API キー、トークンが含まれます。サイト API を通じて管理してください。
• カラム：id、name、domain、url、pri、rss、cookie、ua、apikey、token、proxy、filter、render、public、note、limit_interval、limit_count、limit_seconds、timeout、is_active、lst_mod_date、downloader

siteicon

• 目的：サイト名、ドメイン、アイコン URL、Base64 形式のアイコンデータをキャッシュします。
• 便利なクエリ：アイコンの欠落、ドメインの誤ったマッピング、キャッシュ生成を診断します。
• 書き込み境界：サイトアイコン同期が管理する再生成可能なキャッシュです。直接書き込むことは推奨されません。
• カラム：id、name、domain、url、base64

sitestatistic

• 目的：サイトへのリクエストの成功、失敗、所要時間、最新の状態、診断メモを集計します。
• 便利なクエリ：サイトの可用性、失敗率、直近のアクセス状態を比較します。
• 書き込み境界：サイトアクセス統計によって蓄積されます。実行時の動作を隠すためにカウンターを編集しないでください。
• カラム：id、domain、success、fail、seconds、lst_state、lst_mod_date、note

siteuserdata

• 目的：トラッカーアカウントのレベル、トラフィック、比率、シード状況、未読メッセージのデータを保存します。
• 便利なクエリ：アカウントの状態、トラフィックの傾向、シード量、最新の収集エラーの確認に役立ちます。
• 書き込み範囲：同期によって更新されるサイトスクレイピングの投影データです。直接編集しないでください。
• 列：id、domain、name、username、userid、user_level、join_at、bonus、upload、download、ratio、seeding、leeching、seeding_size、leeching_size、seeding_info、message_unread、message_unread_contents、err_msg、updated_day、updated_time

subscribe

• 目的：有効な映画、テレビ番組、音楽のサブスクリプション、フィルター、進捗状況、ダウンロード先を保存します。
• 便利なクエリ：状態、不足しているエピソードやトラック、品質ルール、サイトの対象範囲、マッチングの進捗状況の確認に役立ちます。
• 書き込み範囲：状態機械の一貫性を保つため、サブスクリプション API を通じて作成、更新、検索、削除してください。
• 列：id、activity_key、identity_key、name、year、type、search_interval、keyword、media_source、media_id、music_type、total_tracks、downloaded_tracks、season、poster、backdrop、vote、description、filter、include、exclude、quality、resolution、effect、audio_quality、audio_format、min_bitrate、min_bit_depth、min_sample_rate、total_episode、start_episode、lack_episode、note、state、last_search、last_update、date、username、sites、downloader、best_version、best_version_full、current_priority、current_audio_format、current_bitrate、current_bit_depth、current_sample_rate、episode_priority、save_path、search_imdbid、manual_total_episode、custom_words、media_category_id、media_category、filter_groups、episode_group

subscribeactivity

• 目的：機能アップグレード後に記録される、構造化されたサブスクリプションのビジネスイベントと再開可能な検索ラウンドの進捗状況です。
• 便利なクエリ：認証済みのサブスクリプションアクティビティ API を通じて、イベントの概要、固定されたフィルタールール、安全なリソースの判断、再試行を確認できます。
• 書き込み範囲：サブスクリプションのトランザクションとアクティビティの監視によって管理されます。ランタイムログを解析してイベントを再構築したり、送信済みダウンロードの事実を直接変更したりしないでください。
• 列：id、activity_key、event_id、kind、source、status、started_at、finished_at、counts、details、tracking
• activity_key は、再利用された整数 ID とは独立して、元のサブスクリプションを完了済みの履歴に関連付けます。tracking には内部ハッシュ化重複排除キーが含まれ、API レスポンスからは除外されます。

subscribehistory

• 目的：完了またはアーカイブされたサブスクリプションのスナップショットと、最終的なフィルター状態を保存します。
• 便利なクエリ：過去のサブスクリプション、メディアの識別情報、完了条件、フィルター設定の監査に役立ちます。
• 書き込み範囲：サブスクリプションの完了とアーカイブによって生成されます。復元または削除は、ビジネス API を通じて行ってください。
• 列：id、activity_key、name、year、type、search_interval、keyword、media_source、media_id、music_type、total_tracks、season、poster、backdrop、vote、description、filter、include、exclude、quality、resolution、effect、audio_quality、audio_format、min_bitrate、min_bit_depth、min_sample_rate、total_episode、start_episode、date、username、sites、best_version、best_version_full、current_priority、current_audio_format、current_bitrate、current_bit_depth、current_sample_rate、episode_priority、save_path、search_imdbid、custom_words、media_category_id、media_category、classification_rule_id、classification_policy_revision、classification_source、filter_groups、episode_group

subscriptionsearchbatch

• 目的：永続的なサブスクリプション検索バッチ、検索元、集約状態、件数、キャンセル要求を保存します。
• 便利なクエリ：ユーザーに表示される検索の進捗、復旧状態、キャンセル、最終結果の確認。
• 書き込み境界：サブスクリプション検索オーケストレーションが所有します。バッチの作成とキャンセルにはサブスクリプション API を使用してください。
• 列：id、batch_id、source、state、priority、total_count、finished_count、failed_count、cancelled_count、skipped_count、cancel_requested、created_at、updated_at、started_at、finished_at、last_error

subscriptionsearchtask

• 目的：リースと実行フェーズを含む、バッチとサブスクリプションごとの永続的なサブスクリプション検索タスクを保存します。
• 便利なクエリ：キュー内、実行中、失敗、キャンセル済み、または復旧済みの処理と、現在のサイトの診断。
• 書き込み境界：検索キューのリース状態機械のみが更新します。リースや最終状態を手動で書き換えないでください。
• 列：id、task_id、batch_id、subscription_id、active_key、source、priority、position、state、phase、current_site_id、pending_site_ids、attempt_count、cancel_requested、lease_owner、lease_token、lease_expires_at、available_at、created_at、updated_at、started_at、finished_at、last_error

subscriptionsitebudget

• 目的：サイトごとのサブスクリプション検索の同時実行数、クールダウン、健全性、公平性の状態を保存します。
• 便利なクエリ：サイトへの負荷、クールダウンによる延期、最近の失敗、アクティブな検索の所有権の診断。
• 書き込み境界：サブスクリプションサイト予算コーディネーターが所有します。直接 SQL でクールダウンやカウンターをクリアしないでください。
• 列：id、site_id、lease_owner、lease_token、lease_expires_at、next_allowed_at、consecutive_failures、success_streak、last_outcome、last_error、updated_at

systemconfig

• 目的：SystemConfigKey をキーとする JSON 形式の業務設定値を保存します。
• 便利なクエリ：管理対象の設定 API の動作に予期しない問題がある場合に限り、物理値を確認します。
• 書き込み境界：まず config.system.get/update を使用してください。直接書き込むと、検証、イベント、プラグインの許可処理が迂回されます。
• 列：id、key、value

transferexecutionstep

• 目的：永続的な転送操作ごとの意図、試行の識別情報、状態、結果の証拠を保存します。
• 便利なクエリ：task_id または operation_id で、停止中、失敗、または繰り返されたステップを診断します。
• 書き込み境界：転送実行状態機械とリース CAS が所有します。状態遷移を手動で強制しないでください。
• 列：id、task_id、operation_id、checkpoint_fingerprint、ordinal、phase、kind、state、attempt_token、attempt_count、intent_version、intent_payload、result_version、result_payload、last_error、prepared_at、started_at、completed_at、updated_at

transferhistory

• 目的：転送元、転送先、モード、メディアの識別情報、ダウンロードとの関連付け、結果を保存します。
• 便利なクエリ：成功／失敗の履歴、転送先パス、メディア分類、ダウンロードとの関連付けの確認。
• 書き込み境界：転送の確定処理によって書き込まれます。削除や再試行には転送履歴の業務 API を使用してください。
• 列：id、transfer_task_id、transfer_settlement_revision、src、src_storage、src_fileitem、dest、dest_storage、dest_fileitem、mode、type、media_category_id、category、classification_rule_id、classification_policy_revision、classification_source、title、year、media_source、media_id、music_type、total_tracks、audio_format、audio_lossless、bit_depth、sample_rate、bitrate、seasons、episodes、image、downloader、download_hash、status、errmsg、retry_count、auto_paused、failure_stage、recovery_action、cleanup_status、cleanup_error、date、files、episode_group

transferpending

• 目的：保留保留中の転送入力、計画、チェックポイント、リース、再試行、および手動レビューの状態を永続的に保存します。
• 有用なクエリ：再起動後の復旧、期限切れのリース、retry_wait、終端失敗、または手動レビューの診断に使用します。
• 書き込み境界：中核となる永続状態マシンは、計画、実行、再試行、およびレビューサービスによってのみ進行します。
• 列：id、task_id、storage、src_path、created_at、state、updated_at、last_error、input_version、planning_input、input_fingerprint、checkpoint_version、checkpoint_payload、planned_at、lease_owner、lease_token、lease_expires_at、heartbeat_at、attempt_count、execution_state、execution_version、execution_payload、execution_fingerprint、retry_generation、retry_count、retry_due_at、retry_requested_by、retry_reason、settlement_revision、terminal_history_id、manual_review_revision、reviewed_at、reviewed_by、review_reason、review_decision

transfersettlementreceipt

• 目的：転送タスクごとに連続したリビジョン番号を持つ、不変の終端精算レシートを保存します。
• 有用なクエリ：履歴、保留中データの削除、および実行フィンガープリントが確実に精算されたことの検証に使用します。
• 書き込み境界：冪等性と監査証跡のため、リビジョンの追加のみを行い、古いレシートを上書きまたは削除しないでください。
• 列：id、task_id、history_id、settlement_revision、outcome、execution_fingerprint、lease_token、history_status、src、src_storage、pending_deleted、error、created_at、updated_at

user

• 目的：ユーザーアカウント、パスワードハッシュ、管理者状態、OTP、権限、および設定を保存します。
• 有用なクエリ：アカウントの状態、権限、または認証設定の、承認された診断に使用します。
• 書き込み境界：セキュリティ上重要なデータです。ユーザー、権限、パスワード、および二要素認証の API を通じて管理してください。
• 列：id、name、email、hashed_password、is_active、is_superuser、avatar、is_otp、otp_secret、permissions、settings、notification_identity

userconfig

• 目的：ユーザー名とキーによって分離された、ユーザーごとの JSON 設定を保存します。
• 有用なクエリ：UI 設定、メッセージのクリアカーソル、またはその他の個人設定の状態確認に使用します。
• 書き込み境界：キーのセマンティクスを維持するため、所有するユーザーまたはメッセージング API を通じて変更してください。
• 列：id、username、key、value

widgetregistration

• 目的：ユーザーおよびインストールごとに、有効期限付きの読み取り専用ウィジェット権限を保存します。専用の Bearer のダイジェストのみを保存し、未加工のシークレットやメインのログイントークンは保存しません。
• 有用なクエリ：ユーザー 1 人分のインストール所有権、有効期限、またはウィジェットアクセスの取り消しに関する、承認された診断に使用します。認証情報のダイジェストを開示したり、他のユーザーのインストール一覧を確認したりしないでください。
• 書き込み境界：セキュリティ上重要なデータです。認証済みウィジェット API を通じてのみ登録、ローテーション、または取り消しを行ってください。権限を追加したり、所有権や有効期限を変更したり、ダイジェストをログイン認証情報にコピーしたりしないでください。
• 列：id、registration_id、installation_id、user_id、owner、secret_digest、expires_at

workflow

• 目的：ワークフローの定義、トリガー、アクショングラフ、実行コンテキスト、およびランタイム状態を保存します。
• 有用なクエリ：スケジュールまたはイベントに基づくワークフロー、一時停止状態、現在のアクション、実行回数、および失敗の確認に使用します。
• 書き込み境界：ワークフロー API を通じて作成、変更、実行、一時停止、またはリセットしてください。
• 列：id、name、description、timer、trigger_type、event_type、event_conditions、state、current_action、result、run_count、actions、flows、context、execution_config、execution_state、add_time、last_time

データベース操作の仕様

• tables: arguments={} で現在のデータベーステーブルを一覧表示します。
• schema: arguments={"table_name":"downloadhistory"} を指定します。table_name は tables の結果に含まれている必要があります。
• query: arguments={"sql":"SELECT ...","limit":100,"write":false} を指定します。sql と file のどちらか一方だけを指定してください。デフォルトでは SELECT／WITH／EXPLAIN が許可されています。
• write: arguments={"sql":"UPDATE ... WHERE ..."} を指定します。sql と file のどちらか一方だけを指定し、ステートメントは1つだけにしてください。
• file は、MoviePilot プロセスが読み取り可能なローカル SQL ファイルのパスです。MCP クライアントは通常、sql を直接送信します。

古いドキュメントから列名を推測せず、最新の schema の結果を使用してください。media_source と media_id は、分割できない1つの識別子ペアとして扱ってください。

よく使うクエリ

ダウンロードの合計：

SELECT COUNT(*) AS total FROM downloadhistory

最近のダウンロード履歴：

SELECT title, year, type, torrent_site, date FROM downloadhistory ORDER BY id DESC LIMIT 10

失敗した転送：

SELECT id, title, src, errmsg, date FROM transferhistory WHERE status = 0 ORDER BY id DESC LIMIT 10

有効なサブスクリプション：

SELECT name, year, type, season, state, lack_episode FROM subscribe WHERE state = 'R' LIMIT 50

サイトのアップロード／ダウンロード統計：

SELECT name, domain, upload, download, ratio, bonus, seeding, user_level FROM siteuserdata ORDER BY upload DESC LIMIT 50

メディアライブラリの統計：

SELECT server, library, COUNT(*) AS count FROM mediaserveritem GROUP BY server, library

サイトへのアクセス成功率：

SELECT domain, success, fail, ROUND(success * 100.0 / (success + fail), 1) AS success_rate FROM sitestatistic WHERE success + fail > 0 ORDER BY success_rate DESC LIMIT 50

プラグインデータのキー：

SELECT plugin_id, key FROM plugindata ORDER BY plugin_id, key LIMIT 100

SQL 方言に関する注意事項

機能	SQLite	PostgreSQL
ブール値	0 / 1	false / true
文字列の連結	`
現在時刻	datetime('now')	NOW()
JSON アクセス	json_extract(col, '$.key')	col->>'key'
大文字と小文字を区別しない照合	LIKE	ILIKE

トラブルシューティング

• 依存関係が見つからない：SQLAlchemy とデータベースドライバーを利用できるよう、MoviePilot プロジェクトの環境内で実行してください。
• 接続に失敗する：moviepilot doctor で MoviePilot の設定を確認してください。
• テーブルが見つからない：python scripts/mp-db.py tables を実行し、続いて schema でテーブルを確認してください。