Oracle Python-oracledb 中 DATE/TIMESTAMP 时区转换问题的分析与解决

Oracle Python-oracledb 中 DATE/TIMESTAMP 时区转换问题的分析与解决

问题背景

在使用 Oracle 的 python-oracledb 驱动程序时，开发人员发现当通过 fetch_df_all() 方法获取 DATE 和 TIMESTAMP 类型数据时，这些时间值会被自动转换为 UTC 时区，而常规的 cursor.fetchall() 方法则能保持原始时区不变。这种不一致的行为可能导致数据处理时出现意外的时间偏移。

问题现象

当执行以下操作时会出现时区转换问题：

1. 创建包含 DATE 和 TIMESTAMP 类型的测试表
2. 使用常规 cursor.fetchall() 方法获取数据 - 时间值保持原样
3. 使用 fetch_df_all() 方法获取数据并转换为 PyArrow 表 - 时间值被转换为 UTC 时区

例如，在 America/Los_Angeles 时区(UTC-7)下：

• 原始数据：2025-05-28 11:01:11
• fetch_df_all() 转换后：2025-05-28 18:01:11 (UTC)

技术分析

这个问题源于 python-oracledb 在将 Oracle 时间数据类型转换为 Arrow 格式时的处理逻辑。具体表现为：

1. 桥接层设计问题：在数据从 Oracle 到 Arrow 的转换过程中，桥接代码自动进行了时区转换，而没有考虑原始数据的时区信息。

2. 会话时区忽略：转换过程没有考虑数据库会话的 TIME_ZONE 设置，导致时区处理不一致。

3. 行为不一致：与常规游标获取方式相比，DataFrame 获取方式产生了不同的结果，这违反了最小意外原则。

解决方案

Oracle 开发团队已经修复了这个问题，主要改进包括：

1. 保持原始时区：现在 fetch_df_all() 方法会保持 DATE 和 TIMESTAMP 值的原始时区，与 cursor.fetchall() 行为一致。

2. 正确处理边界情况：修复还包括了对 Windows 系统上 1970 年时间戳处理的相关问题。

3. 性能优化：即使在修复后，fetch_df_all() 方法在处理大数据量(如100万行)时仍比常规 fetchall() 方法更快。

版本信息

该修复已包含在 python-oracledb 3.2.0 版本中。用户可以通过以下方式获取修复：

• 升级到最新正式版
• 使用开发团队提供的预构建开发版
• 从源代码自行构建

最佳实践建议

1. 版本升级：建议所有使用时间类型数据的用户升级到 3.2.0 或更高版本。

2. 测试验证：升级后应验证时间数据处理逻辑，特别是跨时区应用场景。

3. 性能考量：对于大数据量时间数据处理，仍推荐使用 fetch_df_all() 方法以获得更好性能。

4. 时区一致性：在应用中明确时区处理策略，避免混用不同获取方式导致的时区不一致问题。