pythia-setup

セットアップ

開始時に告知: 「pythia-setup を使用して、データベースアクセスを設定します。」

フェーズ: Do — ハーネスの初回セットアップです。以降はすべて Learn → Ask → Do を通じて実行します。

次の順でセットアップします。まず接続（ほかのすべてに必要です）、次に最小権限のユーザー（回避できない唯一の保護です）、最後に SQLcl MCP（任意、読み取り専用）です。

1. 接続

プロジェクトのルートに .pythia/connections.json を作成します。pythia install でひな形を作成できます（pip でインストールする場合：pip install pythia-plsql）。または、クローンから examples/connections.example.json をコピーして記入します。pythia が適用するルールは次のとおりです。

• エントリが1つの場合は、そのまま使用します。複数ある場合は、プロジェクトルート直下のパス要素で選択します（root/DEV/... → DEV）。該当しない場合は、トップレベルの "default": "<name>" で指定されたエントリを使用します。曖昧な場合は推測せず、エラーになります。
• --conn NAME と PYTHIA_CONNECTION はすべての設定を上書きします。PYTHIA_USER/PYTHIA_PASSWORD/PYTHIA_DSN 変数を使うと、ファイルを経由しません。
• このファイルには認証情報が含まれます。install はこのファイルを .gitignore に追加します（その行をコミットしてください）。その状態を維持し、チャットやスクリーンショットに含めないでください。git がこのファイルを追跡している場合、pythia doctor は失敗します。

pythia check で確認します。接続先のユーザー名とオブジェクト数が表示されます。失敗した場合は、接続名と確認すべき項目が示されます。

2. エージェント用のデータベースユーザー — 実際の保護

ポリシーファイルはアプリケーション側の防護策です。エージェントが回避できないのは Oracle の権限付与だけです。 Oracle には「そのスキーマで PL/SQL を編集できる」という明確なオブジェクト単位の権限はありません。別のスキーマにコンパイルするには CREATE ANY PROCEDURE が必要となり、インスタンス上のすべてのスキーマに適用されるためです。

完全な構成は3つのアカウントで成り立ちます。admin（管理のみ）、owner（スキーマの所有者。DBA にしてはいけません。プロキシセッションは owner が持つ権限をすべて継承します）、agent（ログインのみ）です。GUIDE のセクション3と examples/agent-user-setup.example.sql を参照してください。中核となるのはプロキシ認証です。ログイン専用のユーザーがスキーマ所有者を経由して接続します。エージェントが所有者のパスワードを知ることはなく、権限の取り消しは1つの文で済み、監査証跡には実際に接続したユーザーが記録され、影響範囲は1つの開発スキーマに限定されます。

プロジェクトディレクトリで pythia agent-user --save を1回実行します。生成されたパスワードを含む3つの文のプロキシ SQL が出力され、対応する認証情報が <conn>_agent という接続名で保存されます（これが新しいデフォルトになります。owner のエントリは変更されません）。実行するたびにパスワードが再生成されるため、先にプレビューして後で保存してはいけません。SQL と保存される設定は、同じ実行から取得する必要があります。SQL をそのまま開発者に伝え、DBA に実行してもらってから、pythia check で確認してください。--json を指定すると、同じ結果が機械可読形式で返されます。手動で設定する場合は、名前を適宜変更した examples/agent-user-setup.example.sql を使用します。

LLM アクセスに関する Oracle 独自のガイダンスに従ってください。最小限の権限を付与し、LLM を本番データベースに接続せず、そのアクティビティを定期的に監査します。

セッションが %ANY% 権限を持っている場合、またはスキーマ所有者として直接実行されている場合、pythia check は1行で警告します。目指す状態は、警告がないことです。

3. SQLcl MCP サーバー（任意、読み取り専用）

SQLcl 25.2+ がインストールされている場合、エージェントは Oracle 公式 MCP サーバー（コマンド sql -mcp）を通じて読み取りを行えます。クライアント設定の例：

{"mcpServers": {"sqlcl": {"command": "sql", "args": ["-mcp"]}}}

