DBX Oracle Go Agent 实战指南用 go-ora/v2 构建纯 Go 原生 Oracle 数据库 Agent【免费下载链接】dbx20 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx本文基于 DBX 仓库中的 agents/drivers/oracle-go/README.md 及同目录源码展开。DBX 通过 Agent 机制对接 90 数据库其中 Oracle 除了传统 JDBC Agentagent.jar外还提供了一款基于github.com/sijms/go-ora/v2的实验性原生 Go Agent。读完本文你将掌握如何编译与交叉编译该 Agent、如何将其接入本机 DBX 的 Oracle 驱动目录、Agent 与 DBX 之间的 JSON-RPC 会话协议、连接串JDBC/TNS/SYSDBA的底层解析逻辑以及其元数据、分页查询、事务、DDL 提取与执行计划等核心能力背后的实现原理。一、模块定位原生 Go Agent 在 DBX Agent 体系中的角色DBX 的 Agent 体系定义在 agents/docs/agent-authoring.md 中每个 Agent 是一个独立进程通过stdin/stdout 上的 JSON-RPC 2.0与 DBX 主程序通信向 DBX 暴露connect、testConnection、listDatabases、listSchemas、listTables、getColumns、listIndexes、listForeignKeys、listTriggers、executeQuery、disconnect等统一能力。绝大多数 Agent 是 JVM 进程而 agents/drivers/oracle-go/ 是少数非 JDBC 协议的原生实现它直接用 Go 的database/sql接口驱动 go-ora/v2 与 Oracle 服务器通信。该模块的核心文件包括main.goAgent 主体约 5455 行包含 JSON-RPC 服务端、多会话运行时、连接串构建、元数据查询、分页查询、事务、DDL 提取、执行计划、值规范化等全部逻辑tns.goOracle TNStnsnames.ora别名解析与 DSN 构建main_test.go约 4097 行的协议与行为测试tns_test.goTNS 解析专项测试go.modgo 1.20依赖github.com/sijms/go-ora/v2 v2.9.0与golang.org/x/text v0.22.0。从main.go的handshake返回可以看出Agent 对外声明的能力包括connect、test_connection、metadata、query、transaction、ddl在多会话运行时下还追加multi_session。测试 main_test.go 会校验 handshake 返回的协议版本与能力集合必须落在协议契约内。二、编译与交叉构建原文档给出最简构建方式在 agents/drivers/oracle-go/ 目录下执行go build -o agent .更常用的是发布级交叉编译。由于 go-ora/v2 是纯 Go 实现的 Oracle 协议驱动不依赖 CGO因此可以在任意平台为 Linux / macOS / Windows 产出原生二进制CGO_ENABLED0 GOOSlinux GOARCHamd64 go build -trimpath -ldflags-s -w -o dbx-agent-oracle-linux-x64 . CGO_ENABLED0 GOOSdarwin GOARCHarm64 go build -trimpath -ldflags-s -w -o dbx-agent-oracle-macos-aarch64 . CGO_ENABLED0 GOOSwindows GOARCHamd64 go build -trimpath -ldflags-s -w -o dbx-agent-oracle-windows-x64.exe .参数含义CGO_ENABLED0强制纯 Go 输出保证跨平台可移植性go-ora/v2 无需 CGOGOOS/GOARCH目标操作系统与 CPU 架构如 linux-amd64、darwin-arm64、windows-amd64-trimpath去除构建机器上的绝对路径保证可复现构建-ldflags-s -w去掉符号表与调试信息显著缩小二进制体积-o输出文件名。命名遵循dbx-agent-oracle-平台-架构惯例。三、接入本地 DBX安装位置、优先级与还原原文档说明构建完成后把二进制放入 DBX 已安装的 Oracle 驱动目录即可完成本地联调mkdir -p ~/.dbx/agents/drivers/oracle cp agent ~/.dbx/agents/drivers/oracle/agent chmod x ~/.dbx/agents/drivers/oracle/agent要点DBX 在同一个驱动目录下优先选择名为agent的可执行文件而不是agent.jar。因此只要该文件存在Oracle 连接就会自动走这个 Go Agent想要恢复 Java Agent删除该文件即可rm ~/.dbx/agents/drivers/oracle/agent从仓库的发布脚本 agents/scripts/build_driver_zips.py 与校验脚本 agents/scripts/validate_agents.py 可以看出DBX 的 Agent 发布体系同时管理 JVM Agentshadow JAR与原生 Agent 两种形态本模块以纯 Go 单二进制形态出现正是原生 Agent 的典型代表。四、连接能力与 DSN 构建原理Agent 的连接参数结构见 main.go为字段JSON 键说明HosthostOracle 服务器地址Portport端口缺省时按1521处理Databasedatabase数据库/服务名以SYSDBA:为前缀时会被剥离后作为服务名Usernameusername用户名Passwordpassword密码SysDBAsysdba是否以 SYSDBA 身份连接URLParamsurl_paramsgo-ora 连接参数键值对ConnectionStringconnection_string可选的完整连接串4.1 DSN 的三种形态buildDSNmain.go按优先级处理三类输入oracle://原生 URL直接解析并注入默认参数后返回JDBC URL 兼容识别jdbc:oracle:thin:前缀通过正则main.go区分四种写法jdbc:oracle:thin://host:port/service→ service 模式jdbc:oracle:thin:host:port:sid→ SID 模式options[SID]jdbc:oracle:thin:host:port/service→ 兼容旧写法按 service 处理jdbc:oracle:thin:(DESCRIPTION...)→ 直接内联描述符descriptor。普通 Host/Port/Database 字段拼装oracle://user:passhost:port/service形式。4.2 TNStnsnames.ora支持tns.go 实现了完整的 TNS 别名解析当connection_string形如jdbc:oracle:thin:ALIAS?TNS_ADMIN/path/to/dir时Agent 会读取TNS_ADMIN目录下的tnsnames.ora解析出对应别名的描述符并交给 go-ora 使用。实现要点支持IFILE嵌套引入深度上限 8 层循环引用会被检测解析器按括号深度识别多行描述符支持#注释与引号包裹的内容别名不区分大小写统一转大写比对未找到时返回形如Oracle TNS alias MISSING was not found的明确错误TNS_ADMIN缺失、目录不可访问、tnsnames.ora不存在时都有对应错误信息相关行为被 tns_test.go 覆盖。4.3 SYSDBA 与默认预取当sysdbatrue时DSN 中注入AUTH TYPESYSDBAgo-ora 连接默认注入PREFETCH_ROWS256main.go注释解释为数据网格每页约 100 行预取略超一页可在翻页时减少往返若调用方已显式配置prefetch_rows则不再注入默认值见 tns_test.go。4.4 连接池与会话初始化openDBWithStringConvertermain.go创建连接池时设置MaxOpenConns4、MaxIdleConns1、ConnMaxLifetime30min。连接建立后统一执行ALTER SESSION SET NLS_LANGUAGEAMERICANmain.go保证元数据与错误信息语言稳定连接阶段还会在 15 秒超时内探测 Oracle 主版本号用于后续的 LOB 兼容策略见第六节。五、会话协议单会话 v1 与多会话 v2 运行时该 Agent 同时实现了两代协议v1单会话handshake返回protocolVersion: 1能力为connect/test_connection/metadata/query/transaction/ddl所有请求走一个隐式 legacy 会话agentSessionId缺省为__legacy__v2多会话运行时runtimeServer.handshake返回protocolVersion: 2并追加multi_session能力main.go。这与 agents/docs/agent-protocol-v2.md 定义的一个进程服务多个隔离逻辑会话模型一致。v2 运行时提供以下会话级 RPCmain.goopen_session创建逻辑会话并建立数据库连接缺省上限maxAgentSessions 256close_session只关闭指定会话的连接与游标validate_session校验会话失败时仅重连该逻辑会话不影响其他会话cancel_session仅取消目标会话的活动查询shutdown关闭全部会话并退出进程。并发模型上不同会话的请求可并行执行同一会话的请求被串行化每个agentSession一把互斥锁因为 Oracle 连接状态、事务、schema 变更和驱动连接并发不安全main.go。主循环读取 stdin 时使用 512 MB 缓冲区并为每个请求启动 goroutine 并发处理响应按请求id关联、可乱序返回main.go任何请求路径上的 panic 都会被恢复为可读错误响应避免进程退出导致 RPC 流中断。六、兼容性设计字符集、LOB 与版本探测字符集回退连接 ping 失败时若错误匹配server use charset with id: N not supported by the driverAgent 会为该 charset ID 查找显式注册的转换器后重试main.go。目前内置了ZHS32GB18030charset 854的 GB18030 转换器实现 Encode/Decodemain.go注释明确强调只对显式转换器的字符集重试猜测转换器可能让连接成功却静默损坏文本。老版本 LOB 兼容通过PRODUCT_COMPONENT_VERSION或V$VERSION探测 Oracle 主版本当主版本 ≤ 10 且未显式配置 LOB 选项时会推迟到第一次读取 LOB 的方法get_table_ddl、execute_query等之前用LOB FETCHPOST重建连接main.go绕开老版本服务器的 LOB 读取限制。值规范化RAW/LOB 二进制列按十六进制0x...输出main_test.goDATE/TIMESTAMP 输出为墙钟时间NaN/Inf等非有限浮点数在 JSON 序列化时转为字符串保证 JSON 安全且不修改原始行main_test.go。驱动 panic 兜底go-ora 解码某些不支持列类型如自定义对象类型时可能 panicAgent 在翻页读取路径上把 panic 转成oracleDriverPanicError并尝试用占位投影重写 SQL 重试让其余列保持可读main.go。类似的还有 XMLType 列改写、SDE 空间扩展ORA-28595占位回退等策略。七、元数据能力从库、模式到触发器Agent 的元数据全部通过 Oracle 数据字典实现且大量使用绑定参数:1、:2等防止注入listDatabases / listSchemas查询ALL_USERSlistDatabases会过滤 SYS/SYSTEM/SYSMAN/APEX_% 等系统用户main.go并优先把当前 schema 与当前会话用户排在前面listTables / listObjects分别通过ALL_TABLES/ALL_VIEWS/ALL_MVIEWS与ALL_OBJECTS聚合输出 TABLE、VIEW、MATERIALIZED_VIEW以及 PROCEDURE、FUNCTION、SEQUENCE、PACKAGE、PACKAGE_BODY、SYNONYM 等对象类型main.go当目标 schema 是当前会话用户时切换为USER_*字典以提升性能支持 filter 模糊匹配、object_types 过滤以及基于ROWNUM的 limit/offset 分页getColumns以ALL_TAB_COLUMNS为主表左连主键约束与ALL_COL_COMMENTS按COLUMN_ID排序返回可空性、默认值、主键标志、精度/标度、字符长度及单位BYTE/CHAR等完整信息main.golistIndexes / listForeignKeys分别通过ALL_INDEXESALL_IND_COLUMNS保留列顺序和ALL_CONSTRAINTSALL_CONS_COLUMNS输出listConstraints返回主键、唯一、CHECK 约束由于 Oracle 会把每个 NOT NULL 列生成为系统 CHECK 约束COL IS NOT NULLAgent 在 Go 侧排除这类系统生成的约束只保留用户可识别的约束main.golistTriggers通过ALL_TRIGGERS左连ALL_SOURCE拼接触发器体并尽量剥离ALL_TRIGGERS.DESCRIPTION中重复的头部main.go对象源码与 DDLget_object_source对 VIEW 走ALL_VIEWS.TEXT对物化视图/序列/同义词走DBMS_METADATA.GET_DDL对过程/函数/包走ALL_SOURCE聚合标识符处理上先尝试调用方提供的精确大小写带引号混合大小写对象名再回退到大写形式。另外值得注意的是当ALL_USERS等大字典查询触发ORA-04036PGA 内存限制错误时Agent 会降级为只返回当前 schema保证树形浏览不中断main.go。八、查询执行与分页会话8.1 一次性查询execute_querymain.go的行为若传入schema且未打开手工事务先执行ALTER SESSION SET CURRENT_SCHEMA对 SELECT 类语句走结果集路径行数上限默认defaultMaxRows 1000超出即置truncatedtruemaxRows可覆盖对非 SELECT 语句DML/DDL/PL/SQL 块走ExecContext返回受影响行数timeoutSecs 0时通过time.AfterFunc建立取消计时器超时即取消上下文对 PL/SQL 块DECLARE/BEGIN/CREATE OR REPLACE ...有专门的正则识别与结尾检测支持多语句场景。8.2 分页与表读取为适配数据网格翻页Agent 实现了服务端游标式分页execute_query_pagefetch_query_page第一次执行返回第一页并持有querySessionsessionID形如oracle-go-N后续用sessionId拉取下一页has_more指示是否还有数据start_table_readfetch_table_read_page数据表全量读取专用的并行会话oracle-go-table-N关闭会话方法幂等对不存在的会话返回空页或false不会报错main_test.go翻页判定做了优化读满一页即认为可能还有下一页避免为判断has_more多读一行而引入额外 Oracle 往返main.go。8.3 执行计划get_explain_infomain.go通过EXPLAIN PLAN SET STATEMENT_ID DBX_...DBMS_XPLAN.DISPLAY(PLAN_TABLE, :1, TYPICAL PREDICATE)生成计划文本它会在独立连接上临时切换CURRENT_SCHEMA到目标 schema结束后还原自动解析 SQL 中的位置绑定与命名绑定参数跳过字符串、引号标识符、注释与q...替代引用执行完清理 PLAN_TABLE避免残留。九、事务与 DDL 导出9.1 事务一次性事务execute_transaction接收语句列表在一个db.Begin()事务内顺序执行并统一提交/回滚返回累计受影响行数main.go手工交互式事务begin_manual_transaction会从连接池取出独占的一条物理连接并BeginTx之后的execute_query全部运行在该事务上直到commit_manual_transaction/rollback_manual_transaction结束main.go。这符合 agents/docs/agent-protocol-v2.md 对交互式事务pin one physical connection的约定断连时也会静默回滚未完成的手工事务。9.2 DDL 提取get_table_ddlmain.go优先调用DBMS_METADATA.GET_DDLportabletrue时会先DBMS_METADATA.SET_TRANSFORM_PARAM(..., SEGMENT_ATTRIBUTES, FALSE)禁用段属性输出更干净、可移植的 DDL之后恢复设置。输出结果会继续追加非主键/唯一约束生成的用户索引 DDLDBMS_METADATA.GET_DDL(INDEX, ...)表触发器 DDL表与列注释COMMENT ON TABLE/COLUMN ... IS ...。当DBMS_METADATA失败时会降级为基于getColumns元数据手工拼装CREATE TABLE ...并附带主键、默认值、NOT NULL 与精度/标度信息main.go视图 DDL 则优先取ALL_VIEWS.TEXT再拼CREATE OR REPLACE VIEW schema.view AS ...并正确追加视图注释。get_table_ddl的结果以 JSON 字符串返回main_test.go保证前端可直接回填到 SQL 编辑器。十、测试与质量保障该模块的测试与协议契约绑定紧密main_test.go 校验 handshake 版本与能力集合、多会话运行时行为关闭一个会话不影响其他会话、cancel_session只取消目标会话、空结果集 JSON 序列化columns/rows必须输出[]而非null、RAW 十六进制格式化、非有限浮点转字符串、日期时间墙钟输出等tns_test.go 覆盖 TNS 别名解析、失败转移描述符保留、prefetch_rows覆盖、缺失TNS_ADMIN、未知别名、非法目录等错误路径。发布前还可运行仓库的 Agent 校验脚本 agents/scripts/validate_agents.py 做整体校验。十一、适用前提与限制该 Agent 在 README 中被明确标注为Experimental实验性接入生产环境前请充分验证依赖go 1.20与github.com/sijms/go-ora/v2 v2.9.0见 go.mod与 DBX 的通信完全依赖 JSON-RPC 协议版本升级 DBX 后应重新核对 handshake 返回的协议版本与能力集合本地联调时~/.dbx/agents/drivers/oracle/agent会覆盖同名目录下的 Java Agentagent.jar删除该文件即可还原交叉编译产物命名建议沿用dbx-agent-oracle-平台-架构的惯例便于与发布脚本集成。如需深入协议细节可继续阅读 agents/docs/agent-protocol-v2.md多会话运行时模型与 agents/docs/agent-authoring.mdAgent 编写规范与审查清单。【免费下载链接】dbx20 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DBX Oracle Go Agent 实战指南：用 go-ora/v2 构建纯 Go 原生 Oracle 数据库 Agent
DBX Oracle Go Agent 实战指南用 go-ora/v2 构建纯 Go 原生 Oracle 数据库 Agent【免费下载链接】dbx20 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx本文基于 DBX 仓库中的 agents/drivers/oracle-go/README.md 及同目录源码展开。DBX 通过 Agent 机制对接 90 数据库其中 Oracle 除了传统 JDBC Agentagent.jar外还提供了一款基于github.com/sijms/go-ora/v2的实验性原生 Go Agent。读完本文你将掌握如何编译与交叉编译该 Agent、如何将其接入本机 DBX 的 Oracle 驱动目录、Agent 与 DBX 之间的 JSON-RPC 会话协议、连接串JDBC/TNS/SYSDBA的底层解析逻辑以及其元数据、分页查询、事务、DDL 提取与执行计划等核心能力背后的实现原理。一、模块定位原生 Go Agent 在 DBX Agent 体系中的角色DBX 的 Agent 体系定义在 agents/docs/agent-authoring.md 中每个 Agent 是一个独立进程通过stdin/stdout 上的 JSON-RPC 2.0与 DBX 主程序通信向 DBX 暴露connect、testConnection、listDatabases、listSchemas、listTables、getColumns、listIndexes、listForeignKeys、listTriggers、executeQuery、disconnect等统一能力。绝大多数 Agent 是 JVM 进程而 agents/drivers/oracle-go/ 是少数非 JDBC 协议的原生实现它直接用 Go 的database/sql接口驱动 go-ora/v2 与 Oracle 服务器通信。该模块的核心文件包括main.goAgent 主体约 5455 行包含 JSON-RPC 服务端、多会话运行时、连接串构建、元数据查询、分页查询、事务、DDL 提取、执行计划、值规范化等全部逻辑tns.goOracle TNStnsnames.ora别名解析与 DSN 构建main_test.go约 4097 行的协议与行为测试tns_test.goTNS 解析专项测试go.modgo 1.20依赖github.com/sijms/go-ora/v2 v2.9.0与golang.org/x/text v0.22.0。从main.go的handshake返回可以看出Agent 对外声明的能力包括connect、test_connection、metadata、query、transaction、ddl在多会话运行时下还追加multi_session。测试 main_test.go 会校验 handshake 返回的协议版本与能力集合必须落在协议契约内。二、编译与交叉构建原文档给出最简构建方式在 agents/drivers/oracle-go/ 目录下执行go build -o agent .更常用的是发布级交叉编译。由于 go-ora/v2 是纯 Go 实现的 Oracle 协议驱动不依赖 CGO因此可以在任意平台为 Linux / macOS / Windows 产出原生二进制CGO_ENABLED0 GOOSlinux GOARCHamd64 go build -trimpath -ldflags-s -w -o dbx-agent-oracle-linux-x64 . CGO_ENABLED0 GOOSdarwin GOARCHarm64 go build -trimpath -ldflags-s -w -o dbx-agent-oracle-macos-aarch64 . CGO_ENABLED0 GOOSwindows GOARCHamd64 go build -trimpath -ldflags-s -w -o dbx-agent-oracle-windows-x64.exe .参数含义CGO_ENABLED0强制纯 Go 输出保证跨平台可移植性go-ora/v2 无需 CGOGOOS/GOARCH目标操作系统与 CPU 架构如 linux-amd64、darwin-arm64、windows-amd64-trimpath去除构建机器上的绝对路径保证可复现构建-ldflags-s -w去掉符号表与调试信息显著缩小二进制体积-o输出文件名。命名遵循dbx-agent-oracle-平台-架构惯例。三、接入本地 DBX安装位置、优先级与还原原文档说明构建完成后把二进制放入 DBX 已安装的 Oracle 驱动目录即可完成本地联调mkdir -p ~/.dbx/agents/drivers/oracle cp agent ~/.dbx/agents/drivers/oracle/agent chmod x ~/.dbx/agents/drivers/oracle/agent要点DBX 在同一个驱动目录下优先选择名为agent的可执行文件而不是agent.jar。因此只要该文件存在Oracle 连接就会自动走这个 Go Agent想要恢复 Java Agent删除该文件即可rm ~/.dbx/agents/drivers/oracle/agent从仓库的发布脚本 agents/scripts/build_driver_zips.py 与校验脚本 agents/scripts/validate_agents.py 可以看出DBX 的 Agent 发布体系同时管理 JVM Agentshadow JAR与原生 Agent 两种形态本模块以纯 Go 单二进制形态出现正是原生 Agent 的典型代表。四、连接能力与 DSN 构建原理Agent 的连接参数结构见 main.go为字段JSON 键说明HosthostOracle 服务器地址Portport端口缺省时按1521处理Databasedatabase数据库/服务名以SYSDBA:为前缀时会被剥离后作为服务名Usernameusername用户名Passwordpassword密码SysDBAsysdba是否以 SYSDBA 身份连接URLParamsurl_paramsgo-ora 连接参数键值对ConnectionStringconnection_string可选的完整连接串4.1 DSN 的三种形态buildDSNmain.go按优先级处理三类输入oracle://原生 URL直接解析并注入默认参数后返回JDBC URL 兼容识别jdbc:oracle:thin:前缀通过正则main.go区分四种写法jdbc:oracle:thin://host:port/service→ service 模式jdbc:oracle:thin:host:port:sid→ SID 模式options[SID]jdbc:oracle:thin:host:port/service→ 兼容旧写法按 service 处理jdbc:oracle:thin:(DESCRIPTION...)→ 直接内联描述符descriptor。普通 Host/Port/Database 字段拼装oracle://user:passhost:port/service形式。4.2 TNStnsnames.ora支持tns.go 实现了完整的 TNS 别名解析当connection_string形如jdbc:oracle:thin:ALIAS?TNS_ADMIN/path/to/dir时Agent 会读取TNS_ADMIN目录下的tnsnames.ora解析出对应别名的描述符并交给 go-ora 使用。实现要点支持IFILE嵌套引入深度上限 8 层循环引用会被检测解析器按括号深度识别多行描述符支持#注释与引号包裹的内容别名不区分大小写统一转大写比对未找到时返回形如Oracle TNS alias MISSING was not found的明确错误TNS_ADMIN缺失、目录不可访问、tnsnames.ora不存在时都有对应错误信息相关行为被 tns_test.go 覆盖。4.3 SYSDBA 与默认预取当sysdbatrue时DSN 中注入AUTH TYPESYSDBAgo-ora 连接默认注入PREFETCH_ROWS256main.go注释解释为数据网格每页约 100 行预取略超一页可在翻页时减少往返若调用方已显式配置prefetch_rows则不再注入默认值见 tns_test.go。4.4 连接池与会话初始化openDBWithStringConvertermain.go创建连接池时设置MaxOpenConns4、MaxIdleConns1、ConnMaxLifetime30min。连接建立后统一执行ALTER SESSION SET NLS_LANGUAGEAMERICANmain.go保证元数据与错误信息语言稳定连接阶段还会在 15 秒超时内探测 Oracle 主版本号用于后续的 LOB 兼容策略见第六节。五、会话协议单会话 v1 与多会话 v2 运行时该 Agent 同时实现了两代协议v1单会话handshake返回protocolVersion: 1能力为connect/test_connection/metadata/query/transaction/ddl所有请求走一个隐式 legacy 会话agentSessionId缺省为__legacy__v2多会话运行时runtimeServer.handshake返回protocolVersion: 2并追加multi_session能力main.go。这与 agents/docs/agent-protocol-v2.md 定义的一个进程服务多个隔离逻辑会话模型一致。v2 运行时提供以下会话级 RPCmain.goopen_session创建逻辑会话并建立数据库连接缺省上限maxAgentSessions 256close_session只关闭指定会话的连接与游标validate_session校验会话失败时仅重连该逻辑会话不影响其他会话cancel_session仅取消目标会话的活动查询shutdown关闭全部会话并退出进程。并发模型上不同会话的请求可并行执行同一会话的请求被串行化每个agentSession一把互斥锁因为 Oracle 连接状态、事务、schema 变更和驱动连接并发不安全main.go。主循环读取 stdin 时使用 512 MB 缓冲区并为每个请求启动 goroutine 并发处理响应按请求id关联、可乱序返回main.go任何请求路径上的 panic 都会被恢复为可读错误响应避免进程退出导致 RPC 流中断。六、兼容性设计字符集、LOB 与版本探测字符集回退连接 ping 失败时若错误匹配server use charset with id: N not supported by the driverAgent 会为该 charset ID 查找显式注册的转换器后重试main.go。目前内置了ZHS32GB18030charset 854的 GB18030 转换器实现 Encode/Decodemain.go注释明确强调只对显式转换器的字符集重试猜测转换器可能让连接成功却静默损坏文本。老版本 LOB 兼容通过PRODUCT_COMPONENT_VERSION或V$VERSION探测 Oracle 主版本当主版本 ≤ 10 且未显式配置 LOB 选项时会推迟到第一次读取 LOB 的方法get_table_ddl、execute_query等之前用LOB FETCHPOST重建连接main.go绕开老版本服务器的 LOB 读取限制。值规范化RAW/LOB 二进制列按十六进制0x...输出main_test.goDATE/TIMESTAMP 输出为墙钟时间NaN/Inf等非有限浮点数在 JSON 序列化时转为字符串保证 JSON 安全且不修改原始行main_test.go。驱动 panic 兜底go-ora 解码某些不支持列类型如自定义对象类型时可能 panicAgent 在翻页读取路径上把 panic 转成oracleDriverPanicError并尝试用占位投影重写 SQL 重试让其余列保持可读main.go。类似的还有 XMLType 列改写、SDE 空间扩展ORA-28595占位回退等策略。七、元数据能力从库、模式到触发器Agent 的元数据全部通过 Oracle 数据字典实现且大量使用绑定参数:1、:2等防止注入listDatabases / listSchemas查询ALL_USERSlistDatabases会过滤 SYS/SYSTEM/SYSMAN/APEX_% 等系统用户main.go并优先把当前 schema 与当前会话用户排在前面listTables / listObjects分别通过ALL_TABLES/ALL_VIEWS/ALL_MVIEWS与ALL_OBJECTS聚合输出 TABLE、VIEW、MATERIALIZED_VIEW以及 PROCEDURE、FUNCTION、SEQUENCE、PACKAGE、PACKAGE_BODY、SYNONYM 等对象类型main.go当目标 schema 是当前会话用户时切换为USER_*字典以提升性能支持 filter 模糊匹配、object_types 过滤以及基于ROWNUM的 limit/offset 分页getColumns以ALL_TAB_COLUMNS为主表左连主键约束与ALL_COL_COMMENTS按COLUMN_ID排序返回可空性、默认值、主键标志、精度/标度、字符长度及单位BYTE/CHAR等完整信息main.golistIndexes / listForeignKeys分别通过ALL_INDEXESALL_IND_COLUMNS保留列顺序和ALL_CONSTRAINTSALL_CONS_COLUMNS输出listConstraints返回主键、唯一、CHECK 约束由于 Oracle 会把每个 NOT NULL 列生成为系统 CHECK 约束COL IS NOT NULLAgent 在 Go 侧排除这类系统生成的约束只保留用户可识别的约束main.golistTriggers通过ALL_TRIGGERS左连ALL_SOURCE拼接触发器体并尽量剥离ALL_TRIGGERS.DESCRIPTION中重复的头部main.go对象源码与 DDLget_object_source对 VIEW 走ALL_VIEWS.TEXT对物化视图/序列/同义词走DBMS_METADATA.GET_DDL对过程/函数/包走ALL_SOURCE聚合标识符处理上先尝试调用方提供的精确大小写带引号混合大小写对象名再回退到大写形式。另外值得注意的是当ALL_USERS等大字典查询触发ORA-04036PGA 内存限制错误时Agent 会降级为只返回当前 schema保证树形浏览不中断main.go。八、查询执行与分页会话8.1 一次性查询execute_querymain.go的行为若传入schema且未打开手工事务先执行ALTER SESSION SET CURRENT_SCHEMA对 SELECT 类语句走结果集路径行数上限默认defaultMaxRows 1000超出即置truncatedtruemaxRows可覆盖对非 SELECT 语句DML/DDL/PL/SQL 块走ExecContext返回受影响行数timeoutSecs 0时通过time.AfterFunc建立取消计时器超时即取消上下文对 PL/SQL 块DECLARE/BEGIN/CREATE OR REPLACE ...有专门的正则识别与结尾检测支持多语句场景。8.2 分页与表读取为适配数据网格翻页Agent 实现了服务端游标式分页execute_query_pagefetch_query_page第一次执行返回第一页并持有querySessionsessionID形如oracle-go-N后续用sessionId拉取下一页has_more指示是否还有数据start_table_readfetch_table_read_page数据表全量读取专用的并行会话oracle-go-table-N关闭会话方法幂等对不存在的会话返回空页或false不会报错main_test.go翻页判定做了优化读满一页即认为可能还有下一页避免为判断has_more多读一行而引入额外 Oracle 往返main.go。8.3 执行计划get_explain_infomain.go通过EXPLAIN PLAN SET STATEMENT_ID DBX_...DBMS_XPLAN.DISPLAY(PLAN_TABLE, :1, TYPICAL PREDICATE)生成计划文本它会在独立连接上临时切换CURRENT_SCHEMA到目标 schema结束后还原自动解析 SQL 中的位置绑定与命名绑定参数跳过字符串、引号标识符、注释与q...替代引用执行完清理 PLAN_TABLE避免残留。九、事务与 DDL 导出9.1 事务一次性事务execute_transaction接收语句列表在一个db.Begin()事务内顺序执行并统一提交/回滚返回累计受影响行数main.go手工交互式事务begin_manual_transaction会从连接池取出独占的一条物理连接并BeginTx之后的execute_query全部运行在该事务上直到commit_manual_transaction/rollback_manual_transaction结束main.go。这符合 agents/docs/agent-protocol-v2.md 对交互式事务pin one physical connection的约定断连时也会静默回滚未完成的手工事务。9.2 DDL 提取get_table_ddlmain.go优先调用DBMS_METADATA.GET_DDLportabletrue时会先DBMS_METADATA.SET_TRANSFORM_PARAM(..., SEGMENT_ATTRIBUTES, FALSE)禁用段属性输出更干净、可移植的 DDL之后恢复设置。输出结果会继续追加非主键/唯一约束生成的用户索引 DDLDBMS_METADATA.GET_DDL(INDEX, ...)表触发器 DDL表与列注释COMMENT ON TABLE/COLUMN ... IS ...。当DBMS_METADATA失败时会降级为基于getColumns元数据手工拼装CREATE TABLE ...并附带主键、默认值、NOT NULL 与精度/标度信息main.go视图 DDL 则优先取ALL_VIEWS.TEXT再拼CREATE OR REPLACE VIEW schema.view AS ...并正确追加视图注释。get_table_ddl的结果以 JSON 字符串返回main_test.go保证前端可直接回填到 SQL 编辑器。十、测试与质量保障该模块的测试与协议契约绑定紧密main_test.go 校验 handshake 版本与能力集合、多会话运行时行为关闭一个会话不影响其他会话、cancel_session只取消目标会话、空结果集 JSON 序列化columns/rows必须输出[]而非null、RAW 十六进制格式化、非有限浮点转字符串、日期时间墙钟输出等tns_test.go 覆盖 TNS 别名解析、失败转移描述符保留、prefetch_rows覆盖、缺失TNS_ADMIN、未知别名、非法目录等错误路径。发布前还可运行仓库的 Agent 校验脚本 agents/scripts/validate_agents.py 做整体校验。十一、适用前提与限制该 Agent 在 README 中被明确标注为Experimental实验性接入生产环境前请充分验证依赖go 1.20与github.com/sijms/go-ora/v2 v2.9.0见 go.mod与 DBX 的通信完全依赖 JSON-RPC 协议版本升级 DBX 后应重新核对 handshake 返回的协议版本与能力集合本地联调时~/.dbx/agents/drivers/oracle/agent会覆盖同名目录下的 Java Agentagent.jar删除该文件即可还原交叉编译产物命名建议沿用dbx-agent-oracle-平台-架构的惯例便于与发布脚本集成。如需深入协议细节可继续阅读 agents/docs/agent-protocol-v2.md多会话运行时模型与 agents/docs/agent-authoring.mdAgent 编写规范与审查清单。【免费下载链接】dbx20 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考