在 VS Code 中完成 Oracle 日常开发：连接数据库、执行 SQL、结果内直接编辑并提交/回滚、导出、浏览数据库对象——对标 Oracle SQL Developer 的核心工作流。
✨ 功能特性
| 功能 |
说明 |
| 🔌 连接管理 |
登录前左侧列出全部已保存连接（名称 + 用户@目标 + 只读锁标，行内 连接/编辑/删除，点击行即登录）；基本（主机/端口/服务名）、TNS 别名（自动解析本机 tnsnames.ora）、连接串三种寻址模式；连接/用户名/密码可保存（密码仅存 VS Code 安全存储，永不明文落盘）；编辑/新建在主编辑区表单完成；只读连接保护；SYSDBA/SYSOPER 角色 |
| ⌨️ SQL 工作台 |
行号区执行镜头（每条语句「▶ 执行」+ 首行「▶▶ 执行全部」，点击即执行）；Ctrl+Enter 执行当前语句（光标定位/选区），Ctrl+Shift+Enter 脚本执行；PL/SQL 块感知的语句切分；绑定变量提示；DBMS_OUTPUT 自动回收；SQL/PLSQL 语法高亮 |
| 📊 结果网格 + 编辑 |
结果显示在 SQL 编辑器下方分栏（PL/SQL Developer 风格，每个编辑器独立结果 tab，不抢占编辑器焦点）；大表分批取数 + 虚拟滚动（首屏一批，滚动到底自动续批 OFFSET/FETCH，10 万行滚动依旧流畅，DOM 恒定为可视窗口大小；累计上限可配，全量走流式导出）；CLOB/BLOB 列支持（CLOB 文本取回 + 超长截断显示，BLOB 十六进制预览 + 字节数标注，含 LOB 的表可正常打开）；双击单元格直接编辑（类型校验）、行增删；待提交变更集（预览将执行的 DML）；提交/回滚按钮仅在存在数据变更时可用；连接断开/出错默认回滚；JOIN/聚合结果自动只读 |
| 💾 事务管理 |
Ctrl+Alt+C 提交 / Ctrl+Alt+R 回滚；状态栏事务徽标实时显示未提交更改数 |
| 📤 导出 |
CSV / XLSX / JSON / INSERT 语句 / HTML 报表；支持已加载行或全量流式重查导出 |
| 🪟 六类窗口（PL/SQL Developer 风格） |
SQL 窗口（语句/脚本）/ Test 窗口（整块 PL/SQL 运行 + :绑定变量 + DBMS_OUTPUT）/ Debug 窗口（调试对象调用，断点/单步属 M4 路线图，当前为运行语义）/ Command 窗口（SQL*Plus 风格：DESC/EXEC 命令 + 整缓冲执行）/ 执行计划窗口（EXPLAIN PLAN + DBMS_XPLAN）/ 程序窗口（编译 PL/SQL 单元，错误按 USER_ERRORS 行号标红）；识别 .sql 与 .prc/.fnc/.pkh/.pkb/.trg/.typ/.tyb 等文件后缀，打开即可用活动连接执行 |
| 🗂 对象浏览器 |
连接 → Schema → 两级对象树（类型 → 对象），默认折叠 + 按需加载（展开某类型才查库，搜索时自动全量加载并过滤）；工具栏：新建窗口下拉 / 执行 / 提交(n)/回滚(n)（仅有未提交更改时可用）/ 断开 / 刷新；表数据一键打开（可编辑）；DDL 只读视图；SELECT/INSERT 骨架生成 |
| 🧹 格式化 |
Shift+Alt+F 文档格式化 / Ctrl+K Ctrl+F 选区格式化（PL/SQL 方言、缩进/大小写可配） |
| 🐘 架构预留 |
驱动抽象层（IDbDriver）+ PostgreSQL 注册位（v1.0 实装） |
路线图（见 docs/requirements.html）：PL/SQL 调试（M4，自研 DAP 适配器）、执行计划、PostgreSQL 实装（M5）。
🚀 快速开始
1. 连接 Oracle
- 活动栏点击 SQLAdmin 图标 → 新建连接
- 选择连接模式：
- 基本：主机 + 端口(1521) + 服务名（如
XEPDB1）
- TNS 别名：自动定位本机
tnsnames.ora（查找顺序：TNS_ADMIN → %ORACLE_HOME%\network\admin → Oracle 安装目录 C:\Oracle\* / C:\app\*\product\*\dbhome_1 等 → ~\.oracle\network\admin，可在设置 sqladmin.tns.customPath 指定），列出全部别名供选择；连接时别名自动展开为完整描述符
- 连接串：Easy Connect（
host:1521/service）或完整描述符
- 输入用户名/密码 → 选择密码保存策略 → 测试连接 → 保存
Oracle 驱动为 node-oracledb thin 模式（纯 JavaScript，免安装 Oracle 客户端，支持 Oracle 12.1+）。主机/描述符中的 localhost 会自动归一化为 127.0.0.1（Windows 上 Node 优先解析 IPv6 ::1，而 Oracle 监听器常仅监听 IPv4 回环）；把 TNS 别名误填为服务名时，错误信息会提示改用「TNS 别名」模式。如需连接 Oracle 11.2 或使用客户端高级特性，在设置中切换 sqladmin.oracle.mode = thick（需本机安装 Oracle Client / Instant Client）。
2. 日常使用
Ctrl+Enter 执行光标处语句；**有选区时仅执行选中代码**（Test/Debug/Command 窗口同样支持）
Ctrl+Shift+Enter 脚本顺序执行（有选区时仅执行选中部分）
Ctrl+Alt+N 新建工作台
Ctrl+Alt+C / R 提交 / 回滚
Ctrl+Alt+V 预览待提交更改（生成的 DML）
Ctrl+Alt+E 导出结果
Shift+Alt+F 格式化 SQL
编辑数据：执行单表查询 → 结果网格中双击单元格修改（数字列自动校验）、工具栏 ＋ 行/－ 删行 → 预览更改 → 提交/回滚。所有修改先进入待提交变更集，不会立即写库。
⚙️ 设置项
| 设置 |
默认 |
说明 |
sqladmin.defaultFetchRows |
500 |
结果网格每批拉取行数 |
sqladmin.results.nullText |
(NULL) |
NULL 显示文本 |
sqladmin.results.maxLoadedRows |
100000 |
网格累计加载行数上限（达到后停止续批，导出可获取全量） |
sqladmin.results.autoFetchMore |
true |
滚动接近底部时自动续批拉取 |
sqladmin.export.batchSize |
5000 |
流式导出批大小 |
sqladmin.tns.customPath |
— |
tnsnames.ora 自定义路径 |
sqladmin.oracle.mode |
thin |
thin（免客户端）/ thick（需 Oracle Client） |
sqladmin.oracle.clientLibDir |
— |
thick 模式客户端库目录 |
sqladmin.format.tabSize |
2 |
格式化缩进宽度 |
sqladmin.format.uppercaseKeywords |
true |
格式化时关键字大写 |
🔒 安全
- 密码仅存于 VS Code SecretStorage，连接配置/导出内容永不含明文密码
- 只读连接（新建连接时可选）禁用结果编辑
- 生产环境建议使用最小权限账号
🧪 测试
npm install
npm run compile # 类型检查 + 打包
npm test # 117 个单元测试 + 25 个 VS Code 集成测试（真实 Oracle）
npm run package:vsix # 打包 vsix
集成测试通过 @vscode/test-electron 在独立 VS Code 实例中运行，全流程（连接/查询/编辑/提交/回滚/导出/对象浏览/DDL/格式化/六类窗口/.sql 文件执行）跑在真实 Oracle（默认 127.0.0.1:1521/orcl 的 HR 示例账号，可用 SQLADMIN_IT_CONN / SQLADMIN_IT_USER / SQLADMIN_IT_PASSWORD 覆盖）上；数据库不可达时整套自动跳过，不影响无 Oracle 的机器与 CI。
🗄️ 本地 Oracle 实库测试（可选）
Docker 就绪后，起一个 Oracle Database Free 容器（首次启动需等待就绪，faststart 变体约 1 分钟）：
# 镜像二选一：
# ghcr.io/gvenzl/oracle-free —— 社区构建的 Oracle Free 镜像（国内网络可直连 ghcr.io，无需登录）
docker pull ghcr.io/gvenzl/oracle-free:23-slim-faststart
docker run -d --name oracle-free -p 1521:1521 -e ORACLE_PASSWORD=SqlAdmin123 \
-v oracle-free-data:/opt/oracle/oradata ghcr.io/gvenzl/oracle-free:23-slim-faststart
# container-registry.oracle.com/database/free —— Oracle 官方镜像（网页上接受许可后需 docker login）
docker run -d --name oracle-free -p 1521:1521 -e ORACLE_PWD=SqlAdmin123 \
-v oracle-free-data:/opt/oracle/oradata container-registry.oracle.com/database/free:23.5
docker logs -f oracle-free # 等待 DATABASE IS READY TO USE!（gvenzl 镜像也可用 docker inspect 看 Health 状态）
跑实库集成测试（在 FREEPDB1 中自动重建专用测试用户并灌入标准 HR 种子数据）：
SQLADMIN_ORA_ENABLED=1 npm run test:oracle # Git Bash / Linux / macOS
# PowerShell: $env:SQLADMIN_ORA_ENABLED='1'; npm run test:oracle
实库测试默认跳过（未设置 SQLADMIN_ORA_ENABLED / SQLADMIN_ORA_CONN 时显示 pending），不影响常规 npm test 与 CI。可用环境变量：SQLADMIN_ORA_CONN（默认 127.0.0.1:1521/FREEPDB1）、SQLADMIN_ORA_PASSWORD（HR 密码，默认与 ORACLE_PWD 一致）、SQLADMIN_ORA_SYS_PASSWORD（SYSTEM 密码）。驱动走 thin 模式纯 JS 连接，测试机无需安装 Oracle 客户端。
本机环境备注（受限网络下的安装形态）：本机未装 Docker Desktop（官方源被 SNI 阻断），改为 WSL2 内运行 docker-ce：发行版 ubuntu-docker（Ubuntu 24.04，数据在 D:\WSL\ubuntu-docker），镜像 ghcr.io/gvenzl/oracle-free:23-slim-faststart 经 GitHub Actions 中继下载（docker save | zstd 发为 release 资产再 docker load）。容器 oracle-free 带 --restart unless-stopped，密码 SqlAdmin123。开机自启：注册表 HKCU\...\Run → wscript.exe ~\Downloads\sqladmin\SQLAdminOracleWSL.vbs（登录时拉起 WSL/docker/容器并保持会话；WSL 空闲会自动回收发行版，必须有常驻会话钉住）。手动启动：wsl -d ubuntu-docker 后 docker start oracle-free。
📄 许可证
Apache-2.0。第三方组件：oracledb（Apache-2.0/UPL-1.0）、exceljs（MIT）、sql-formatter（MIT）。
🔗 链接
