Delphi连接Oracle终极方案：ODAC直连、REF CURSOR映射与时区控制

简介：本资源为Delphi与C++Builder开发者专用的ODAC（Oracle Data Access Components）完整组件包，聚焦Oracle数据库高效接入与开发，适用于中高级桌面应用开发者快速构建企业级数据库系统。包内含1807个文件，主体为396个PAS源码单元、140个DFM窗体设计、134个DPK包工程及263个DCU编译单元，辅以BMP图标、CFG配置、SQL脚本等配套资源，完整覆盖连接管理（TOracleConnection）、查询执行（TOracleQuery）、事务控制（TOracleTransaction）、存储过程调用及数据绑定等核心功能模块，压缩包仅9.7MB，轻量易集成。已有467人学习下载，资源由资深开发者goto1997整理发布，结构清晰、即开即用，包含多版本Build脚本（如Make.bat、MakeCBuilder.bat）及WebForm.aspx等跨平台适配示例，助读者深入理解ODAC在VCL/FMX双框架下的实际部署与调试要点。

1. Delphi ODAC Oracle 连接控件：不是“又一个数据库组件”，而是解决 Delphi 项目 Oracle 集成最后一公里的工业级方案

你在 Delphi 项目里写完业务逻辑，却卡在 Oracle 数据库连接上？用 dbExpress 调不通 TNS 配置，用 FireDAC 在 OCI 版本切换时反复报 ORA-12154，或者更糟——上线后突然出现连接池泄漏、LOB 字段读取截断、DATE 类型时区错位？这不是玄学，是 Delphi 原生生态与 Oracle 企业级特性之间长期存在的“协议鸿沟”。ODAC（Oracle Data Access Components）不是另一个轻量封装，它是 Devart 团队用近二十年 Oracle 协议栈逆向经验打磨出的 Delphi 专用桥接层：它绕过 OCI DLL 的版本绑定陷阱，原生支持 Oracle 10g 到 23c 全系列服务端，把TIMESTAMP WITH TIME ZONE、XMLType、BFILE、REF CURSOR这些企业级类型变成TDataSet字段；它让连接字符串不再依赖tnsnames.ora文件，支持纯内存式连接描述符；它甚至把 Oracle 的DBMS_OUTPUT、UTL_FILE、DBMS_ALERT封装成 Delphi 对象。适合谁？正在维护银行核心批处理模块的某公司 Delphi 开发者、需要对接 Oracle EBS 的某高校教务系统重构团队、或是被客户强制要求 Oracle 后端但团队只有 Delphi 老兵的某跨平台系统集成组——你不需要重学 PL/SQL，只需要让 Delphi 真正“听懂” Oracle。

2. ODAC 核心能力拆解：为什么它能绕过 OCI 版本墙、原生支持 REF CURSOR、并让 DATE 不再乱跳时区

ODAC 的价值不在“能连”，而在“连得稳、传得准、控得细”。它的底层不是简单调用 Oracle 官方 OCI 库，而是实现了 Oracle Net 8+ 协议的精简子集（含 TNS 数据包解析、加密握手、会话状态机），这决定了它对环境的低侵入性。下面从三个高频痛点切入，讲清它如何落地。

2.1 绕过 OCI DLL 版本绑定：不依赖 oracle_home，也不怕客户端升级翻车

传统 Delphi 数据库组件（如 dbExpress Oracle driver）必须在运行时加载oci.dll，而该 DLL 严格绑定 Oracle Instant Client 或完整客户端版本。一旦服务器升级到 Oracle 21c，客户端仍用 19c 的 oci.dll，就会触发 ORA-03134（连接被服务器拒绝）。ODAC 的解法是：内置轻量级 OCI 兼容层（称为 Direct Mode），它不加载任何外部 DLL，而是通过 TCP 直连 Oracle 监听器（默认 1521 端口），自行构造 Oracle Net 数据包。这意味着：

• 你的 Delphi 应用发布包里只需包含OdaclibXX.bpl（XX 为 Delphi 版本号），无需打包oci.dll、oraocieiXX.dll或配置PATH
• 连接字符串可完全脱离tnsnames.ora，直接写成：
  Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=10.20.30.40)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orcl)));User Id=scott;Password=tiger;

