claude-oracledb

Oracle 数据库 Claude Code 插件。连接后直接用自然语言提问，Claude 自动生成 SQL、查询数据库、返回结果，无需手动编写查询语句。

兼容 Oracle 11g+（含 Thick 模式），支持 npm 安装。

功能概览

• 自然语言查询：直接说「昨天有多少订单？」，Claude 自动查库回答
• 后台连接池：oracledb-daemon 常驻后台，连接复用，无重复握手开销
• Schema 智能注入：按语义相似度筛选相关表注入上下文，减少 token 消耗
• SQL 验证：基于 AST 的语法检查，正确识别 Oracle 特有语法（SYSDATE、ROWNUM、NVL 等）
• 权限分级：SELECT 自动执行，DML 需确认，DDL 默认拒绝
• EXPLAIN PLAN：SQL 性能分析与优化建议
• 项目配置自动检测：扫描 .env、application.yml、tnsnames.ora 等自动填充连接参数
• Oracle 11g 支持：通过可配置下载地址安装 Instant Client（Thick 模式）

安装

通过 Claude Code 插件系统

/plugin install claude-oracledb
/reload-plugins

本地开发安装

git clone https://github.com/your-name/claude-oracledb
cd claude-oracledb
npm install

在 Claude Code 设置中将插件目录指向本地路径。

快速开始

1. 连接数据库

/oracledb:connect

插件会自动扫描项目目录中的数据库配置文件。找到后询问是否使用，未找到则引导手动输入。连接成功后自动缓存表结构。

2. 自然语言提问

连接成功后，直接提问即可：

昨天有多少新订单？
本月各地区的销售额分别是多少？
用户表中注册时间最近的 10 条记录？

Claude 检测到数据相关问题后，自动调用 oracledb-cli 查询数据库，无需任何额外指令。

3. 断开连接

/oracledb:disconnect

或会话结束时自动清理。

Skills（显式命令）

| 命令 | 说明 | |------|------| | /oracledb:connect | 连接向导：自动检测配置 → 建立连接 → 缓存表结构 | | /oracledb:query | 执行 SELECT 查询 | | /oracledb:execute | 执行 DML/DDL（含权限确认）| | /oracledb:analyze | SQL 性能分析（EXPLAIN PLAN + 优化建议）| | /oracledb:validate | SQL 语法与安全性检查 | | /oracledb:schema | 查看表结构（含列类型、约束、索引）| | /oracledb:setup | 安装 Oracle Instant Client（Oracle 11g 必需）|

Oracle 11g 支持

Oracle 11g 需要 Thick 模式，必须安装 Instant Client。

方式一：插件自动下载（推荐）

在插件配置中填写下载地址：

instant_client_download_url = https://your-mirror/instantclient-basic-windows.zip

支持格式：

• HTTPS 直链（Oracle 官网登录后复制，或企业内网镜像）
• file:///D:/downloads/instantclient.zip（本地文件）
• \\server\share\instantclient.zip（UNC 路径）

配置后运行 /oracledb:setup 自动完成下载和安装。

方式二：手动指定路径

已有 Instant Client 的情况下，在插件配置中直接填写目录：

instant_client_lib = D:\oracle\instantclient_21_13

Oracle 官网下载

访问 Oracle Instant Client Downloads，需要 Oracle 账号登录，选择 Basic 包（instantclient-basic-windows.x64-XX.X.X.X.X.zip）。

CLI 命令参考

插件通过 oracledb-cli 与数据库交互，也可直接在终端调用：

# 连接管理
oracledb-cli configure <host> <port> <service> <user> [password]
oracledb-cli status
oracledb-cli disconnect

# 查询
oracledb-cli query "SELECT * FROM orders WHERE ROWNUM <= 10"
oracledb-cli execute "UPDATE orders SET status='shipped' WHERE id=1" --force

# 表结构
oracledb-cli tables
oracledb-cli schema ORDERS
oracledb-cli schema-dump

# 分析与验证
oracledb-cli analyze "SELECT * FROM orders o JOIN customers c ON o.cust_id=c.id"
oracledb-cli validate "SELECT SYSDATE FROM DUAL"

# Instant Client 安装
oracledb-cli setup --url "file:///D:/downloads/instantclient.zip"

自动识别机制

每条用户消息发送前，Hook 脚本自动检测是否包含数据查询意图：

用户: 「本月销售额是多少？」
        ↓
UserPromptSubmit Hook 触发
        ↓
关键词匹配（多少/统计/金额/count/total...）
        ↓
按语义相似度筛选相关表（如 ORDERS、SALES）
        ↓
注入上下文：已连接数据库 + 相关表结构
        ↓
Claude 生成 SQL → oracledb-cli query → 返回结果

未连接数据库时 Hook 静默跳过，不影响普通对话。

权限控制

| 操作类型 | 包含语句 | 默认行为 | |---------|---------|---------| | read | SELECT | 自动执行 | | write | INSERT / UPDATE / DELETE / MERGE | 展示风险说明，需加 --force 确认 | | admin | DDL / GRANT / TRUNCATE / DROP | 默认拒绝，需加 --admin-confirm |

配置文件自动检测

/oracledb:connect 会扫描项目目录中的以下文件（最多 4 层深度）：

| 文件 | 检测的配置 | |------|-----------| | .env / .env.* | DB_HOST、DB_USER、DB_PASSWORD、DB_SERVICE 等 | | application.properties | Spring Boot JDBC URL | | application.yml | Spring Boot 数据源配置 | | tnsnames.ora | TNS 别名（Thick 模式 TNS_ADMIN 路径）| | appsettings.json | .NET Oracle 连接字符串 |

系统要求

• Node.js >= 18.0.0
• Claude Code 最新版
• Oracle 数据库 12.1+（Thin 模式）或 11g+（Thick 模式，需 Instant Client）
• 操作系统：Windows、macOS、Linux

项目结构

├── bin/
│   ├── oracledb-cli        # CLI 入口
│   └── oracledb-daemon     # 连接池后台进程
├── src/
│   ├── cli.js            # 子命令路由
│   ├── daemon.js         # Daemon 服务端（连接池）
│   ├── ipc.js            # IPC 客户端
│   ├── connection.js     # Oracle 连接管理
│   ├── config.js         # 配置持久化
│   ├── detector.js       # 项目配置自动检测
│   ├── permission.js     # SQL 权限分级
│   ├── validator.js      # SQL 合法性检查（AST）
│   ├── analyzer.js       # EXPLAIN PLAN 分析
│   └── setup.js          # Instant Client 安装
├── skills/               # Claude Code Skills
├── agents/               # oracle-agent（自动路由）
├── hooks/                # UserPromptSubmit Hook
└── .claude-plugin/       # 插件清单

License

MIT