一句话总结
mssql-django 1.7.2 是一个小版本补丁，但修了三个非常实用的 Bug：时区处理、explain() 报错、异常吞没。如果你是 Django + SQL Server 技术栈的用户，尤其是用了 DATETIMEOFFSET 字段或 USE_TZ=True，建议尽快升级。
为什么要关注这个版本？
国内不少企业用 Django 做后端，数据库选 SQL Server — 尤其是制造业、金融、政务这些领域，SQL Server 绑定 Windows 生态，很多时候没得选。但 mssql-django 这个 ORM 适配层一直有些「可以忍但很烦」的小问题，其中时区处理就是投诉最多的一个。1.7.2 终于把这些问题修了。
三个核心修复
1. DATETIMEOFFSET 时区处理终于正确了 🔥
这是本次更新最重要的修复。
之前的问题： 当你从 SQL Server 的 DATETIMEOFFSET 字段读取数据时，mssql-django 会丢失时区偏移信息。比如你存了一个 2026-05-22 17:00:00 +08:00，读出来时变成 naive datetime（没有时区信息），或者时区直接错了。
带来的坑： 如果你的 Django 配置了 USE_TZ=True，用户的时区是北京时间，但 SQL Server 部署在 UTC 时区，那时间会偏移 8 小时 — 你存的「下午 5 点」用户看到「上午 9 点」。
1.7.2 的修复：
handle_datetimeoffset现在正确解析 SQL Server 二进制DATETIMEOFFSET的偏移量，返回带时区的datetime对象Now()在USE_TZ=True时编译为SYSDATETIMEOFFSET()而不是SYSDATETIME()，自带时区信息
这个补丁覆盖了 UTC、+05:30（印度）、-05:00（北美东部）、-09:30（马克萨斯群岛）、+05:45（尼泊尔）等多个时区的回归测试。
💡 国内用户注意： 如果你用 Django + SQL Server 做多时区业务（比如海外分公司的订单时间），升级后之前手动加
tzinfo的 workaround 可以删掉了，ORM 层面已经是 timezone-aware 了。
2. QuerySet.explain() 不再报错 ✅
Django 4.0 内部把 query.explain_format / query.explain_options 合并成了 query.explain_info，但 mssql-django 的编译器还在读旧属性，导致任何调用 .explain() 的操作都直接抛 AttributeError。
1.7.2 根据 Django 版本自动读取正确的属性，现在 explain() 在 Django 4.0 到 6.0 全版本都恢复正常。
做 SQL 调优时
explain()是常用工具，这个修复对日常开发排查慢查询很实用。
3. 测试工具不再吞异常 🐛
_check_jsonfield_supported_sqlite() 的 finally 块里有个 return 语句，会把包括 KeyboardInterrupt 在内的所有异常都吞掉。这个坑很小，但在调试阶段可能让你一脸懵。移除后异常正常传播。
版本兼容性
| 组件 | 支持版本 | |------|----------| | Django | 3.2 ~ 6.0 | | Python | 3.8 ~ 3.14 | | SQL Server | 2017 / 2019 / 2022 / 2025 / Azure SQL | | ODBC Driver | 17 或 18（默认 18，没装自动回退 17） |
升级指南
一行命令升级：
pip install --upgrade mssql-django
1.7.2 是 1.7.1 的原地替换，不需要改任何配置。
如果你的应用满足以下任一条件，升级后行为会直接变正确：
- 从
DATETIMEOFFSET列读取数据 - 在
USE_TZ=True下用django.db.models.functions.Now() - 在 Django 4.0+ 上调用
QuerySet.explain()
⚠️ 注意： 如果你之前手动给 DATETIMEOFFSET 读取的 naive datetime 加过 tzinfo，升级后需要去掉这些 workaround，否则会重复加时区。
来源
- 原文：Announcing mssql-django 1.7.2
- 项目地址：https://github.com/microsoft/mssql-django
- PyPI：https://pypi.org/project/mssql-django/
