使用.between查询时本地与服务器返回数据不一致问题排查

在使用SQLAlchemy的.between筛选时间范围时，本地机器调用ReferalEntityRewardsRepository.summary_rewards方法返回的数据与服务器上调用的结果完全不同。已知条件：

• 数据库中add_dt字段为naive datetime（无时区信息），传入的start_dt和end_dt同样为naive datetime
• 数据库时区设置为UTC
• 本地与服务器的应用代码完全一致
• 数据库事务隔离级别为read committed

相关代码：

class ReferalEntityRewardsRepository(SQLAlchemyRepository):

    model = ReferalEntityReward

    async def summary_rewards(self, start_dt: datetime, end_dt: datetime, currency: str = 'rub', **filter_by):

        currency_map = {
            'rub': self.model.amount,
            'usd': self.model.amount_usd
        }

        stmt = (
            select(func.count(self.model.id).label("total_rewards"), func.sum(currency_map[currency]).label("total_amount"))
            .filter_by(**filter_by)
            .filter(self.model.add_dt.between(start_dt, end_dt))
        )

        result = await self.session.execute(stmt)
        total_rewards, total_amount = result.all()[0]

        return total_rewards, total_amount

可能的原因及解决方案 #

1. 本地与服务器的系统时区不一致 #

SQLAlchemy处理naive datetime时，默认会使用当前系统时区转换后再与数据库中的值比较。如果本地机器和服务器的系统时区不同（比如本地是东八区，服务器是UTC），传入的同一份naive datetime会被转换成不同的UTC时间去匹配数据库数据，直接导致结果差异。

解决办法：

• 统一将传入的start_dt和end_dt转换为带UTC时区的aware datetime，摆脱系统时区依赖：

  from datetime import timezone
  
  start_dt = start_dt.replace(tzinfo=timezone.utc)
  end_dt = end_dt.replace(tzinfo=timezone.utc)
  

• 或者在数据库连接时强制指定时区（以PostgreSQL为例），确保会话统一用UTC处理时间：

  engine = create_async_engine(
      "postgresql+asyncpg://user:pass@db:5432/dbname",
      connect_args={"options": "-c timezone=utc"}
  )
  

2. 数据库存储的naive datetime实际时区与代码假设不符 #

虽然数据库全局时区设为UTC，但如果写入add_dt时，应用是用本地时区的naive datetime直接存储（比如本地东八区，没转UTC就存了），那数据库里的时间实际是本地时区的数值，而非UTC。此时服务器用UTC时区解析查询，自然会和本地的查询结果产生偏差。

验证方式：
直接查数据库中的add_dt值，和应用写入时的原始时间对比，确认存储的是否为UTC时间。

解决办法：
写入数据时，必须先把时间转换为UTC的aware datetime再存储，或者明确标记naive datetime的时区为UTC。

3. 时间精度或边界处理差异 #

.between是闭区间查询（包含start和end的时间点），如果本地和服务器的系统时间精度不同（比如本地保留毫秒，服务器截断为秒），或者end_dt在两边的解析有差异，会导致边界数据的匹配结果不同。比如服务器上end_dt被截断后，原本符合条件的毫秒级数据被排除。

解决办法：

• 统一时间精度，比如截断到秒：

  start_dt = start_dt.replace(microsecond=0)
  end_dt = end_dt.replace(microsecond=0)
  

• 改用>=和<替代.between，避免闭区间的边界歧义，比如：

  .filter(self.model.add_dt >= start_dt)
  .filter(self.model.add_dt < end_dt)
  

4. 数据库会话时区配置不一致 #

虽然应用代码一致，但本地和服务器的数据库连接配置可能存在隐性差异，比如SQLAlchemy的timezone参数设置不同。如果本地会话默认用系统时区，服务器会话强制用UTC，也会导致naive datetime的解析逻辑不一致。

解决办法：
在创建SQLAlchemy引擎时，明确指定会话时区为UTC，确保环境间配置统一。

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