提示：Direct Mode 默认启用，若需回退到传统 OCI 模式（例如必须使用UTL_HTTP等依赖本地客户端的功能），可在TOraSession.Options.UseDirectMode := False后显式设置TOraSession.LibraryName := 'oci.dll'。

2.2 REF CURSOR 的 Delphi 原生映射：把存储过程返回的游标变成真正的 TDataSet

Oracle 存储过程中大量使用SYS_REFCURSOR返回动态结果集，但 Delphi 原生组件对此支持极弱：dbExpress 无法自动识别 REF CURSOR 字段结构，FireDAC 需手动调用Open并预设字段定义。ODAC 将其彻底对象化：

// 假设 Oracle 中有存储过程：PROCEDURE get_emp_by_dept(p_dept_id IN NUMBER, p_cursor OUT SYS_REFCURSOR) var OraStoredProc: TOraStoredProc; DataSet: TOraQuery; begin OraStoredProc := TOraStoredProc.Create(nil); try OraStoredProc.Session := OraSession; // 已建立的 TOraSession OraStoredProc.StoredProcName := 'get_emp_by_dept'; // 关键：声明 REF CURSOR 参数为 ftCursor 类型，并指定关联的 DataSet OraStoredProc.ParamByName('p_cursor').DataType := ftCursor; OraStoredProc.ParamByName('p_cursor').ParamType := ptOutput; OraStoredProc.ParamByName('p_cursor').DataSet := DataSet; // 自动将结果注入此 DataSet OraStoredProc.ParamByName('p_dept_id').AsInteger := 10; OraStoredProc.Execute; // 执行后，DataSet 已自动打开并填充数据 // 此时 DataSet.Fields[0].FieldName = 'EMPNO', Fields[1].FieldName = 'ENAME'... finally OraStoredProc.Free; end; end;

逻辑说明：ODAC 在Execute时捕获 Oracle 返回的 REF CURSOR 描述信息（列名、类型、长度），动态构建TOraQuery的字段元数据，无需人工FieldDefs.Add。参数说明：ftCursor是 ODAC 特有数据类型（非 VCL 标准），仅用于 REF CURSOR 参数；DataSet属性必须指向一个已创建但未打开的TOraQuery实例，ODAC 会接管其生命周期。

2.3 DATE/TIMESTAMP 时区一致性保障：从连接层就锁定时区，避免“存进去是下午3点，查出来变凌晨3点”

Oracle 的DATE和TIMESTAMP类型本身不存时区，但客户端会根据NLS_TIMESTAMP_FORMAT和会话时区做隐式转换。Delphi 默认用 Windows 系统时区解析时间字符串，而 Oracle 服务端可能运行在 UTC 时区，导致插入TRUNC(SYSDATE)后查询结果偏移 8 小时。ODAC 提供两级控制：

• 会话级时区锁定：在TOraSession.Options中设置TimeZone属性，例如OraSession.Options.TimeZone := 'Asia/Shanghai';。ODAC 会在登录后自动执行ALTER SESSION SET TIME_ZONE = 'Asia/Shanghai'，确保所有SYSDATE、SYSTIMESTAMP返回值按指定时区计算。
• 字段级精度控制：对TDateTime字段，ODAC 默认映射为 OracleDATE（秒级精度）；若需毫秒级，需将字段DataType显式设为ftDateTime并启用Options.UseTimestamp := True，此时底层使用TIMESTAMP类型传输。

验证方法：在 Delphi 中赋值MyField.AsDateTime := EncodeDateTime(2024, 6, 15, 15, 30, 0, 0);，插入后在 SQL*Plus 中执行SELECT DUMP(my_date_col) FROM my_table;，若结果为Typ=12 Len=7: 224,124,6,15,16,31,1（典型 DATE 内部表示），说明未发生时区漂移；若出现Typ=180（TIMESTAMP）且值异常，则需检查UseTimestamp设置。

3. 快速集成实战：从零部署 ODAC 到 Delphi 10.4，完成 Oracle 连接、查询、事务三步闭环

本节以 Delphi 10.4 Sydney 为例，演示如何在无 Oracle 客户端环境下，用 ODAC Direct Mode 完成最小可行连接。全程不依赖tnsnames.ora、不安装 Instant Client、不修改系统 PATH。

