pythia-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Setting Up

设置流程

Announce at start: "Using pythia-setup to configure the database access."

Set up in this order: connection first (everything else needs it), the least-privilege user second (the only protection that cannot be bypassed), SQLcl MCP last (optional, reads only).

开始时告知："使用pythia-setup配置数据库访问。"

请按以下顺序进行设置：首先配置连接（其他所有操作都依赖于此），其次创建最小权限用户（这是唯一无法绕过的保护机制），最后配置SQLcl MCP（可选，仅用于读取）。

1. Connection

1. 连接配置

Create

.pythia/connections.json

at the project root —

pythia install

scaffolds it (pip installs:

pip install pythia-plsql

), or copy

examples/connections.example.json

from a clone. Fill it in. Rules pythia applies:

One entry: used as-is. Several entries: the path segment directly under the project root picks one (
```
root/DEV/...
```
→
```
DEV
```
), else the entry named by a top-level
```
"default": "<name>"
```
. Ambiguity is an error, never a guess.

--conn NAME

and

PYTHIA_CONNECTION

override everything; the

PYTHIA_USER/PYTHIA_PASSWORD/PYTHIA_DSN

variables bypass the file.

The file holds credentials: it is gitignored — keep it that way, and keep it out of chat and screenshots.

Verify with

pythia check

: it prints who you are connected as and object counts. A failure names the connection and what to check.

在项目根目录创建

.pythia/connections.json

文件——

pythia install

命令会自动生成模板（需先通过pip安装：

pip install pythia-plsql

），也可从克隆的仓库中复制

examples/connections.example.json

文件。填写文件内容时，需遵循pythia的以下规则：

若文件中只有一个条目：直接使用该条目。若有多个条目：项目根目录下的路径段会选择对应条目（如
```
root/DEV/...
```
→ 选择
```
DEV
```
条目）；若无对应路径段，则使用顶层
```
"default": "<name>"
```
指定的条目。存在歧义时会报错，不会自动猜测。
```
--conn NAME
```
参数和
```
PYTHIA_CONNECTION
```
环境变量会覆盖所有配置；
```
PYTHIA_USER/PYTHIA_PASSWORD/PYTHIA_DSN
```
变量则会绕过配置文件直接生效。
该文件存储凭证信息：已被设置为git忽略——请保持此状态，切勿将其分享至聊天或截图中。

执行

pythia check

命令验证配置：该命令会显示当前连接的用户身份及对象数量。若验证失败，会指出对应的连接及需要检查的内容。

2. The agent's database user — the real protection

2. Agent数据库用户——核心保护机制

The policy file is an application-side fence; Oracle grants are the only layer an agent cannot walk around. Oracle has no clean per-object form of "may edit PL/SQL in that schema" — compiling into another schema needs

CREATE ANY PROCEDURE

, which spans every schema on the instance.

The workable pattern is proxy authentication: a logon-only user that connects through the schema owner. The agent never learns the owner's password, revocation is one statement, the audit trail shows who really connected, and the blast radius is the one development schema.

Run

pythia agent-user --save

— ONE run, in the project directory. It prints the three-statement proxy SQL with a generated password and saves the matching credential as connection

<conn>_agent

(the new default; the owner entry stays untouched). The password is regenerated on every run, so never preview first and save later — the SQL and the saved config must come from the same run. Relay the SQL to the developer verbatim for a DBA to execute, then verify with

pythia check

--json

gives the same result machine-readable. Manual alternative:

examples/agent-user-setup.example.sql

, names adapted.

Oracle's own guidance for LLM access, follow it: grant minimum privileges, never point an LLM at a production database, audit its activity regularly.

pythia check

warns on one line when the session holds

%ANY%

privileges or runs as the schema owner directly. The goal state is: no warning.

策略文件是应用端的防护措施；Oracle权限授予是Agent无法绕过的唯一安全层。Oracle没有针对单个对象的"可编辑该模式下PL/SQL"的权限——要在其他模式下编译代码，需要

CREATE ANY PROCEDURE

权限，而该权限覆盖实例中的所有模式。

可行的模式是代理认证：创建一个仅用于登录的用户，通过模式所有者进行连接。Agent永远不会知晓所有者的密码，撤销权限只需一条语句，审计日志会显示实际连接的用户，且影响范围仅局限于单个开发模式。

在项目目录中执行

pythia agent-user --save

命令——只需执行一次。该命令会生成包含三条语句的代理SQL（附带自动生成的密码），并将匹配的凭证保存为

<conn>_agent

连接（成为新的默认连接；所有者条目保持不变）。每次执行命令都会重新生成密码，因此切勿先预览再保存——SQL语句与保存的配置必须来自同一次执行。请将生成的SQL原封不动地交给开发人员，由DBA执行，然后通过

pythia check

命令验证。使用

--json

参数可获取机器可读格式的结果。手动配置的替代方案：

examples/agent-user-setup.example.sql

，需自行调整名称。

遵循Oracle官方针对LLM访问的指导原则：授予最小权限，切勿将LLM指向生产数据库，定期审计其活动。

当会话持有

%ANY%

权限或直接以模式所有者身份运行时，

pythia check

命令会给出一行警告。目标状态是：无警告。

3. SQLcl MCP server (optional, reads only)

3. SQLcl MCP服务器（可选，仅用于读取）

If SQLcl 25.2+ is installed, agents can read through Oracle's official MCP server: command

sql -mcp

. Example client config:

json

{"mcpServers": {"sqlcl": {"command": "sql", "args": ["-mcp"]}}}

Keep the default restrict level (
```
-R 4
```
, most restrictive): it blocks host commands and
```
@
```
scripts. Note it does NOT block DML/DDL inside
```
run-sql
```
— which is why writes never go through MCP: only
```
pythia apply
```
has the snapshot, preview, verify and journal.
Built-in audit, worth telling the DBA about: every interaction lands in
```
DBTOOLS$MCP_LOG
```
;
```
V$SESSION.MODULE
```
shows the MCP client and
```
V$SESSION.ACTION
```
the LLM's name; generated SQL carries an
```
/* LLM in use */
```
comment.

若已安装SQLcl 25.2及以上版本，Agent可通过Oracle官方MCP服务器进行读取操作：执行命令

sql -mcp

。客户端配置示例：

json

{"mcpServers": {"sqlcl": {"command": "sql", "args": ["-mcp"]}}}

保持默认的限制级别（
```
-R 4
```
，最严格）：它会阻止主机命令和
```
@
```
脚本。注意：它不会阻止
```
run-sql
```
中的DML/DDL操作——这就是写入操作永远不通过MCP执行的原因：只有
```
pythia apply
```
命令具备快照、预览、验证和日志功能。
内置审计功能，建议告知DBA：所有交互都会记录在
```
DBTOOLS$MCP_LOG
```
中；
```
V$SESSION.MODULE
```
会显示MCP客户端信息，
```
V$SESSION.ACTION
```
会显示LLM的名称；生成的SQL会带有
```
/* LLM in use */
```
注释。

Done when

完成标志

```
pythia check
```
connects, shows the right schema, and prints no privilege warning.
```
pythia policy
```
prints the write policy and the rollback table.
The credentials file is untracked (
```
git status
```
does not show it).

```
pythia check
```
命令成功连接，显示正确的模式，且无权限警告。
```
pythia policy
```
命令显示写入策略和回滚表。
凭证文件未被版本跟踪（
```
git status
```
不会显示该文件）。