pythia-table

表、列与注释

开始时宣布：“正在使用 pythia-table——先读取表及其相邻对象，再设计 DDL。”

**阶段：**了解 → 提问 → 执行 — 了解表的现状，确认由开发者决定的事项，然后编写一份有序脚本

表的生命周期远长于读取它的任何程序。它的列与架构中的每份报告、每个接口和每个过程都是一份契约，而结构性 DDL 几乎无法撤销：DROP COLUMN 是永久操作，重命名列会让所有调用方同时出错。花五分钟设计，是最划算的一步。

铁律

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> — 了解当前项目如何创建表：主键风格、审计列、表空间、命名方式。阅读 .pythia/conventions.md 并运行 pythia conventions。
2. 询问哪些事项应由开发者决定（通过 pythia-spec）：保留还是删除、现有行的可空性和回填值、保留期限、谁会写入此表（API 包、触发器、接口），以及在项目没有规定时使用标识列还是序列。绝不要擅自为 NOT NULL 列编造业务默认值。
3. 编写一份有序脚本 — reference/ddl-standards.md 中有模板和数据类型规则：
   • 为每个约束命名（除非项目另有规定，使用 PK_、FK_、UK_、CK_）；每张表都必须有主键；每个外键列都必须有索引；
   • 文本使用 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（一次运行，这样注释文件也会被计入）— 检查缺少注释、未命名约束、缺少索引的外键、没有默认值的 ADD ... NOT NULL、按字节语义定义的文本、缺少项目规范列等问题。错误必须修复，不可争辩。
5. 部署：使用 pythia-deploy（pythia deploy script.sql）：预览每条语句，经一次批准后按顺序执行，遇到首个失败立即停止。单条语句仍可像往常一样通过 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)——一步完成，在 12c+ 上仅修改元数据。没有商定的默认值？则先添加可空列，回填（data_dml），然后执行 MODIFY c NOT NULL。
重命名	共享架构中绝不能直接重命名：添加新列、复制数据、迁移调用方，之后再删除旧列——这需要单独进行破坏性操作审批。
类型变更	扩大类型范围（VARCHAR2(50) → (100)）可直接修改；缩小类型范围或进行类型转换：新建列、复制数据、交换列。
为现有数据添加新外键	先执行 ENABLE NOVALIDATE，清理数据行，再执行 VALIDATE——并且先创建索引，再添加约束。
删除	破坏性操作：需要单独预览、单独审批；除非操作卡片明确说明，否则绝不能在自动驾驶租约期间执行。检查回收站是否已启用，未经要求绝不添加 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 的工作。

危险信号——如果发现自己在想以下内容，请立即停止

想法	事实
“等它能用了再补注释”	永远等不到那时候；数据字典是唯一能保留下来的文档。使用同一个脚本。
“外键索引只是优化”	没有它，删除父表中的行会锁定整个子表。这是在负载下保证正确性的必要条件。
“VARCHAR2(100) 肯定够用”	在 AL32UTF8 中，100 字节约等于 33 个越南语字符。请声明 CHAR。
“我会把 NOT NULL 列的默认值设为 0”	这等于悄悄替业务做决定。请先询问。
“重命名只是一条语句”	每个引用处都会有一个调用方因此中断。先扩展，再收缩。
“表是新的，影响为零”	使用 pythia impact 提供证据说明这一点——这样它就是事实，而不是猜测。

何时不应使用此技能

• 更改读取该表的代码 → pythia-write / pythia-package。
• 现有表上的慢查询 → pythia-tune（调优要求建立索引后，仍在此处设计索引）。
• 修复数据（UPDATE/DELETE）→ pythia-apply；这些操作属于 data_dml。