• デフォルトの制限レベル（-R 4、最も厳しい設定）を維持してください。これにより、ホストコマンドと @ スクリプトがブロックされます。ただし、run-sql 内の DML／DDL はブロックされません。**書き込みには MCP を使用しないでください。**スナップショット、プレビュー、検証、ジャーナルが備わっているのは pythia apply だけです。
• 組み込みの監査機能については、DBA に伝えておくとよいでしょう。すべてのやり取りは DBTOOLS$MCP_LOG に記録されます。V$SESSION.MODULE には MCP クライアントが、V$SESSION.ACTION には LLM の名前が表示されます。また、生成された SQL には /* LLM in use */ コメントが付与されます。

4. .pythia/ に格納されるものと、その作成方法

install によって書き込まれるのは connections.json だけです。その他のファイルは必要に応じて作成されるため、.pythia/ が空でも正常に動作しています。必要になるまでは、何も欠けていません。

ファイル	作成方法	用途
connections.json	pythia install	接続先を保存します。パスワードが含まれるため、絶対に開かないでください。pythia connections を実行すると、秘密情報を表示せずに名前、ユーザー、スキーマ、ターゲットを一覧表示できます。インストール時に .gitignore に追加されます。
journal/	初回の書き込みまたはスナップショット作成時	記録された各バージョンが保存され、各エントリーから実行可能なロールバックを利用できます。
conventions.json	pythia conventions --init	オブジェクトの種類ごとの命名パターンを保存します。新しい名前がパターンから外れると、適用前のプレビューで警告されます。
conventions.md	pythia conventions --init	チームのルールを文章で記述します。pythia-write は何かを書き込む前にこのファイルを読み込みます。同梱されている一般的なパターンよりも優先されます。
policy.json	pythia policy set <group> <value>	書き込みポリシーを固定します。ファイルがない場合は、すでに安全な組み込みの既定値が使われます。
settings.json	手動で作成	{"auto_snapshot": false} などの任意の設定を指定します。

チームの慣習を記録することは、最も価値の高い任意のステップです。 pythia conventions --init を実行し、プレースホルダーのパターンを実際のパターンに置き換えてください。pythia similar <A_TYPICAL_NAME> を実行すると、スキーマですでに使われている命名がわかるため、一から規則を考えるより効果的です。違反した場合にコストが発生するルールを conventions.md に記入し、そのコストも明記してください。結果が明確なルールほど守られます。両方のファイルをプロジェクトリポジトリにコミットし、チーム全体とすべてのエージェントセッションで同じルールを使えるようにしてください。

5. 承認、フック、環境 — pythia doctor

pythia install は Claude Code のフックを設定し、.mcp.json に pythia_approve MCP 承認ツールを登録します（dontAsk 以外のすべての権限モードでプロンプトを表示する承認ゲートです）。また、Codex の同等の設定も行います。再起動後：

• pythia doctor — すべてのフックが設定され、pythia を起動できること（インポートできないフックはフェイルオープンとなり、ガードは無効になります）、承認ゲートが登録されていること、かつ、かつて AskUserQuestion が空の結果を返す原因となった設定（許可ルール、または allowed-tools にこれを指定するスキル、設定内でこれを捕捉する PreToolUse フック、あるいは有効なプラグイン）を確認します。現在の Claude Code ではダイアログが必要なため、これらは今は warn になります。dontAsk は fail になり、両方のチャットゲートを閉じます。fail の各行はガードまたは承認が機能しない理由を示します。行に記載されたファイルとあわせて、その内容を共有してください。セッションの approval door 行には、この環境で機能する順序でゲートが表示されます。
• pythia doctor --db — バージョン、文字セット、PL/Scope とコンパイラ警告の網羅状況、INVALID オブジェクト、utPLSQL を確認します。
• 本番相当の接続には、connections.json で "protected": true（または "env": "prod"）を設定してください。autopilot はその接続への操作を拒否するようになります。

堅牢な開発環境のチェックリスト全体については、reference/environment.md を参照してください。ローカルの Oracle Free コンテナ、AL32UTF8、コンパイラ設定、共有スキーマの衛生管理、utPLSQL、レビュー作業と自律作業それぞれに適したクライアント権限モードについて説明しています。

完了の条件

• pythia check が接続し、正しいスキーマを表示し、権限に関する警告を一切出力しない。
• pythia doctor に fail の行が表示されない。
• pythia policy が書き込みポリシーとロールバックテーブルを出力する。
• 認証情報ファイルが追跡対象になっていない（git status に表示されない）。