pythia-table

テーブル、列、コメント

開始時に宣言: 「pythia-table を使用します — DDL を設計する前に、テーブルとその周辺を確認します。」

フェーズ: 学習 → 質問 → 実行 — 現状のテーブル、開発者が決めること、順序付けた単一のスクリプト

テーブルは、それを読み取るすべてのプログラムより長く使われます。列は、スキーマ内のすべてのレポート、インターフェース、プロシージャとの契約です。構造を変更する DDL は、ほとんど取り消せません。DROP COLUMN は元に戻せず、列名を変更すると、すべての呼び出し元が一度に動かなくなります。設計に費やす 5 分は、最も低コストな手順です。

絶対則

NO TABLE OR COLUMN WITHOUT ITS COMMENT, ITS CONSTRAINTS AND ITS IMPACT KNOWN

ワークフロー

1. テーブルとその周辺を確認します。
   • pythia cols T · pythia comments T · pythia stats T — 何が存在し、何が文書化されていて、どの外部キーにインデックスがないかを確認します。
   • ALTER の前に pythia impact T を実行します — 再コンパイルされるすべてのプログラムを確認します。
   • pythia similar T_<NAME> と pythia ddl TABLE <NEIGHBOUR> — この環境ですでにテーブルがどのように作られているかを確認します。PK のスタイル、監査列、テーブルスペース、命名規則を確認してください。.pythia/conventions.md と pythia conventions を読みます。
2. 何が開発者の判断事項かを質問します（pythia-spec を通じて）。保持するものと削除するもの、既存行の NULL 許容性とバックフィル値、保持期間、テーブルへの書き込み元（API パッケージ、トリガー、インターフェース）、この環境に規則がない場合の ID 列とシーケンスのどちらを使うかを確認します。NOT NULL 列のビジネス上のデフォルト値を勝手に決めてはいけません。
3. 順序付けた単一のスクリプトを作成します — テンプレートとデータ型の規則については reference/ddl-standards.md を参照してください。
   • すべての制約に名前を付けます（この環境で別の規則が定められていない限り、PK_、FK_、UK_、CK_）。すべてのテーブルに主キーを設定し、すべての FK 列にインデックスを設定します。
   • 文字列には VARCHAR2(n CHAR) を使用します — ベトナム語の文字は 3 バイトを占める場合があります。金額には NUMBER(p,s) を使用し、FLOAT は使用しません。必要に応じて DATE または TIMESTAMP を使用します。
   • 追加するすべてのテーブルと列に COMMENT ON TABLE と COMMENT ON COLUMN を記述します。意味、単位、許容値、ソースを記載します。ここではベトナム語を使用してもかまいません — COMMENT ... IS が受け取るのはリテラルのみ（unistr は使用不可）で、pythia は UTF-8 をそのまま送信します。文字セットがベトナム語を保持できない場合は、pythia doctor --db が警告します。
4. Lint を実行します：pythia lint script.sql comments.sql（1 回の実行にまとめると、コメントファイルも対象になります） — コメントの不足、名前のない制約、インデックスのない FK、デフォルト値のない ADD ... NOT NULL、バイトセマンティクスの文字列、必須列の不足を検出します。エラーは修正してください。議論の余地はありません。
5. 適用します：pythia-deploy（pythia deploy script.sql）を使用します。すべてのステートメントをプレビューし、承認は 1 回だけ行い、順番に実行し、最初の失敗時点で停止します。単一のステートメントは、通常どおり pythia apply で実行できます。structural はデフォルトで deny です — 拒否を開発者に伝えてください。判断するのは開発者です（pythia policy set structural confirm、または structural を指定した autopilot リースを使用します）。
6. 検証します（pythia-verify）：pythia cols T、pythia comments T（不足が 0 件であること）、ベースラインに対する pythia invalid を実行します。

ライブテーブルの変更 — まず拡張し、その後で縮小する

変更	安全な方法
新しい必須列	ADD (c ... DEFAULT <agreed> NOT NULL) — 1ステップで完了し、12c 以降ではメタデータのみを変更します。合意済みのデフォルト値がない場合は、NULL を許容して追加し、バックフィル（data_dml）を行ってから、MODIFY c NOT NULL を実行します。
名前変更	共有スキーマでは、その場での変更は避けます。新しい列を追加してコピーし、呼び出し元を切り替えてから、後で古い列を削除します。削除には別途、破壊的変更の承認が必要です。
型変更	拡張（VARCHAR2(50) → (100)）はその場で変更できます。それ以外の縮小や変換では、新しい列を追加してコピーし、切り替えます。
既存データへの新しい FK	まず ENABLE NOVALIDATE を設定し、行を整理してから VALIDATE を実行します。制約より先にインデックスを作成します。
削除	破壊的変更です。専用のプレビューと承認が必要です。カードに記載がない限り、自動操縦リースには含めません。Recycle Bin が有効であることを確認し、依頼がない限り PURGE を追加しないでください。

大規模テーブル（数百万行）の場合、デフォルト値を指定した ALTER TABLE ... ADD はメタデータのみを変更しますが、MODIFY、インデックスの作成、バックフィルにはデータ処理が伴います。実施可能な時間帯を確認してください。また、ONLINE インデックス作成には Enterprise Edition が必要です。パーティショニングと圧縮は別途ライセンスが必要なオプションです。提案する前に、その点を明示してください。

ロールバックは本当に可能ですか？

文	元に戻す方法
COMMENT ON	はい — 以前のコメントがスナップショットに保存されています。pythia journal restore <entry> を実行します。
CREATE TABLE / INDEX / SEQUENCE	DROP を実行します。構造を変更する操作なので、手動で記述し、ほかの書き込みと同様に承認を得ます。
ALTER TABLE ADD	ALTER TABLE ... DROP COLUMN を実行します。その間に書き込まれたデータは失われます。
DROP、TRUNCATE、SET UNUSED	いいえ。 保持期間内であれば、フラッシュバックは DBA の担当です。

要注意事項 — 次のように考えてしまったら、作業を中断してください

考え	実際のところ
「動いてからコメントを追加すればよい」	その「後」はやってきません。データディクショナリだけが残るドキュメントです。同じスクリプトでコメントを追加してください。
「FK インデックスは最適化のためのもの」	インデックスがないと、親行の削除時に子テーブル全体がロックされます。負荷がかかった状態で正しく動作させるために必要です。
「VARCHAR2(100) なら十分」	AL32UTF8 では、100 バイトでベトナム語の文字は約 33 文字しか格納できません。CHAR を指定してください。
「NOT NULL 列のデフォルト値は 0 にすればよい」	それは黙って下すビジネス上の判断です。確認してください。
「名前変更は1つの文で済む」	参照ごとに呼び出し元が1つ壊れます。まず拡張し、その後で縮小してください。
「新しいテーブルだから影響はゼロ」	pythia impact を根拠として示してください。そうすれば推測ではなく事実になります。

このスキルを使用しない場合

• テーブルを読み取るコードを変更する場合 → pythia-write / pythia-package。
• 既存テーブルでクエリが遅い場合 → pythia-tune（チューニング時にインデックスが必要になれば、ここで設計します）。
• データの修正（UPDATE/DELETE）を行う場合 → pythia-apply。これらは data_dml です。