pythia-package

パッケージ、プロシージャ、関数、トリガーの設計

開始時に宣言：「pythia-package を使用して、本文を書く前に仕様を設計します。」

フェーズ： 学習 → 質問 → 実行 — まず関連するコードと呼び出し元を確認し、契約を合意してから、仕様と本文を2つのファイルに分けて作成します。

pythia-write を使うと、新しいコードをコードベースの既存コードと見分けがつかないほどなじませられます。このスキルで補うのは、コードベースに現れていないかもしれない点、つまり呼び出し元が信頼できるようにユニットをどのような形にすべきかです。プロジェクトの慣習が異なる場合は、プロジェクトの慣習を優先します。まず .pythia/conventions.md を確認し、そこで決まっていないことはすべて reference/plsql-standards.md を参照してください。

鉄則

THE SPEC IS A CONTRACT: DESIGN IT FIRST, AND NEVER BREAK IT SILENTLY

パッケージ仕様の変更は依存先すべてを一度に無効化しますが、本文の変更は何も無効化しません。この非対称性が、設計上の判断の大半を左右します。

ワークフロー

1. 学習する — 上位2、3件を対象に pythia similar <NAME> と pythia src を実行し、呼び出すすべてのユニットについて pythia args を実行します。パッケージが存在する場合は pythia impact <PKG> を実行します（仕様の変更はパッケージ全体に影響します）。対象となるすべてのテーブルについて pythia cols を実行します。
2. 契約の形を決める（動作に検討の余地がある場合は、まず pythia-spec を使用します）：
   • プロジェクトでスタンドアロンユニットを作成する慣習がある場合を除き、スタンドアロンではなく パッケージにします。カプセル化、プライベートヘルパー、依存先を無効化しない本文変更が可能になります。
   • 公開するのは呼び出し元に必要なものだけです。それ以外はすべて本文内だけに置くプライベートなものにします。新しい公開項目は仕様の 末尾に追加します。細粒度の依存関係追跡（11g以降）があれば、既存の依存先は VALID のまま維持されます。
   • パラメーターには %TYPE を使い、デフォルトは IN にします。OUT はプロシージャでのみ使用し、大きな IN OUT コレクションや LOB には NOCOPY を使用します。デフォルト値を設定するのは、入力が真に任意の場合だけです。
   • 関数は1つの値を返し、OUT パラメーターを持たず、SQL から呼び出される可能性がある場合は DML を実行しません。
   • エラー契約：仕様で名前付き例外を定義するか、パッケージごとに -20xxx の範囲を1つ定めて文書化します。呼び出し元が「見つからない」と「壊れている」を区別できるようにします。
   • トランザクション契約：コミットするのは最外部の呼び出し元です。ユニットがコミットする場合は、そのことを名前または仕様のコメントで明記します。そのユニットは、より大きなトランザクションの一部として組み合わせられません。
   • ロギング／計測にはプロジェクトのロガーを使用します。長時間実行するエントリーポイントでは DBMS_APPLICATION_INFO.SET_MODULE/SET_ACTION を設定し、DBA が実行内容を確認できるようにします。
   • セキュリティ：仕様で呼び出し元権限が必要な場合を除き、AUTHID DEFINER を使用します。内部ヘルパーには ACCESSIBLE BY（12c）を使用し、動的 SQL に渡す識別子にはすべて DBMS_ASSERT を使用します。コード内に認証情報を記述しません。
3. 2つのファイルを作成する — まず仕様、次に本文を作成します（1ファイルにつき1オブジェクト、末尾に / を記述し、ベトナム語のメッセージには pythia unistr を使用します）。テンプレートは reference/plsql-standards.md を参照し、コメントには pythia-comment を使用します。
4. トリガーは薄く保つ：導出処理と監査のみとし、業務プロセス、COMMIT、リモートシステムへの呼び出しは含めません。同じテーブルで複数のタイミングポイントが必要な場合は、複合トリガーを1つ使用します（ORA-04091 の原因となるテーブル変更中の参照への対策にもなります）。トリガーに隠れてしまいがちな業務ルールは API パッケージに実装します。
5. 確認する — pythia lint spec.sql body.sql を実行し、続けて pythia-review を実行します。
6. 反映する — まず仕様、次に本文の順で反映します。pythia deploy spec.sql body.sql（承認は1回、順序どおり）を使うか、pythia apply を2回実行します。終了コード3は失敗を意味し、完了ではありません。
7. 検証する — pythia errors <PKG> を実行し、ベースラインと照らして pythia invalid を実行します。また、未使用または一度も値が代入されていない識別子について pythia plscope <PKG> を実行します。

危険信号 — 次のように考えていることに気づいたら、作業を止めてください

考え	実際のところ
「既存のプロシージャにパラメーターを追加するだけ」	呼び出し元がすべて壊れるか、再コンパイルが必要になります。オーバーロードを追加するか、仕様の末尾に新しいユニットを追加してください。
「WHEN OTHERS THEN log; で十分」	RAISE がなければ、呼び出し元は処理が成功したと思い込みます。ログを記録してから、例外を再送出してください。
「安全のために最後に COMMIT する」	これでは誰も自分のトランザクション内で呼び出せなくなります。コミットは呼び出し元が行います。
「このルールを実装するなら、トリガーが一番簡単」	その分、データ修正の際に見つけるのも、テストするのも、回避するのも最も困難です。API パッケージを使ってください。
「PRAGMA AUTONOMOUS_TRANSACTION を使えば変異テーブルの問題を解決できる」	エラーを隠し、古いデータを読み取ります。コンパウンドトリガーを使ってください。
「テーブル名を連結しても問題ない。内部処理だから」	今日は内部処理でも、将来は変わるかもしれません。DBMS_ASSERT.SQL_OBJECT_NAME の呼び出しは一度だけです。
「標準では X とされているが、コードベースでは Y になっている」	コードベースを優先してください。X は別途提案してください。

このスキルを使わない場合

• 既存のユニット内での小さな編集 → pythia-write で十分です。
• テーブル設計 → pythia-table。パフォーマンス調整 → pythia-tune。
• 他の人が作成したユニットのレビュー → pythia-review。