如何修复PostgreSQL的「时区偏移超出范围」错误？

问题根源 #

你生成的时间字符串格式YYYY-MM-DD HH:MM:SS+fff（比如2022-10-29 11:00:00+45）被PostgreSQL误解析：+后面的数字被当成了时区偏移量（而非毫秒），而PostgreSQL允许的时区偏移范围是-12小时到+14小时，+45会被识别为+45小时，超出范围导致报错。

解决方案 #

1. 修正Python时间格式（最优，从源头解决） #

直接修改Python生成时间字符串的代码，生成PostgreSQL能正确解析的timestamptz格式：用.分隔毫秒，时区明确标记为+00（因为是UTC时间）。

示例代码：

from datetime import datetime, timezone

# 生成带毫秒的UTC时间字符串，格式为 "YYYY-MM-DD HH:MM:SS.fff+00"
utc_time = datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S.%f')[:23] + '+00'

或者更简洁的写法：

utc_time = datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('T', ' ').replace('+00:00', '+00')

生成的字符串类似2022-10-29 11:00:00.450+00，PostgreSQL会正确识别.后的部分为毫秒，+00为UTC时区，彻底避免解析错误。

2. 无法修改Python代码时的SQL兼容方案（次优，注意性能） #

如果上游代码不能调整，可在SQL查询中对错误格式的字符串做转换，把+替换为.后再指定时区：

SELECT * FROM BOOKS 
WHERE CurrentTimeStamp BETWEEN 
  TO_TIMESTAMPTZ(REPLACE('2022-10-29 10:00:00+00', '+', '.') || '+00')
  AND 
  TO_TIMESTAMPTZ(REPLACE('2022-10-29 11:00:00+450', '+', '.') || '+00');

或者用TO_TIMESTAMP指定格式解析：

SELECT * FROM BOOKS 
WHERE CurrentTimeStamp BETWEEN 
  TO_TIMESTAMP('2022-10-29 10:00:00+00', 'YYYY-MM-DD HH24:MI:SS+FF3') AT TIME ZONE 'UTC'
  AND 
  TO_TIMESTAMP('2022-10-29 11:00:00+450', 'YYYY-MM-DD HH24:MI:SS+FF3') AT TIME ZONE 'UTC';

注意：这种方式需要对查询参数做字符串处理和类型转换，在高并发（每小时50万条）场景下可能无法命中CurrentTimeStamp列的索引，导致查询性能下降，仅作为临时兼容方案。

3. 高并发场景性能优化建议 #

• 确保CurrentTimeStamp列上创建BTREE索引，这是范围查询（BETWEEN）的最优索引类型。
• 如果查询是固定时间窗口（如按小时查询），可考虑将表按时间分区，大幅提升大表的查询效率。
• 始终保持CurrentTimeStamp列的原始类型参与比较，避免对列做函数转换，才能有效利用索引。

内容的提问来源于stack exchange，提问作者layman