3.1 环境准备与包安装：BPL 包注册与 IDE 集成

ODAC 发布包包含多个.bpl（编译后包）和.dpk（源码包）。生产环境推荐使用 BPL，开发调试可用 DPK。步骤如下：

1. 解压 ODAC 安装包，进入bpl\win32（或win64）目录，找到对应 Delphi 版本的文件：
   • Odaclib104.bpl（运行时包）
   • Odaclib104D.bpl（设计时包，含组件面板图标）
2. 将Odaclib104.bpl复制到 Delphi 的bin目录（如C:\Program Files (x86)\Embarcadero\Studio\21.0\bin），或将路径加入系统PATH（推荐前者，避免全局污染）
3. 启动 Delphi IDE →Component→Install Packages...→ 点击Add...→ 选择Odaclib104D.bpl→ 确认。此时组件面板Devart Oracle页签会出现TOraSession、TOraQuery、TOraStoredProc等控件。

注意：若安装时报错 “Package does not contain any design-time components”，说明选择了错误架构的 BPL（如 64 位 BPL 装入 32 位 IDE），请核对win32/win64目录及 Delphi 构建目标。

3.2 创建连接会话：TOraSession 配置与连接测试

拖拽TOraSession组件到窗体，关键属性设置如下：

连接测试代码（放在按钮OnClick事件中）：

procedure TForm1.Button1Click(Sender: TObject); begin try OraSession1.Connect; // 触发连接 ShowMessage('连接成功！服务器版本：' + OraSession1.ServerVersion); except on E: EOraError do ShowMessage('Oracle 错误：' + E.Message + ' (ORA-' + IntToStr(E.ErrorCode) + ')'); on E: Exception do ShowMessage('通用错误：' + E.Message); end; end;

逻辑说明：Connect方法会尝试建立 TCP 连接、完成 Oracle Net 握手、发送登录凭据。若成功，ServerVersion返回类似'Oracle Database 19c Enterprise Edition Release 19.0.0.0.0 - Production'的字符串。参数说明：EOraError是 ODAC 自定义异常类，ErrorCode对应 Oracle 标准错误码（如 ORA-12154），比Exception.Message更利于精准排错。

3.3 执行查询与事务：TOraQuery 的参数化查询与事务边界控制

拖拽TOraQuery组件，设置Session属性指向OraSession1。执行带参数的 SELECT 并启用事务：

procedure TForm1.Button2Click(Sender: TObject); var SQL: string; begin // 1. 开启事务（显式 BeginTransaction，非自动提交） OraSession1.StartTransaction; try // 2. 构造参数化 SQL（防止 SQL 注入） SQL := 'SELECT empno, ename, sal FROM emp WHERE deptno = :dept_id AND sal > :min_sal'; OraQuery1.SQL.Text := SQL; // 3. 绑定参数（名称匹配，类型自动推导） OraQuery1.ParamByName('dept_id').AsInteger := 20; OraQuery1.ParamByName('min_sal').AsFloat := 2000.00; // 4. 执行查询（自动 Open） OraQuery1.Open; // 5. 遍历结果（字段名即 Oracle 列名，大小写敏感） while not OraQuery1.Eof do begin Memo1.Lines.Add(Format('%d %s %.2f', [ OraQuery1.FieldByName('EMPNO').AsInteger, OraQuery1.FieldByName('ENAME').AsString, OraQuery1.FieldByName('SAL').AsFloat ])); OraQuery1.Next; end; // 6. 提交事务（即使只读查询，StartTransaction 也需配对 Commit） OraSession1.Commit; except on E: EOraError do begin OraSession1.Rollback; // 出错时回滚 raise; // 重新抛出以便上层处理 end; end; end;

逻辑说明：ODAC 的TOraQuery.Open会自动检测 SQL 类型（SELECT 自动执行，DML 需ExecSQL），参数绑定使用ParamByName，值类型通过AsInteger/AsString等属性自动转换。参数说明：StartTransaction是会话级操作，影响所有关联的TOraQuery和TOraStoredProc；Commit/Rollback必须成对出现，否则连接会处于未结束事务状态，可能导致锁表。

4. 避坑指南：五个血泪换来的 ODAC 常见问题与根因排查

