About pythia-explore
pythia-explore is a skill for developers investigating live database schemas and PL/SQL objects. It prioritizes querying the database over relying on potentially stale SQL exports, with commands for source, dependencies, usages, and errors.
Key features
- 01Inspect live schema and connection
- 02Read object source and signatures
- 03Explore columns and DDL
- 04Trace dependencies and impact
- 05Find exact identifier usages
- 06Check invalid objects and errors
Use cases
- 01Verify a SQL export against the live database
- 02Understand a procedure or function
- 03Find where a database object is used
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/pythia-explorein Claude Code to confirm it loaded.
Bundled filesreference/data-dictionary.md
Details
From the project READMEExploring the Schema
Announce at start: "Using pythia-explore — asking the database directly."
Phase: Learn
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.
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) |
Rules that keep answers honest
- Truncation is always announced. Outputs end with
-- truncated ...or set"truncated": truein--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. plscopebeforegrepfor "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.srcline numbers are the compiler's own — an error atline 47means line 47 insrcoutput. 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.