mssql-django 中的新增功能

本文介绍 Django 数据库后端的每个版本中的 mssql-django 新功能、改进和更改。

版本 2.0

发行日期:2026年9月

2.0 版本新增了 Microsoft 的mssql-python驱动程序,作为可按数据库使用的pyodbc替代方案,更新了受支持的 Python、Django 和 SQL Server 版本矩阵,并提供了兼容性和可靠性修复。 pyodbc 仍然是默认驱动。

亮点

  • MSSQL-python驱动支持:数据库别名在其字典中选择加入"python_driver": "mssql_python"OPTIONS。 驱动程序涵盖连接、连接池、重试、事务和保存点、datetimeoffset 值、内省以及 Microsoft Entra 认证。 没有该选项的别名继续使用 pyodbc,所以在你选择加入之前不会有任何变化。 欲了解更多信息,请参见 为 mssql-django 选择数据库驱动程序。
  • 在 mssql-python 路径中无需单独安装 ODBC 驱动程序:mssql-python 上的别名无需额外安装 Microsoft SQL Server ODBC 驱动程序。 保留 pyodbc 的别名依然有效。
  • 现代化支持矩阵:Python 3.10 至 3.14,Django 5.2 至 6.1,以及 SQL Server 2017 至 2025。 Django 6.0及以后版本需要Python 3.12或更高版本。