ODAC 功能强大，但 Delphi 与 Oracle 的深度耦合也埋下独特陷阱。以下是我在某高校教务系统 Oracle 迁移项目中踩过的坑，每一条都附带现场日志特征和验证命令。

4.1 现象：连接时抛出 EOraError，Message 为 "ORA-12537: Network Session: End of file"，ErrorCode=12537

原因：Oracle 监听器未启动，或防火墙拦截了 1521 端口，导致 TCP 连接建立后立即被 RST。ODAC Direct Mode 无法区分“连接失败”和“连接后断开”，统一报此错。
解决：

• 在 Delphi 机器上执行telnet 10.20.30.40 1521，若提示“无法打开到主机的连接”，说明网络不通；
• 若 telnet 成功但 ODAC 仍报错，检查 Oracle 服务端listener.ora中HOST是否为localhost（应改为实际 IP 或0.0.0.0）；
• 临时关闭 Windows 防火墙测试：netsh advfirewall set allprofiles state off。

4.2 现象：TOraQuery.Open后RecordCount = -1，且EOF = True，但 Oracle 中确认有数据

原因：TOraQuery的FetchAll属性默认为False，ODAC 采用流式获取（fetch on demand），RecordCount仅在FetchAll=True或遍历完全部记录后才准确。
解决：

• 方案一（推荐）：不依赖RecordCount，用while not EOF do ... Next遍历；
• 方案二：设OraQuery1.FetchAll := True，此时Open会一次性拉取全部结果到内存，RecordCount可用，但大数据集慎用；
• 验证：在Open后立即打印OraQuery1.RecordCount和OraQuery1.EOF，若为-1和False，说明数据已加载，只是未统计。

4.3 现象：插入 CLOB 字段时，内容被截断为 4000 字节，且无报错

原因：ODAC 对 CLOB 的默认传输模式为InParam（输入参数），当值长度超过 4000 字节，Oracle 会静默截断。必须显式设置参数方向为ptInput并启用LongReadLen。
解决：

OraQuery1.SQL.Text := 'INSERT INTO docs(id, content) VALUES (:id, :content)'; OraQuery1.ParamByName('id').AsInteger := 1001; OraQuery1.ParamByName('content').ParamType := ptInput; // 关键！ OraQuery1.ParamByName('content').DataType := ftMemo; // ftMemo 映射 CLOB OraQuery1.ParamByName('content').AsString := VeryLongString; // 长度 > 4000 OraQuery1.ExecSQL;

提示：ftMemo是 ODAC 对 CLOB/BLOB 的映射类型，ptInput确保以 LOB Locator 模式传输，而非普通字符串。

4.4 现象：TOraStoredProc调用含OUT VARCHAR2参数的存储过程，ParamByName('out_str').AsString为空字符串

原因：OracleVARCHAR2OUT 参数在 PL/SQL 中需预先分配长度，ODAC 默认分配 1 字节，导致返回值被截断。
解决：在Execute前显式设置Size：

OraStoredProc.ParamByName('out_str').Size := 4000; // 必须大于实际返回长度 OraStoredProc.Execute; ShowMessage(OraStoredProc.ParamByName('out_str').AsString); // 此时有值

4.5 现象：应用运行数小时后，Oracle 会话数暴增，v$session中出现大量INACTIVE状态连接

原因：TOraSession的连接池未启用，每次Connect都新建物理连接，但Disconnect未被调用（如异常退出未Free组件）。
解决：

• 启用连接池：OraSession1.Options.Pooling := True;
• 设置最大连接数：OraSession1.Options.MaxPoolSize := 20;
• 在应用退出前调用OraSession1.Disconnect（或设OraSession1.AutoDisconnect := True）；
• 监控命令：SELECT username, status, program FROM v$session WHERE username IS NOT NULL;，若status=INACTIVE且program为delphi_app.exe，说明连接泄漏。

5. 进阶技巧：用 ODAC 的 Schema Explorer 逆向工程 Oracle 表结构，并生成 Delphi 数据模块骨架

