polygres-cli

Polygres CLI

インストール済みの polygres コマンドを使って、ユーザーの Polygres プロジェクトを操作します。 CLI を運用上およびセキュリティ上の境界として扱ってください。非公開のコントロールプレーンのルートを呼び出したり、文書化されていないリクエストペイロードを推測したりしないでください。

利用可能な MCP 接続を優先する

現在のセッションで Polygres MCP ツールを利用できる場合は、 references/mcp-tool-contract.md を読み、検出された互換性のあるツールを使って 対話的なプロジェクト操作を行ってください。whoami を呼び出し、 固定プロジェクトまたは複数プロジェクトの境界を守り、検出されたカタログを 正とみなしてください。

ユーザーが CLI を明示的に求めた場合、MCP が存在しないか互換性がない場合、 または操作が CLI の対象範囲に属する場合は、このスキルの CLI ワークフローを 使用してください。対象となる操作には、マイグレーション、Runtime キー、 対話的なデータベースアクセス、インポートの開始、従来のベクトルまたは テキスト設定などがあります。CLI コマンドを模倣する MCP ツールを決して 作り出さないでください。

安全に開始する

1. ライブテストまたはエンドツーエンドテストの前、および利用可能かどうかや コマンドの互換性が不明な場合は、polygres --version と polygres --help を実行してください。
2. コマンドが見つからない場合は、polygres-cli のインストール方法をユーザーに 伝え、インストールの承認または実施をユーザーに委ねてください。パッケージを 無断でインストールしてはいけません。
3. Polygres のソースチェックアウトからライブテストを行う場合は、分離された テスト環境を作成し、そのチェックアウトから依存関係のインストールポリシーに 従って polygres-cli と polygres-sdk の両方を再インストールしてから、 テスト前にそれらのバージョンとインポート元を確認してください。テスト対象の チェックアウトの代わりに PyPI パッケージを使用してはいけません。
4. ソースチェックアウト以外では、インストール済みの CLI と SDK のバージョンを、 アプリケーションまたは現在のスキル互換性記録で必要とされるバージョンと 比較してください。コマンドが存在するというだけで、最新の状態だと判断しては いけません。インストール済みパッケージを変更する前に承認を得てください。
5. ユーザーの識別情報またはアクティブな組織が不明な場合は、変更操作の前に polygres whoami を実行してください。認証が必要な場合は、 polygres login を使用してください。
6. polygres projects list、明示的な --project、または polygres projects use <project> でプロジェクトを解決してください。 破壊的な操作、シークレットを生成する操作、またはスキーマを変更する操作の 前に、解決したプロジェクトを明示してください。
7. project_mode を確認してください。値が synced の場合は、コマンドを 選ぶ前に references/synced-projects.md を読んでください。
8. エージェントが解析する必要のある出力には、polygres --json ... を 優先してください。stdout は JSON チャネルとして、stderr は診断情報として 扱ってください。

同梱の例がインストール済みの --help と異なる場合は、インストール済みの コマンド体系に従い、バージョンの不一致を説明してください。代替コマンドを 推測してはいけません。

リクエストを振り分ける

タスクに必要なリファレンスだけを読んでください。

ユーザーの意図	リファレンス
ログイン、ログアウト、識別情報、組織、プロジェクトの選択またはステータス	references/authentication-and-projects.md
同期プロジェクトの作成、機能、ライフサイクルの引き継ぎ、権限の境界	references/synced-projects.md
環境、Postgres メタデータ、psql、Runtime API キー	references/database-and-keys.md
CSV、TSV、JSON 配列、または JSONL/NDJSON からのデータセットまたはバックフィル	references/data-imports.md
1 つの JSON オブジェクトまたはランタイムイベントの検証、挿入、アップサート、または無視	references/rows.md
マイグレーションの一覧表示／適用と SQL の安全性	references/migrations.md
グラフ、テキスト、既存のベクトル設定、一般的な検索の準備状況	references/retrieval.md
MCP 経由で承認済みのグラフプランを実行するか、CLI にフォールバックする	references/mcp-graph-retrieval.md
Polygres AI Context のコレクション、フィルター、ポイント、操作、検索	references/context.md
JSON 出力、ポーリング、終了コード、リトライ、復旧	references/automation-and-errors.md

操作を実行する

1. リクエストを読み取り専用、変更、破壊的、スキーマ変更、またはシークレット生成に分類します。
2. 関連するリファレンスを読み込み、ローカル入力を検証します。
3. 認証とプロジェクトのコンテキストを解決します。
4. プロジェクトモードを解決し、そのモードでは利用できないコマンドを停止します。
5. 変更を行う場合は、対象プロジェクト、影響を受けるリソース、重要なオプション、元に戻せるかどうかを提示します。
6. 必要な場合は明示的な承認を得ます。このプロジェクト、ソース範囲、アクション、および変更されていないプランダイジェストを指定している既存の統合パイプライン承認があれば、それを受け入れます。
7. ドキュメントに記載されたコマンドのうち、最も対象を絞ったものを実行します。
8. 結果に含まれるプロジェクト、ジョブ、マイグレーション、設定、キー、リクエストの各 ID を保持します。
9. 観測された最終状態のみを報告します。処理がまだ実行中の場合は、その旨を伝え、ステータスコマンドを提示します。

