Oracle Query — Oracle 数据库查询助手

Overview

连接 Oracle 数据库并查找数据：执行 SELECT 查询、把结果导出为 CSV / JSON / Excel / Markdown，以及浏览数据库元数据（表列表、列详情）。基于纯 Python 的 python-oracledb thin 模式，无需安装 Oracle Client。

默认只读模式：只允许 SELECT 等查询语句；INSERT/UPDATE/DELETE/DDL 会被拦截，需显式 --allow-write。

Prerequisites

1. 安装 Python 依赖

使用 WorkBuddy 自带的托管 Python 与隔离虚拟环境（不要污染用户环境）：

C:\Users\tnkso\.workbuddy\binaries\python\versions\3.13.12\python.exe -m venv C:\Users\tnkso\.workbuddy\binaries\python\envs\default
C:\Users\tnkso\.workbuddy\binaries\python\envs\default\Scripts\pip install oracledb openpyxl

> 说明：openpyxl 仅在导出 .xlsx 时需要。脚本运行时使用：
> C:\Users\tnkso\.workbuddy\binaries\python\envs\default\Scripts\python.exe <skill-dir>/scripts/oracle_query.py ...

2. 准备连接配置（推荐）

复制模板并填入真实连接信息：

cp <skill-dir>/assets/oracle_config.example.json ~/.workbuddy/oracle_config.json

配置文件结构（详见 references/connection_guide.md）：

{
  "connections": {
    "oracle_prod": {
      "user": "apps_readonly",
      "password": "YOUR_PASSWORD",
      "host": "192.168.1.10",
      "port": 1521,
      "service_name": "PRODCDB"
    }
  }
}

也可不写配置文件，直接用命令行参数 --host/--port/--user/--password/--service-name 或环境变量 ORACLE_HOST 等直连。

Workflow（执行步骤）

1. 确认依赖已装：若未安装，先执行上面的 venv + pip 步骤。
2. 测试连接：test 子命令验证可达性与凭据。
3. 探索元数据（可选）：
   - tables --filter 'EMP%' 列出相关表
   - describe EMPLOYEES 查看列与类型
4. 执行查询：query 子命令运行 SELECT，输出表格/JSON/CSV。
5. 导出结果（可选）：export 子命令写入文件。

Usage（命令参考）

脚本位于 <skill-dir>/scripts/oracle_query.py，子命令如下：

# 测试连接（具名连接）
python oracle_query.py test --connection oracle_prod

# 直接命令行连接测试
python oracle_query.py test --host 192.168.1.10 --port 1521 --user scott --password '***' --service-name ORCLPDB1

# 列出当前用户的表（可按表名过滤）
python oracle_query.py tables --connection oracle_prod --filter 'EMP%'
# 列出所有用户的表
python oracle_query.py tables --connection oracle_prod --all

# 查看表结构
python oracle_query.py describe --connection oracle_prod EMPLOYEES

# 执行查询（表格输出，默认上限 100 行）
python oracle_query.py query --connection oracle_prod "SELECT * FROM EMPLOYEES WHERE DEPT_ID = :1" --params '[10]'
# JSON 输出
python oracle_query.py query --connection oracle_prod "SELECT EMPNO, ENAME FROM EMPLOYEES" --format json
# 提高行数上限
python oracle_query.py query --connection oracle_prod "SELECT * FROM BIG_TABLE" --limit 1000

# 导出到文件
python oracle_query.py export --connection oracle_prod "SELECT * FROM EMPLOYEES" --out result.csv
python oracle_query.py export --connection oracle_prod "SELECT * FROM EMPLOYEES" --out result.xlsx
python oracle_query.py export --connection oracle_prod "SELECT * FROM EMPLOYEES" --out result.json

安全与约束

• 只读优先：query / export 默认只接受 SELECT（及 WITH/SHOW/DESC/EXPLAIN）。写操作需 --allow-write。
• 密码不回显：所有日志中密码以 ****** 脱敏。
• 防注入：查询支持 Oracle 绑定变量（--params），避免字符串拼接。
• 凭据存储：配置文件为明文，请设置仅本人可读权限（chmod 600），不要提交到仓库。详见 references/connection_guide.md 的「安全建议」。

排错

连接或字符集问题见 references/connection_guide.md 的「常见问题」（ORA-12170 / 12514 / 01017 / 中文乱码等）。