ODAC 自带Schema Explorer工具（位于安装目录Bin\SchemaExplorer.exe），它不只是图形化浏览工具，更是 Delphi 开发者的“数据库翻译器”——能把 Oracle 的复杂对象（分区表、物化视图、函数索引）一键转成 Delphi 可用的TDataModule代码框架。这招在我接手某银行旧系统重构时救了命：300+ 张表、50+ 个存储过程，手工建TDataSet至少两周，用 Schema Explorer 10 分钟搞定。

5.1 使用 Schema Explorer 抽取表结构并生成 DataModule

1. 启动SchemaExplorer.exe，新建连接（填入与 Delphi 中一致的 Server/Port/ServiceName/User/Pass）
2. 连接成功后，左侧树展开Tables，勾选目标表（如EMP,DEPT,SALGRADE）
3. 右键 →Generate DataModule...→ 选择 Delphi 版本（如 10.4）→ 设置输出路径
4. 点击Generate，生成DM_Oracle.pas和DM_Oracle.dfm

生成的DM_Oracle.pas关键片段如下：

type TDM_Oracle = class(TDataModule) OraSession1: TOraSession; OraQuery_EMP: TOraQuery; OraQuery_DEPT: TOraQuery; OraQuery_SALGRADE: TOraQuery; DataSource_EMP: TDataSource; DataSource_DEPT: TDataSource; DataSource_SALGRADE: TDataSource; public procedure Connect; procedure Disconnect; end; implementation {$R *.dfm} procedure TDM_Oracle.Connect; begin if not OraSession1.Connected then OraSession1.Connect; OraQuery_EMP.Open; OraQuery_DEPT.Open; OraQuery_SALGRADE.Open; end; procedure TDM_Oracle.Disconnect; begin OraQuery_SALGRADE.Close; OraQuery_DEPT.Close; OraQuery_EMP.Close; if OraSession1.Connected then OraSession1.Disconnect; end;

逻辑说明：Schema Explorer 不仅生成组件，还自动生成连接/断开逻辑、Open/Close顺序（按外键依赖关系排序），并为每个TOraQuery配置好SQL.Text（SELECT * FROM table_name）和参数绑定占位符（若表有主键，会添加WHERE条件模板）。

5.2 手动增强生成的 DataModule：添加事务控制与错误日志

生成的骨架是起点，需人工加固。以TDM_Oracle为例，添加事务包装和 Oracle 错误日志：

// 在 TDM_Oracle 类声明中添加 private FTransactionID: Integer; procedure LogOracleError(const Msg: string; ErrCode: Integer); public function ExecuteInTransaction(const SQL: string; const Params: array of const): Boolean; // 实现 function TDM_Oracle.ExecuteInTransaction(const SQL: string; const Params: array of const): Boolean; var Q: TOraQuery; begin Result := False; Q := TOraQuery.Create(nil); try Q.Session := OraSession1; Q.SQL.Text := SQL; // 绑定变长参数数组（兼容不同数量参数） if Length(Params) > 0 then for I := 0 to High(Params) do Q.Params[I].Value := Params[I]; OraSession1.StartTransaction; try Q.ExecSQL; OraSession1.Commit; Result := True; except on E: EOraError do begin OraSession1.Rollback; LogOracleError(E.Message, E.ErrorCode); Exit; end; end; finally Q.Free; end; end; procedure TDM_Oracle.LogOracleError(const Msg: string; ErrCode: Integer); const LOG_FILE = 'oracle_errors.log'; var F: TextFile; TimeStr: string; begin AssignFile(F, LOG_FILE); try if FileExists(LOG_FILE) then Append(F) else Rewrite(F); TimeStr := FormatDateTime('yyyy-mm-dd hh:nn:ss.zzz', Now); Writeln(F, Format('[%s] ORA-%d: %s', [TimeStr, ErrCode, Msg])); finally CloseFile(F); end; end;

参数说明：ExecuteInTransaction接收格式化 SQL 和array of const（Delphi 可变参数），内部用TOraQuery执行，自动包裹事务并捕获EOraError；LogOracleError将错误写入本地日志，含毫秒级时间戳，便于与 Oraclealert.log对齐。

从那以后我每次接手 Oracle 迁移项目，第一件事就是用 Schema Explorer 生成 DataModule 骨架，然后花 30 分钟加事务包装和错误日志——这比徒手敲 200 行TDataSet初始化代码快 10 倍，且零手误。希望帮到你。

本文还有配套的精品资源，点击获取