polygres-troubleshooting

Polygres のトラブルシューティング

まず読み取り専用のチェックを行ってください。コンテキストを特定し、証拠を保全して、障害の境界を分類したうえで、最小限で安全な修正を推奨してください。診断中は変更を加えないでください。

Polygres MCP ツールを利用できる場合は、references/mcp-tool-contract.md を読み、whoami を呼び出して、検出した読み取りカタログを CLI や SDK にフォールバックする前に使用してください。接続 URL の制限、OAuth のインストール、現在のスコープ、プロジェクトの境界、プロジェクトモード、カタログのバージョンは、それぞれ別の診断レイヤーとして扱ってください。

ワークフロー

1. コマンドを使用する前に、インストール済みの polygres --help とコマンド固有のヘルプを確認してください。CLI の互換性については、インストール済みの動作を正とします。
2. references/context-and-connectivity.md を使用して、ID、設定ソース、対象プロジェクトを一つに特定してください。プロジェクトを明確に特定できない場合は中止してください。
3. 症状、タイムスタンプ、サニタイズ済みのコマンドまたは SDK 呼び出し、終了コードまたは例外の種類、request_id、ジョブ ID、ページネーションでカーソルが返されたかどうかを記録してください。 生成されたパイプラインの場合は、マニフェストの状態、プランダイジェスト、承認済みのアクション ID、チェックポイント、最後に正常に完了したステージも記録してください。
4. references/projects-and-database.md を使用して、プロジェクトとデータベースの証拠を調べてください。
5. project_mode が synced の場合は、references/synced-projects.md を使用し、ターゲットデータベース、行、インポート、マイグレーションのチェックは省略してください。
6. インポートジョブまたはマイグレーションの失敗には references/jobs-and-migrations.md を使用してください。グラフ、ベクトル、テキスト、ハイブリッド、または一般的な準備状態の失敗には references/retrieval.md を使用してください。pgContext の機能、コレクション、ポイント、操作、想起、または Joint の失敗には references/context.md を使用してください。 MCP 経由の検索評価には references/mcp-retrieval-quality.md を、MCP 操作の状態には references/mcp-operation-recovery.md を使用してください。
7. 障害を CLI／ローカル設定、コントロールプレーン、Runtime API、Postgres／データベースまたはプーラー、非同期ジョブの状態に分類してください。型付き SDK エラーとエスカレーションには references/errors-and-escalation.md を使用してください。
8. 再試行する前にステータスを再確認してください。修正を提案しますが、明示的な承認を得てください。また、サポート対象の変更は $polygres-cli に、アプリケーションの変更は $polygres-sdk に委任してください。

送信後に応答を失った単一行の書き込みでは、公開されている証拠で解決できない限り、コミットの結果を不確定として扱ってください。行のみの挿入、アップサート、または無視を自動的に再試行しないでください。Context を利用した書き込みでは、正確な冪等性キーを使って、正確なリクエストを24時間の再実行ウィンドウ内に再送してください。複合台帳により、行への変更が再度行われることを防ぎます。ROW_CONTEXT_IDEMPOTENCY_EXPIRED の後は、新しいキーを選ぶ前に行と Context のポイントを調べてください。

証拠に関するルール

• インストール済みヘルプと公開されている $polygres-sdk のメソッドで確認されたコマンドのみを使用してください。非公開のエンドポイントを推測したり、内部の可観測性を使用したりしないでください。
• リクエスト ID とジョブ ID は正確に保持してください。証拠が存在しないことと、チェックが成功したことを区別してください。
• データベースのパスワード、API キー、認可ヘッダー、認証情報を含む接続文字列、環境変数の全出力をログに記録しないでください。
• 検証、認証、権限、互換性に関するエラーを、一時的なエラーとして再試行しないでください。レート制限やタイムアウトに対する再試行には上限を設けてください。
• 変更のない統合パイプラインレビューですでに修正アクションが承認の対象となっている場合、再度承認を求めないでください。プロジェクト、ソーススコープ、アクションセット、エグレス、破壊的な影響、またはプランダイジェストが変更された場合は、再度確認してください。
• ページネーションと部分的な失敗を明示的に報告してください。最初のページが成功したことや、サブシステムの一つが正常であることは、操作全体の成功を示すものではありません。

診断レポート

• 解決した ID 情報： アカウント ID、または特定できない正確な理由。
• 解決したプロジェクト： 正確なプロジェクト ID、または選択を妨げた曖昧さ。
• 症状： 観測可能な障害と影響を受けた操作。
• 観測された証拠： サニタイズ済みのステータス、例外クラス、タイムスタンプ。
• 考えられる原因： 証拠に裏付けられた分類と確信度。
• 実施した安全な確認： 使用した公開読み取り専用コマンドと SDK 呼び出し。
• 是正措置： まだ実施していない、文書化された最小限の措置。
• 承認またはエスカレーション： 必要な承認、またはエスカレーション先。
• 保持した ID： 秘密情報を含まないリクエスト ID、ジョブ ID、カーソル。
• 不明点： 欠落、古い、互換性がない、または矛盾している証拠。

制約事項

• 診断中に変更を加えないでください。認証情報のローテーション、ジョブや Context 操作の再試行、マイグレーションの適用、ポイントの調整、グラフリソースの再構築、 テキスト、ベクトル、または Context の再インデックスを開始しないでください。
• 文書化されていないルートや非公開のルートを呼び出したり、非公開の オブザーバビリティシステムにクエリを送信したりしないでください。
• 証拠が考えられる境界を示すにとどまる場合、根本原因を断定しないでください。