故障修复

  • 显式 MARS 设置会被采用:extra_params 中的显式 MARS_Connection 值会被保留,而不是被 Windows 默认值覆盖,且匹配忽略大小写。 设置 MARS_Connection=no 现在适用于拒绝 MARS 的端点,包括 Microsoft Fabric Warehouse。 禁用MARS时,ORM迭代会先缓冲结果,使嵌套查询可以重用连接,这在大型查询集上占用更多内存。 该连接修复并未为迁移或其他 SQL Server 功能添加完整的仓库支持。
  • 括号通配符在表达式查找中可以逃离:比较两个带有F()表达式的字段(如contains和startswith)的模式查找可以避开SQL Server[的万用符。 括号字符按数据匹配,而不是按通配符语法匹配。
  • inspectdb 架构名称中的引号会被转义:元数据查询中,inspectdb --schema 值中的单引号会被转义,因此包含引号的架构名称不再生成格式错误的 Transact-SQL(T-SQL)。
  • 空的 HOST 在 mssql-python 路径下会连接到 localhost:被省略的 HOST 会被 Django 补为一个空字符串,并解析为 localhost,而不是因空的 SERVER= 值而无法通过验证。 这种行为符合本地实例的默认情况 pyodbc 。

Improvements

  • pytz 已由 zoneinfo 和 tzdata 取代:时区处理使用标准库中的zoneinfo模块,而tzdata包则在未附带 IANA 时区数据库的环境中用于提供该数据库,例如 Windows 和精简容器镜像等环境。 对于采用负夏令时偏移量的时区,偏移量在全年始终正确。 pytz 不再是依赖项。
  • 接受较新的 SQL Server 版本:后端不认可的 SQL Server 主要版本使用后端已知的最新能力集,而非失败的版本验证。 你可以在与之匹配的 mssql-django 版本发布之前连接到新的 SQL Server 版本。 接受连接并不意味着支持未经测试的功能。

破坏性变更

  • Python 3.8 和 3.9,以及 Django 3.2 到 5.1 版本已不再支持。 早期版本的兼容性代码依然保留,但这些组合不会被测试或列出。
  • mssql-python 即使别名使用 pyodbc,1.15.0 或更高版本仍是必需的依赖。 安装仅限于兼容发行 mssql-python 版的平台,不包括 ARM64 上的 SUSE Linux。 其他平台的项目仍保留在1.8.0版本。
  • 声明的 SQL Server 支持始于 SQL Server 2017,声明的原生连接支持仅限于 Microsoft ODBC 驱动 17 和 Microsoft ODBC 驱动 18。

版本 1.8.0

发行日期:2026年8月

1.8.0 版本增加了对 Django 6.1 的支持,同时继续支持 Django 3.2 至 6.0。 将项目从 Django 6.0 迁移到 6.1 不需要代码更改,除非你使用本节描述的两个 Django 6.1 功能之一。

亮点

  • Django 6.1 支持:在继续支持 Django 3.2 至 6.0 的同时,已通过 Django 6.1 验证。 依赖约束从 django>=3.2,<6.1 扩大到 django>=3.2,<6.2。
  • 查询编译器在 Django 6.1 上使用 quote_name:Django 6.1 已弃用 quote_name_unless_alias。 后端现在会在 Django 6.1 及更高版本中调用 SQLCompiler.quote_name;该行为根据版本进行控制,因此较早的 Django 版本不受影响。 切片和偏移查询(例如 qs[a:b] 和 OFFSET ... FETCH)在编译时不会出现弃用警告。
  • 外键自省返回 ON DELETE 规则:Django 6.1 将 get_relations() 扩展为包含数据库级的 ON DELETE 规则。 后端返回预期的三部分结构,并据此映射 SQL Server NO ACTION 外键,因此 inspectdb 和外键内省都会生成正确的模型。

不支持的Django 6.1功能

由于不同原因,Django 6.1 的两个扩展功能在该后端不可用:

  • 数据库级参照操作(DB_CASCADE、DB_SET_NULL、DB_SET_DEFAULT):SQL Server 拒绝包含指向同一表的多条级联路径的外键图(错误 1785),因此在任何版本的 SQL Server 中都无法原生支持此功能。 使用这些值中的任何一个都会触发 Django 系统检查 fields.E324,它会将你指向标准的 Django 级别的 on_delete。
  • 位向聚合(BitAnd, BitOr, ):BitXorSQL Server 没有原生的逐位聚合函数,后端也不模拟,因此这些聚合会生成 NotSupportedError。

有关详细信息,请参阅 mssql-django 中的限制和不支持的功能。

版本 1.7.4

上映日期:2026年7月

1.7.4 版本是一个向后兼容的补丁版本,包含两个针对原始和带注释的 GROUP BY 查询处理的修复。

故障修复

  • 在带有转义的 %% 和真实参数的 GROUP BY 查询上的 IndexError:以前,任何带有 GROUP BY 子句的查询都会经过占位符重写步骤,该步骤匹配 %\w+ 并将其替换为 {}。 该正则表达式还匹配了转义的 %% 文本,这会在查询将 %%-escape 与真实 %s 参数结合时注入幻影占位符并引发 IndexError: Replacement index N out of range。 收窄后的正则表达式现在只会处理 %%(按原样保留)和 %s(真正的占位符),这也是编译器唯一会输出的模式。 相同的修复还防止了一个不相关的静默 bug,其中无参数查询中未转义的模式(例如 LIKE '%abc%')被重写为 LIKE '{}%' 并返回了错误的行。
  • 在原始 GROUP BY 查询中 IntegerChoices 的 NotImplementedError:以前,将 IntegerChoices 值传递到包含 GROUP BY 子句的原始查询中会引发 NotImplementedError: Not supported type <enum ...>。 参数类型帮助程序使用精确类型检查 (typ == int) ,而 type(IntegerChoices_value) 是枚举类而不是 int,因此即使它子类化了 int,该值也会落到引发异常。 类型检查现在使用 isinstance,分支 bool 在分支 int 之前被评估(因为 bool 本身是一个 int 子类)。 枚举选项现在可以正确绑定,bool 仍然绑定 BIT,普通的 int 保持不变。

版本 1.7.3

发布日期:2026 年 6 月

版本 1.7.3 是一个向后兼容的补丁版本,包含两项与连接和运行时相关的修复。

故障修复

  • FA001 对于 Authentication= 以外的 ActiveDirectoryMsi 模式:以前,后端仅对 Trusted_Connection=yes 跳过 ActiveDirectoryMsi。 其他未提供 USER 值的 Entra 模式(例如 ActiveDirectoryIntegrated、ActiveDirectoryDefault、ActiveDirectoryDeviceFlow)仍会收到 Trusted_Connection=yes,而 ODBC 驱动程序会以 FA001(Cannot use Authentication option with Integrated Security option)拒绝该值。 该修复程序通过边界感知且不区分大小写的匹配方式检测任何显式的 Authentication= 值,并跳过 Trusted_Connection 和 Integrated Security=SSPI。 密码处理保持不变:SqlPassword、ActiveDirectoryPassword 和 ActiveDirectoryServicePrincipal 继续发送 PWD,而 ActiveDirectoryInteractive 继续省略它。
  • 子类化 KeyError 上的 DatabaseWrapper:缓存的 sql_server_version 和 to_azure_sql_db 属性依赖于 type(self).__dict__ 的 cached_property 内省,这在 KeyError 子类首次访问它们时会引发 DatabaseWrapper(1.7.1 版本引入的回归问题)。 修复使用通过 _known_versions 访问的显式类级别字典(_known_azures、self.),因此查找通过 MRO 解析,子类化包装器正常工作。

版本 1.7.2

发布日期:2026 年 5 月

版本 1.7.2 是一个向后兼容的补丁版本,包含时区和兼容性修复。

故障修复

  • .explain() Django 4.0 及更高版本的兼容性:修复了 Django 解释元数据的编译器处理,因此 .explain() 不再在 AttributeError Django 4.0 及更高版本中失败。 后端现在遵循符合相应版本的 explain 字段,并在需要时正确抛出 NotSupportedError。
  • datetimeoffset 时区处理:修复了 datetimeoffset 的解析问题,从而保留时区偏移量而不是将其丢弃。 返回的日期时间现在会在预期情况下包含时区信息。
  • Now() with USE_TZ=True: 更新了 SQL 生成,以便在Now()启用时区支持时使用时区感知行为,从而阻止非 UTC SQL Server 主机上的时间戳偏移。

版本 1.7.1

发布日期:2026 年 4 月

版本 1.7.1 是一个向后兼容的补丁版本,包含错误修复。

故障修复

  • FieldDoesNotExist 当以降序索引排序更改字段时:修复 _alter_field() 中使用 schema.py 而非 index.fields_orders 来解析索引字段名称的 index.fields。 以前的代码将原始字段带排序字符串(例如 "-pub_date")传递给 model._meta.get_field(),这会引发 FieldDoesNotExist。 现在仅提取字段名称,正确丢弃排序后缀。
  • 支持 Microsoft Fabric 中的 SQL 数据库(EngineEdition 12):将 Fabric 中的 SQL 数据库(EngineEdition=12)识别为 Azure 版本。 以前,Fabric 的引擎版本未被识别,导致 to_azure_sql_db 返回 False 且功能门控检查失败。 该修复将EDITION_AZURE_SQL_FABRIC=12添加到_AZURE_EDITIONS,并将 Fabric 映射到最新受支持的 SQL Server 版本。 JSONField、哈希函数、排序规则内省和测试数据库拆卸在 Fabric 上现在正常工作。

版本 1.7

发布日期:2026 年 3 月

亮点

  • Django 6.0 支持:与 Django 6.0 完全兼容,这需要Python 3.12 或更高版本。 后端以透明方式处理所有 6.0 API 更改。
  • 部分 CompositePrimaryKey 支持:后端添加了对 Django 5.2 CompositePrimaryKey的部分支持。 元组与子查询的比较需要 Django 5.2.4 或更高版本,部分复合键和 JSONField 边缘情况仍然存在。 Django 5.2 本身首次在 mssql-django 1.6 中受支持。
  • SQL Server 2025 支持:根据 SQL Server 2025 进行验证。
  • ODBC 驱动程序 18 默认值:后端现在默认为 ODBC Driver 18 for SQL Server,如果未安装版本 18,则自动回退到 ODBC 驱动程序 17。

特定版本说明

Django 版本 备注
姜戈5.1 inspectdb 可以检查具有复合主键的表,但不会为这些表生成完整的模型定义。
Django 5.2 CompositePrimaryKey 仅提供部分支持。 元组与子查询的比较需要 Django 5.2.4 或更高版本,部分迁移和 JSONField 边缘情况仍然存在。
姜戈6.0 需要Python 3.12 或更高版本。 所有 5.2 限制都适用。

版本 1.6

发布日期:2025 年 8 月

  • 添加了 Django 5.1 和 5.2 支持。
  • 增强的 JSON 功能和向后兼容性。
  • 改进了管道基础结构。

版本 1.5

发布日期:2024 年 4 月

  • 为 supports_comments 添加了 db_comments 功能标记。
  • AutoField、参数格式设置和架构查询的错误修复。

版本 1.4

发布日期:2024 年 1 月

  • 添加了 Django 5.0 支持。
  • 添加了 db_comment 支持。
  • 日期/时间转换和空聚合的错误修复。

版本 1.3

发布日期:2023 年 5 月

  • 添加了 Django 4.2 支持。
  • 新增了对大小写敏感 Replace 函数的支持。
  • 为 OFFSET 处理和左填充的 Bug 修复。

版本 1.2

发布日期:2022 年 12 月

  • 添加了 Django 4.1 支持。
  • 添加了时区支持 (datetimeoffset with USE_TZ=True) 。
  • 新增了用于批量插入时检索 ID 的 return_rows_bulk_insert 选项。
  • 添加了 SQL Server 2022 支持。
  • 新增了JSONField对 Azure SQL 托管实例 的支持。

版本 1.1

发布日期:2022 年 7 月

  • Django 3.2 和 4.0 支持。
  • SQL Server 2016 及更高版本,以及Azure SQL 数据库支持。
  • 基于 pyodbc 的连接。