同意を必須とする

次の操作を行う前に、ユーザーから明示的な承認を得てください。

• replace_existing インポート。
• SQL マイグレーションの適用。
• 生成された TSVector 列や管理対象テキストインデックスを含む、テキスト設定の作成または更新。
• テキスト設定の再インデックス。
• Runtime API キーの無効化。
• 既存のベクトル設定またはテキスト設定の削除。
• コレクションの作成、更新、デフォルト設定、ベクトル追加、デフォルトベクトルの変更、再インデックス、削除を含む、永続的な pgContext のすべての変更。フィルターの登録、ポイントの整合性調整、操作のキャンセルまたは再試行。
• pgContext のポイントのアップサートまたは削除のうち、永続的な操作となるもの、またはマッピングの削除がユーザーのサービング動作に破壊的な影響を及ぼすもの。
• --yes を使用するコマンド。
• 破壊的、または元に戻すことが困難なその他の操作。

その操作と対象について承認を得た後に限り、--yes を追加します。 ユーザーのコマンドによってすでに承認されている、または一致する統合パイプライン承認がある rows insert、rows upsert、rows ignore コマンドには、追加の確認を求めないでください。 add-column または new-table によるコレクション作成について承認を得る前に、事前確認用の DDL、影響を受けるスキーマオブジェクト、および所有権の境界も提示します。

シークレットを保護する

• ネイティブデータベースのパスワードを要求、取得、保存、記録、または受け渡してはいけません。
• 同期対象のソース接続情報を要求したり、引数や生成ファイル、トランスクリプトに出力したりしてはいけません。CLI の非表示の対話型 URL プロンプトを優先してください。承認済みの非対話型操作では、値を確認せずに、ユーザーが設定した環境変数を --connection-env で参照してください。
• データベースのパスワードは psql からユーザーに入力を促してください。
• エージェントのターミナルで対話型 TTY を維持できない場合は、パスワードを使わないコマンドを提示するか、ユーザーに polygres db psql を直接実行してもらいます。
• POLYGRES_ACCESS_TOKEN をユーザーに尋ねてはいけません。これは開発およびテスト用のオーバーライドであり、公開された認証フローではありません。
• polygres keys create <name> の前に警告してください。Runtime API キーのシークレットは一度だけ表示され、ターミナルやエージェントの履歴に残る可能性があります。
• シークレットがエージェントのトランスクリプトに残らないよう、ユーザー自身のターミナルでキーを作成する方法を提案してください。
• トークン、キー、パスワードをソースファイル、例、コマンド引数、ログ、最終的な要約に含めてはいけません。

CSV 以外のデータをローカルで準備する

TSV、JSON 配列、および JSONL/NDJSON データセットについては、references/data-imports.md を読み、scripts/prepare_import.py を使用します。個別の書き込みを目的とする単一の JSON オブジェクトは、代わりに references/rows.md を参照してください。リポジトリに scripts/ があると想定せず、このスキルディレクトリを基準にスクリプトのパスを解決します。

このコンバーターはローカルでのみ動作し、レビュー済みの CSV 成果物を生成します。Polygres には接続しません。結果を説明して必要な承認を得ずに、ネストされた JSON を暗黙にフラット化したり、列名を変更したり、null 値と空文字列の値を統合したりしてはいけません。

SQL マイグレーションを汎用的な行インポート手段として提示してはいけません。これらのコマンドは現在の公開 CLI に含まれていないため、バックエンドの SQL インポートや pg_dump のルートを呼び出してはいけません。

失敗への対処

終了コードの解釈には、references/automation-and-errors.mdを使用してください。特に、次の点に注意してください。

• 終了コード2の場合は、再試行する前に検証エラーを修正します。
• 終了コード3の場合は、再認証します。
• 終了コード4の場合は、権限が不足していることを説明します。
• 終了コード5の場合は、不足しているリソースを解決します。
• 終了コード6の場合は、競合または曖昧なプロジェクト選択を解決します。
• 終了コード7の場合は、レート制限のガイダンスに従います。
• 終了コード8の場合は、リモート側の失敗またはタイムアウトとして扱います。
• 終了コード9の場合は、psqlなど、不足しているローカル依存関係をインストールするか、担当者に引き継ぎます。

インポートまたはプロビジョニングがタイムアウトした場合は、再送信する前に、対象のリソースまたはジョブの既知のステータスを確認してください。クライアントがタイムアウトしても、サーバー側の操作が失敗したとは限りません。