pythia-explore

探索架构

开始时宣布：“正在使用 pythia-explore —— 直接向数据库查询。”

**阶段：**学习

原则：查询数据库，而不是导出文件

导出的 .sql 文件仓库从导出后的第二天起就会过时。一个真实的中型系统在 2026 年接受审计时，将仓库中的导出文件与实时数据库进行了比较：

对象类型	导出文件中	数据库中	结论
存储过程	3,827	3,827	匹配
表	952	952	匹配
类型	0	115	全部缺失
包	0	9	全部缺失
索引	116	1,016	约 89% 缺失

针对导出文件编写的代码可能“看起来没问题”，却引用了导出文件中从未包含的类型和包。

当开发者交给你一个 .sql 文件时——“解释一下这个存储过程”、“这是导出文件，它的作用是什么”——这个文件只是一个说法，并非事实。先阅读它，然后运行 pythia src <NAME>，根据数据库作答。如果两者不一致，先说明这一点：哪个版本更新，正是开发者需要知道的信息，而仅凭文件无法判断。只要数据库可访问，就绝不要仅根据文件回答数据库对象相关问题。

只有在数据库不可访问时，才将文件内容作为答案，并说明你正在这样做。

你需要什么 → 运行什么命令

需求	命令
连接是否正常，有什么架构	pythia check
按名称查找对象	pythia ls "PKG_%"
查看源代码及编译器提供的行号	pythia src NAME（--body、--spec）
存储过程／函数签名	pythia args NAME
列和实际数据类型	pythia cols TABLE_NAME
完整 DDL	pythia ddl TABLE NAME
搜索所有 PL/SQL 文本	pythia grep "text"
对象依赖了什么	pythia deps NAME
哪些对象依赖某个对象	pythia impact NAME
精确的标识符用法（优于 grep）	pythia plscope NAME
名称类似于该程序的程序	pythia similar NAME
当前所有失效对象	pythia invalid、pythia errors
自由形式的问题	pythia sql "select ..."（仅限 SELECT/WITH）

确保答案准确的规则

• **始终会提示输出是否被截断。**输出末尾会有 -- truncated ...，或者在 --json 中设置 "truncated": true。如果没有看到标记，就说明看到了全部内容；如果看到了，就要说明这一点，或获取更多内容（--limit、--offset、--max-lines）——绝不要把截断的列表说成完整列表。
• 要查找“X 在哪里被使用”，先用 plscope，再用 grep：PL/Scope 由编译器记录，结果精确；grep 会匹配注释和相似名称。如果 PL/Scope 没有数据，命令会说明这一点，此时再使用 grep 作为替代方案。
• src 中的行号是编译器提供的行号——错误出现在 line 47，就表示它位于 src 输出中的第 47 行。无需换算偏移量。
• 默认输出上限用于保护你的上下文窗口；仅对你当前实际处理的对象调高上限。

更深入的参考资料——这些命令使用哪些数据字典视图、如何启用 PL/Scope、许可限制：reference/data-dictionary.md。