pythia-explore

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Exploring the Schema

探索Schema

Announce at start: "Using pythia-explore — asking the database directly."

开始时说明： "正在使用pythia-explore —— 直接向数据库查询。"

The principle: ask the database, never the dump

原则：向数据库提问，绝不依赖转储文件

Repositories of exported

.sql

files go stale the day after export. A real mid-size system, audited in 2026, compared its repo dump against the live database:

Object type	In the dump	In the database	Verdict
Procedures	3,827	3,827	matched
Tables	952	952	matched
Types	0	115	all missing
Packages	0	9	all missing
Indexes	116	1,016	~89% missing

Code that "reads fine" against the dump can reference types and packages the dump never heard of.

When the developer hands you a
.sql
file — "explain this procedure", "here is the export, what does it do" — the file is a claim, not the truth. Read it, then run

pythia src <NAME>

and answer from the database. If the two differ, say so first: which is newer is exactly what the developer needs to know, and it is invisible from the file alone. Never answer about a database object from a file alone while the database is reachable.

Read files as the answer only when the database is unreachable — and say that is what you are doing.

导出的

.sql

文件仓库在导出次日就会过时。2026年对一个真实的中型系统进行审计时，将其仓库转储文件与实时数据库进行了对比：

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

针对转储文件“看起来正常”的代码，可能引用了转储文件中从未提及的类型和包。

当开发者交给你一个
.sql
文件时 —— “解释这个存储过程”、“这是导出文件，它的作用是什么”——该文件只是一种声明，而非真相。先阅读文件，然后运行

pythia src <NAME>

并从数据库获取答案。如果两者存在差异，首先告知开发者：哪一个是最新版本正是开发者需要了解的信息，而这仅从文件本身无法得知。只要数据库可访问，绝不要仅通过文件回答关于数据库对象的问题。

只有当数据库无法访问时，才通过文件获取答案——并且要说明你正在这么做。

What you need → what you run

需求 → 对应命令

Need	Command
Is the connection alive, what schema	`pythia check`
Find objects by name	`pythia ls "PKG_%"`
Read source, with the compiler's line numbers	`pythia src NAME` ( `--body` , `--spec` )
A procedure/function signature	`pythia args NAME`
Columns and real data types	`pythia cols TABLE_NAME`
Full DDL	`pythia ddl TABLE NAME`
Search all PL/SQL text	`pythia grep "text"`
What an object depends on	`pythia deps NAME`
What depends on an object	`pythia impact NAME`
Exact identifier usages (beats grep)	`pythia plscope NAME`
Programs named like this one	`pythia similar NAME`
Everything currently broken	`pythia invalid` , `pythia errors`
A free-form question	`pythia sql "select ..."` (SELECT/WITH only)

需求	命令
连接是否正常，当前Schema是什么	`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语句）

Rules that keep answers honest

保证答案真实性的规则

Truncation is always announced. Outputs end with
```
-- truncated ...
```
or set
```
"truncated": true
```
in
```
--json
```
. If you do not see the marker, you saw everything; if you do, say so or fetch more (
```
--limit
```
,
```
--offset
```
,
```
--max-lines
```
) — never present a truncated list as complete.
plscope
before
grep
for "where is X used": PL/Scope is recorded by the compiler and exact; grep matches comments and look-alike names. If PL/Scope has no data, the command says so and grep is the fallback.
src
line numbers are the compiler's own — an error at
```
line 47
```
means line 47 in
```
src
```
output. No offset arithmetic.
Default output caps exist to protect your context window; raise them only for the object you are actually working on.

Deeper reference — which dictionary views back these commands, PL/Scope enablement, licensing boundaries:

reference/data-dictionary.md

始终说明截断情况。输出会以
```
-- truncated ...
```
结尾，或在
```
--json
```
模式下设置
```
"truncated": true
```
。如果未看到该标记，则表示你已查看全部内容；如果看到，则需说明或获取更多内容（使用
```
--limit
```
,
```
--offset
```
,
```
--max-lines
```
参数）——绝不要将截断的列表当作完整内容呈现。
查找“X在哪里被使用”时，优先使用
plscope
而非
grep
：PL/Scope由编译器记录，结果精确；grep会匹配注释和相似名称。如果PL/Scope没有数据，命令会提示，此时再使用grep作为备选。
src
输出的行号是编译器自身的行号——比如“第47行出错”指的是
```
src
```
输出中的第47行，无需进行偏移计算。
默认输出存在上限以保护你的上下文窗口；仅在处理当前实际操作的对象时才提高上限。

更深入的参考资料——这些命令对应的字典视图、PL/Scope启用方法、许可边界：

reference/data-dictionary.md

。