本文按最新版本在前的顺序列出了 mssql-python 驱动在各个版本中的更改内容。 每个章节都涵盖一个版本的新功能、行为变更和bug修复。
关于 Microsoft 目前支持的版本,请参见支持生命周期。
mssql-python 1.18.0
发布日期:2026年11月18日
改进
自定义应用程序名称
在 连接字符串 中设置APP或Application Name,以便在服务器端监控中标识您的工作负载。 例如,APP=orders-api 在 APP_NAME() 和 sys.dm_exec_sessions.program_name 中显示为 MSSQL-Python|orders-api。 同步连接、实验性原生异步路径和批量复制都发送同一个名称。
默认名称为 MSSQL-Python。 在此版本之前,原生异步和批量复制路径会发送 mssql-python。 如果监控过滤器完全匹配 mssql-python ,请更新它。
有关详细信息,请参阅 Application name。
更快的行取用和转换
常见的提取模式执行的重复工作较少:
-
dict(row._mapping)不再在每次调用时重建列名查找。 -
fetchone()、fetchmany(1)、fetchval()以及对游标进行迭代,都会复用该游标上一次提取时的设置。 -
带有输出转换器的
fetchall()和fetchmany()会在调用你的转换器之前跳过内部文本转换。 转换器依然按相同顺序运行,并以相同的方式接收 SQLNULL。 - 对文本结果重复调用
fetchmany(1)后,每一行之后都会保留其设置。 驱动程序仍然不会预读后续行。
当 fetch 无法使用更快的路径时,驱动程序会使用现有的 Python 代码。 无需进行应用程序更改。
更快的重复参数化查询
驱动程序会一次性转换 pyformat 占位符并缓存结果,因此重复运行相同语句会跳过转换。 当你在同一个光标上再次运行相同语句,且每个参数的类型和大小与上一次运行相同时,驱动程序会重复使用已准备好的语句,而不是重新准备它。
有关详细信息,请参阅 “构建参数化查询”。
更新后的 Rust 运行时
驱动程序需要 mssql-python-rs==0.5.0。 当你使用选择加入 mssql-odbc 提供程序或本地异步路径时,此版本处理 SQL 文本和发送参数所花费的时间更少。
mssql-odbc 提供程序现在将 SQL_ATTR_CONNECTION_TIMEOUT 应用于重置池连接的请求。 在此版本之前,超时仅适用于请求被取消后的清理。
在 macOS 上, Encrypt=Strict 通过 Rust 运行时进行的 TCP 连接,比如 mssql-odbc 提供者和原生异步路径,现在都使用 Apple 的 Network.framework 来实现 TLS。 这些连接可以协商 TLS 1.3。 其他 Encrypt 设置不会改变。
mssql-odbc该提供者现在支持在 ODBC 级别的表值参数,包括NULL通过执行时数据流发送的单元格和单元格值。
mssql-python光标没有传递表值参数的 API。
msodbcsql18提供者仍然是默认选项。 更多信息,请参阅 使用 mssql-odbc 驱动程序(预览版) 和 依赖要求。
故障修复
Synapse 池连接关闭
在 Azure Synapse 专用 SQL 池中,关闭带有自动提交功能的池连接不再失败。 当驱动程序将连接返回到连接池时,它发送了 SET TRANSACTION ISOLATION LEVEL READ COMMITTED,而专用 SQL 池不支持这一语句。 驱动程序不再发送该语句。
显式连接池检出超时
如果你设置 SQL_ATTR_CONNECTION_TIMEOUT 的超时时间短于登录超时,在池重用连接之前运行的检查现在会保留你的值。 在修复之前,检查用更长的登录超时来替代它。 检查成功后,驱动程序会恢复您的原始值。
有关详细信息,请参阅连接运行状况检查。
关闭 Arrow reader
在此修复之前,从另一个线程关闭 Arrow 读取器时,即使没有 fetch 在运行,也会发送取消请求。 那个请求关闭了光标,阅读线程的下一个取用请求也随之引发了 ProgrammingError。 现在 close() 只会取消正在进行的提取,并在提取停止后返回。 来自较早查询的读取器无法关闭或读取同一光标上的后续结果。 关闭时未引发的错误仍然会传递到你的代码。
更多信息请参见 Apache Arrow集成。
Pyformat 占位符处理
驱动程序不再替换字符串字面量、带引号或方括号括起的标识符或注释中的 %(name)s 文本。 转义的百分比符号(%%)现在总是变为单 % 值,不再导致占位符和参数值不匹配。
Rust运行时修复
这些修复已在 0.5.0 版本 mssql-python-rs 中实现。 它们适用于 mssql-odbc 提供者和本地异步路径。
- 连接超时现限制每个连接级请求,包括在重用前检查池连接的请求。
- 当驱动程序在使预备计划失效的同时释放语句描述符时,预备语句不再失败。
- 驱动程序现在会在请求被取消后清理预先准备好的语句句柄。
- 更改事务隔离级别不再会丢弃有效的光标状态。
- 在带有小栈的线程上打开连接时,栈不会溢出。
- 标量
sql_variant值中长度过大现在会引发协议错误。 在此修复之前,长度会发生回绕,且未读字节会留在流中。 有效的数值不受影响。
在提供者中 mssql-odbc ,通过执行时数据流发送的值现在会放在其绑定参数的位置。 在此修复之前,提供者将它们移到了其他参数之后。 当你在同一预备语句上运行流式参数和参数数组时,值可能会到达错误的参数。
有关完整版本详情,请参阅 mssql-python 1.18.0 版本。
mssql-python 1.17.0
发布日期:2026年11月2日
改进
已更新的预览版原生提供程序
mssql-python-rs 0.4.0 中可选的 mssql-odbc 提供程序支持 Microsoft Entra ID 集成身份验证、运行中语句的取消,以及大型可扩展标记语言 (XML) 和用户定义类型参数的流式传输。 当服务器支持时,它还协商服务器辅助的域名系统(DNS)缓存和增强路由。 其默认的多子网故障切换行为现在允许对适用的传输控制协议(TCP)连接进行并行连接尝试。
该提供程序目前处于预览阶段。
msodbcsql18 仍然是默认提供者。 有关当前功能和限制,请参见使用 mssql-odbc 驱动(预览版)。
更快的连接池重用
当驱动程序能够确认一个池化连接已经干净时,会跳过冗余清理。 重用前,仍然需要清理带有未提交工作或已更改会话状态的连接。 结账仍然会通过与服务器进行一次往返通信来验证连接。
更多信息请参见 连接生命周期。
故障修复
软件包升级后的批量复制
驱动程序需要 mssql-python-rs==0.4.0。 更新后的运行时修复了升级后因原生模块布局导致的批量复制失败。 安装或升级带有依赖项的 mssql-python 会自动安装相应的运行时。
更多信息请参见 依赖要求。
批量复制Unicode、目标名称和日期时间精度
bulkcopy() 并 bulkcopy_arrow() 正确处理 UTF-8 文本,并修复加载 datetime2 值时小秒丢失的问题。 例如,Arrow 纳秒时间戳可以在 datetime2(7) 目标列中保留第七位小数,而不是被截断到微秒。 Pythondatetime对象的精度仍限制在微秒级。
包含三个以上部分的目标名称现在会在发送行之前、元数据查找期间引发 RuntimeError,而不是发展为服务器端错误。
更多信息请参见 批量复制 和 Apache Arrow集成。
从无响应的池化连接中进行有界恢复
在默认 msodbcsql18 提供程序中,检出操作会在池化验证期间应用一个临时的原生连接操作超时。 它使用正的登录超时时间,或者如果登录超时时间为零或未指定,则使用15秒。 验证失败后,驱动程序丢弃该连接,尝试重新登录,而不是验证每一个剩余的空闲连接。
多次验证操作、清理和替换登录可能会超过临时超时。 这并非完整的验证,也不是 connect() 截止日期。 Microsoft Entra ID 令牌获取不受登录超时限制。
可选的 mssql-odbc 提供程序并不保证相同的验证范围。 更多信息请参见 连接健康检查 和 原生提供程序限制。
nextset() 后的准确行数
Cursor.nextset() 会为批处理、存储过程或 Transact-SQL (T-SQL) 循环中每个后续的数据修改结果刷新 rowcount。 产生行的结果在获取前以 rowcount == -1 开始。 早期版本在进入另一个结果时仍保留了第一个语句的计数。
更多信息请参见 行数。
DB-API Timestamp() 兼容性
microsecond参数 是Timestamp()可选的,默认为零。 六参数 Timestamp(year, month, day, hour, minute, second) 调用现已按照 PEP 249的规定工作。
更多信息请参见 DB-API 时间戳构造器。
完整版本详情请参见 mssql-python 1.17.0 版本。
mssql-python 1.16.0
发布日期:2026年10月
改进
Python 3.15 支持
Python Package Index(PyPI)现在已提供适用于 Windows、Linux 和 macOS 上的 Python 3.15 的 wheel 包。 该版本共发布 41 个 wheel 包,涵盖 Python 3.10 至 3.15 版本。
欲了解更多信息,请参见 支持生命周期。
Conda 软件包
驱动程序现已发布到 Anaconda.org 上的 microsoft 频道。conda 包是一个自包含的软件包,包含 ODBC 驱动程序二进制文件和 Rust 运行时:
conda install -c microsoft mssql-python
在 Linux 上,conda 包需要 glibc 2.34 及更高版本。 在macOS上,需要macOS 15及更高版本。 有关完整的平台和要求列表,请参见 通过 conda 安装。
选择加入 mssql-odbc 原生提供程序
你现在可以选择一个名为 mssql-odbc的基于 Rust 的 ODBC 提供商。 Microsoft ODBC 驱动 18 (msodbcsql18) 仍然是默认。 在首次连接前,通过 MSSQL_PYTHON_NATIVE_PROVIDER 环境变量或 mssql_python.native_provider 属性选择提供程序。 你的应用程序代码不会变。
有关详细信息,请参阅使用 mssql-odbc 驱动程序(预览版)。
使用 row._mapping 进行字典式行访问
每个 Row 现在都有一个只读 _mapping 属性,该属性将列名映射到值。 使用 dict(row._mapping) 将行转换为字典,且不使用 cursor.description 合并值。
更多信息请参见 行对象。
Rust运行时随mssql-python-rs软件包附带
驱动批量复制的 Rust 运行时现在以独立的、版本匹配的 mssql-python-rs 包形式发布,而不再包含在 mssql-python wheel 包内。
pip install mssql-python 命令会自动安装它。 软件包 0.3.0 版本使用 CPython 稳定应用二进制接口(ABI)wheel 包,因此每个 wheel 包都适用于 Python 3.10 及更高版本。
更多信息请参见 依赖要求。
更新 mssql-python-odbc 的配套包
驱动现在需要 mssql-python-odbc 版本 18.6.2.2。 Linux 轮子按 C 库分割,因此 glibc 和 musl(Alpine Linux)环境各自只安装匹配的 ODBC 驱动 18.6 二进制文件。
提取操作更快
取指操作在 Python 中花费的时间更少:
-
fetchmany()和fetchall()在连接没有输出转换器且没有Row值被转换为字符串时,会在原生提取路径中构建对象。 -
date、time和datetime值的构建成本较低。 - 列元数据被重用于当前结果集,而不是每次取用时都重复描述。
- 干净的提取会跳过重复的诊断扫描。
- 诸如
row[0]的整数索引使用直接查找路径。 -
fetchval()当调试日志关闭时跳过调试日志调用。
无需更改申请。
故障修复
Windows进程在关机时可能会崩溃
驱动程序可以在 Python 终结之后释放其 ODBC 环境句柄,这导致在 Windows 进程退出时存在访问违规风险。 不再在终结之后释放句柄。
从提取到的文本中删除了开头的 U+FEFF 和 U+FFFE 字符
当提取的字符串以 U+FEFF 或 U+FFFE 开头时,驱动程序将该码点视为字节顺序标记并删除它。 驱动程序现在返回有界类型(如 nvarchar(n) 和 varchar(n))的完整值。 诸如 nvarchar(max) 之类的大值类型不在此修复范围内:前置的 U+FEFF 仍会被移除,且前置的 U+FFFE 会导致该值以错误的字节顺序解码。
池化连接可以保持空事务的开放状态
池连接可以带着处于打开状态的空事务或在关闭自动提交的情况下返回池。 驱动随后回滚物理连接并开启自动提交,然后再将该连接返回到连接池。 如果该清理失败,驱动会丢弃该连接,而不是将其放回连接池。
有关详细信息,请参阅连接池。
用户自定义类型参数缺少类型元数据
你声明为带有 和 -151(setinputsizes())的 SQL Server 用户定义类型的参数(例如 SQL_SS_UDT 和 geometry),现在会在绑定前从服务器获取其类型元数据。 修复涵盖了 None 值和已声明参数的复用语句。 在重用语句中,传递给用户定义类型列的未声明的 None 仍然失败。
setencoding() 无预警地忽略了不受支持的请求
驱动程序总是以 UTF-16LE 格式发送 Transact-SQL(T-SQL)语句和 str 参数。 如果调用 setencoding() 并指定了不同于使用 SQL_WCHAR 的 UTF-16LE 的编码或 ctype,现在会发出 UserWarning,而不再被静默忽略。
setencoding()无参数调用会无预警地恢复默认值。
有关详细信息,请参阅 管理连接。
原生日志可以将元数据解释为格式指令
当启用本机日志记录时,服务器提供的值(如 Arrow 列元数据)会以格式字符串的形式传递给本机日志记录器。 驱动程序现在会把这些值记录为字面文本。
批量复制未始终给目标标识符加引号
批量复制现在能够一致地为目标表名、列名和排序规则加引号并进行转义。 多部分名称和含空格或 ] 字符的括号引号名称可以正常使用。 格式错误的名称(如未封闭的括号或缺失的表名)会在发送任何行之前引发错误。
更多信息请参见 批量副本。
MSSQL-Python 1.15.0
发布日期:2026年9月
改进
setinputsizes() 参数处理在本地代码中运行
对 setinputsizes() 的参数处理现已通过原生 C++ 执行管线进行,而不再对每个参数分别进行 Python 调用。 宽、批处理且频繁执行的参数化语句在 Python 端参数处理中花费的时间更少。 无需更改申请。
有关详细信息,请参阅 数据类型映射。
Binary() 接受 memoryview 对象
Binary() 现在接受 memoryview 作为二进制输入,因此你可以传递缓冲区的零副本视图,而无需先将其转换为 bytes。
更多信息请参见 二进制数据。
可从 mssql_python 模块获取 SQL Server 类型常量
SQL Server 类型的常量现在直接从mssql_python模块中暴露出来,这使你在声明参数类型或读取类型元数据时更容易找到它们。
有关详细信息,请参阅 数据类型映射。
故障修复
并发日志可能会让进程卡住
原生日志路径获取 GIL 和内部互斥组的顺序不一致,因此启用驱动日志的多线程应用程序可能会死锁。 加锁顺序已修正。
Windows ARM64 轮毂不包含 ARM64 原生核心
Windows ARM64 轮盘没有提供匹配的 ARM64 mssql_py_core 二进制文件,这影响了该平台上的批量复制。 现在轮子装的是ARM64版本。
更多信息请参见 批量副本。
捆绑的 Windows DLL 依赖进程搜索路径
软件包附带的驱动程序和身份验证 DLL 现在从软件包本地目录中加载。 原生依赖项的解析无需依赖进程范围内的搜索路径配置,而这种配置在某些部署环境中并不可靠。
Decimal 参数会根据其值以不同方式绑定
Decimal参数现在无论运行时值如何都被绑定为 ,SQL_NUMERIC因此十进制参数类型在不同值和执行路径上保持不变。
更多信息请参见 十进制和货币数据。
参数绑定使用了过时的 ODBC 2.x 类型标识符
类型参数现在使用ODBC 3.x类型标识符替代ODBC 2.x的对应标识符,避免与当前驱动配置不匹配。
Connection.getinfo(SQL_DATABASE_NAME) 返回一个未解码的值
返回的值SQL_DATABASE_NAME已被解码,数据库名称以 Python 文本形式返回。
更多信息请参见 连接管理。
解释器关闭时游标清理崩溃
一个连接中存在混合生命周期状态的光标会按顺序清理它们,但当部分清理在解释器关闭时运行时,可能会导致进程崩溃。 关机现在正常完成。
更多信息请参见光标管理。
MSSQL-Python 1.14.0
发布日期:2026年8月
改进
参数检测和绑定在本地代码中运行
参数类型检测和绑定现在通过单一的原生管道执行,而不是对每个参数分别进行 Python 调用。 这一变化解决了一个重大的性能瓶颈,在大型作业如批量插入中实现了更高的端到端吞吐量提升。 无需更改申请。
故障修复
传递给 connect() 的 timeout 参数设置的是查询超时,而不是身份验证超时
timeout 参数现在会设置 SQL_ATTR_LOGIN_TIMEOUT,并限定认证尝试的范围,这也正是该参数名称和文档中所描述的。 早期版本中,它变成了每语句查询超时,因此 connect(timeout=30) 不限制连接尝试的持续时间,且在30秒后终止查询。 每条语句的查询超时仍可作为 Connection.timeout 属性使用。
Important
如果你将 timeout 传递给 connect() 以中止长时间运行的查询,这种行为将不再发生。 改为设置 Connection.timeout。 如果你依赖 bulkcopy() 来增大 connect(timeout=) 用于其内部连接的连接超时时间,也是如此:请在创建游标之前设置 Connection.timeout。
更多信息请参见 连接超时。
timeout=0 被 bulkcopy() 拒绝
timeout 为 0 时引发了验证错误,尽管 0 在底层批量复制 API 中表示无超时。 该方法现在接受 0 并禁用操作超时。 负值、非整数值和布尔值仍然被拒绝。
更多信息请参见 批量副本。
清理操作替换了原来的 Arrow 提取异常
当从 Arrow 读取器获取数据失败时,驱动程序的清理流程又引发了第二个错误,覆盖了原始错误,因此调用方看到的是清理失败,而不是获取失败的原因。 清理现在先检查光标状态,并保留原始例外。
executemany() 十进制转换错误包含参数值
executemany() 中的十进制转换失败通过链式异常报告了违规值,这可能会导致客户数据进入应用程序日志和监视系统。 错误现在只报告行索引、列索引和值类型。
有关详细信息,请参阅错误处理。
批量复制拒绝了 Arrow View 类型
bulkcopy_arrow() 无法处理可变长度的 Arrow View 数组,因此 Polars DataFrame.to_arrow() 列必须先用 string_view 进行转换。 字符串视图的值和 NULL 值现在可直接通过 Arrow C 数据接口传递。
更多信息请参见 极地积分。
Windows 扩展加载使用主机的 CPU 架构
在 Windows 上,驱动根据主机 CPU 而非运行的解释器选择原生扩展,因此 ARM64 主机上的 x64 Python 通过备用路径加载并向 stdout 写入通知。 加载器现在会根据解释器确定架构,并将回退情况作为警告报告。
MSSQL-Python 1.13.0
发布日期:2026年8月
改进
ODBC 驱动程序二进制文件仅随 mssql-python-odbc 提供
1.13.0 版本从 mssql-python wheel 包中移除了 libs/ 回退机制,并在 install_requires 中声明了 mssql-python-odbc==18.6.2.1。 命令 pip install mssql-python 仍会生成一个可正常工作的驱动程序。 使用 mssql-python-odbc 安装时,请显式安装 --no-deps;或者在使用未镜像该包的私有索引时,也请显式安装 --no-deps。
有关详细信息,请参阅安装。
从 Apache Arrow 源批量复制
新cursor.bulkcopy_arrow()方法加载的是已经以Apache Arrow格式存在的数据,但不会先将每一行转换成Python对象。 将 Arrow 数据源传递给 bulkcopy() 现在会引发 TypeError。
有关更多信息,请参阅 Apache Arrow 集成和批量复制。
token_providerMicrosoft Entra 凭据参数
函数connect()和Connection类token_provider接受参数,因此你可以传递凭证对象DefaultAzureCredential,而不是在连接字符串中指定认证模式。 该参数与 Authentication 关键字以及通过 attrs_before 传递的令牌互斥,且仅支持 Azure 商业云范围。
有关详细信息,请参阅 Microsoft Entra 身份验证。
身份感知连接池
连接池现在会按 Microsoft Entra 身份区分连接。 在早期版本中,连接池仅基于连接字符串进行区分,因此可能会将一个以某用户身份通过身份验证的连接提供给另一用户发起的请求。 驱动程序还仅在连接请求未命中连接池时才获取令牌,并在池化连接的令牌距离到期不足5分钟时刷新该连接。
有关详细信息,请参阅连接池。
故障修复
executemany() 当第一行之后出现 NULL 时,插入了零行
当首行之后出现首个 NULL 值时,混合了非 NULL 和 NULL 数值的 executemany() 调用插入了零行且未引发异常。 这种行为影响了 tinyint、 smallint、 int 和 float 参数。 驱动程序现在会在数组执行前,为每个固定宽度的数值参数初始化ODBC指示符。
SQL_WVARCHAR输出转换器对非串列进行变换
注册单个字符串转换器也会转换 int、decimal 和 date 值,因为驱动程序会对任何没有其自身转换器的列回退到 SQL_WVARCHAR 转换器。 驱动程序现在仅在该列映射到的 Python 类型为 str 或 bytes 时才使用该回退方案。
由整数SQL类型代码注册的输出转换器从未运行
以整数 SQL 类型代码注册的转换器(例如 SQL_DECIMAL)会被存储起来,但始终不会被调用,因为驱动程序仅根据 cursor.description 中的 Python 类型进行分派。 驱动程序现在首先根据整数代码进行分派,然后根据 Python 类型,最后根据 SQL_WVARCHAR 回退。
Important
如果你在早期版本中用整数SQL类型的代码注册转换器,升级后这些转换器就会开始运行。 部署前请先审查,因为之前未更改的列值现在会被转换。
更多信息请参见 “定制类型转换器”。
关闭 Arrow 读取器未释放服务器端游标
关闭 Arrow 读取器会使服务器端光标被分配,父 Cursor 光标处于不一致状态,因为 cursor.arrow_reader() 返回了原始 pyarrow.RecordBatchReader。 该方法现在返回一个包装器,其 close() 方法释放服务器端光标并重置光标状态,封装器作为上下文管理器工作。
更多信息请参见 Apache Arrow集成。
部分初始化的光标在 Cursor.__del__ 中引发了 AttributeError
初始化失败的游标在垃圾回收期间以不可引发的异常形式引发了 AttributeError。
Cursor.__init__ 在设置 closed 和 hstmt 属性之前被引发,__del__ 随后尝试读取这些属性。 初始化器现在会在任何代码产生前设置这两个属性,并 __del__ 保护日志调用,确保在解释器关闭时保持安全。
MSSQL-Python 1.12.0
发布日期:2026年7月
改进
独立 mssql-python-odbc 配套包
ODBC 驱动程序二进制文件现已作为 mssql-python-odbc 单独发布,它是一个仅包含数据、版本固定为 18.6.2 的配套包。 你不需要更改任何代码,因为 pip install mssql-python 会安装配套包。 本机加载器会优先使用配套包,并在配套包不存在时回退到 mssql-python wheel 中捆绑的二进制文件。
有关详细信息,请参阅安装。
故障修复
cursor.bulkcopy() 现在使用父连接的连接超时
bulkcopy() 现在使用其父连接的连接超时,您用 connect(..., timeout=<seconds>)设置了该超时值。 之前,批量复制打开的独立连接使用的是一个硬编码的 15 秒连接超时,而且无法通过 Python 覆盖。 使用 timeout=0 创建的父连接仍使用默认的 15 秒设置。
更多信息请参见 批量副本。
cursor.bulkcopy() 支持 CLR 用户自定义类型列
cursor.bulkcopy()此前对于任何使用通用语言运行时(CLR)用户定义类型的目标列都会因 而失败,包括内置的 geography、geometry 和 Protocol Error: Unsupported TDS type for bulk copy: 0xF0 类型。 驱动程序现在会在传输中将 CLR UDT 列映射为 varbinary(max),并将你提供的字节作为 UDT 的 IBinarySerialize 负载以流方式传输。 修复版本在 mssql_py_core 0.1.7版本发布。
MSSQL-Python 1.11.0
发布日期:2026年7月
改进
改进的上下文管理器语义
with connection: 现在,当块干净利落地退出时提交事务,并在异常离开块时回滚该事务。
有关详细信息,请参阅 事务管理。
故障修复
- 修复了 ODBC 拆卸路径(
conn.close()和cursor.close())以及 SSH 隧道和进程内转发器设置中SQLDescribeParam值为None参数的 GIL 死锁。 - 修复了临时表和表变量中的
BINARY和VARBINARYNULL 参数问题。 当自动类型解析失败时,驱动程序会发出带有明确cursor.setinputsizes()指导的 Python 警告。 - 修复了在全新安装时在 Apple Silicon 上
import mssql_python失败的问题(1.8.0 中的回归)。 随附的 ODBC dylib 依赖项现已针对arm64和x86_64两种架构重写。 - 修复了 Rust 核心中的一个 GIL 死锁问题,该问题会在使用
Authentication=ActiveDirectoryServicePrincipal进行身份验证时导致批量复制操作卡死。
MSSQL-Python 1.10.0
发行日期:2026年6月
改进
ActiveDirectoryServicePrincipal 对批量复制的支持
cursor.bulkcopy() 现支持 Authentication=ActiveDirectoryServicePrincipal,因此您可以使用服务主体凭据进行批量导入。
更多信息请参见批量复制和 Microsoft Entra 认证。
故障修复
- 修复了 Arrow 获取路径中的非 ASCII
VARCHAR和CHAR数据。 - 修复了批量加载操作期间的连接超时问题。
MSSQL-Python 1.9.0
发行日期:2026年6月
改进
批量复制中的行对象
cursor.bulkcopy() 现在直接接受获取的 Row 对象,无需手动转换为元组。
故障修复
- 修复了 wheel 打包,使
simdutf始终静态链接。 - 修复了
executemany()中的大型DECIMAL插入。 - 修复了 NULL 参数的错误类型回退。
- 修复了异常的 pickle 和 unpickle 往返。
- 已修复
nextset(),使其能够在各个结果集之间保留PRINT消息。 - 修复了
executemany()数据执行时回退路径中的Row处理。 - 修复了静态分析工具对 fetch 方法的类型检查问题。
MSSQL-Python 1.8.0
发行日期:2026年5月
改进
ActiveDirectoryMSI 对批量复制的支持
cursor.bulkcopy() 现在支持用于系统分配和用户分配托管身份的 Authentication=ActiveDirectoryMSI。
更多信息请参见批量复制和 Microsoft Entra 认证。
行字符串键索引
例如,你现在除了位置索引和属性访问外,还可以通过列名 row["col"]访问行值。
更多信息请参见 行对象。
随附 ODBC 驱动程序升级
捆绑的 Microsoft ODBC SQL Server 驱动更新至 18.6.2.1。
故障修复
- 修复了基于令牌认证的延迟连接属性生命周期问题。
- 修复了认证路径中重复的 连接字符串 解析问题。
- 修复了序列输入的
executemany()类型注解。
MSSQL-Python 1.7.1
发行日期:2026年5月
改进
扩展轮毂覆盖范围与性能提升
此版本包括:
- 支持RHEL 8的轮毂。
- 恢复了 macOS Python 3.10
universal2wheel 包。 - 通过
simdutf改进了 UTF-16 处理。 - 优化
execute()热路径。
性能影响:由于方法中的 execute() 热路径优化,批处理吞吐量有所提升。
有关详细信息,请参阅安装。
故障修复
- 修复了身份验证失败的问题,使其在失败时抛出
mssql_pythonDB-API 异常,而不是RuntimeError。 - 扩展了跨阻塞 ODBC 执行、提取、事务和连接属性调用的 GIL 释放。
- 修复了小数值变号时的
executemany()故障。 - 修复了跨平台解码不一致的CP1252
VARCHAR问题。 - 已修复
cursor.bulkcopy()和NVARCHAR(MAX)列中空字符串导致的VARCHAR(MAX)故障。
注释
1.7.0版本因发布问题被撤回。 使用1.7.1或更高版本。
MSSQL-Python 1.6.0
发行日期:2026年4月
改进
基于解析器的连接字符串清理
连接字符串清理现在使用解析器而不是正则表达式,因此,密码字段中包含特殊字符以及用花括号括起来的值的连接字符串都能被正确解析。
有关详细信息,请参阅连接字符串。
故障修复
- 修复了阻塞 ODBC 连接和断开连接操作期间的 GIL 释放。
- 修复了带有
SQL_DECIMAL和SQL_NUMERIC提示的setinputsizes()崩溃。 - 修复了 ODBC 目录方法的
fetchone()行为不正确的问题。 - 修复了使用
reset_cursor=False时出现的无效光标状态错误。 - 修复了基于映射的参数序列的
executemany()类型提示。 - 为
setup_logging(log_file_path=...)添加了路径遍历保护。
MSSQL-Python 1.5.0
发行日期:2026年4月
新增功能
Apache Arrow 提取支持
三种新的游标方法通过 Arrow C Data Interface 提供高性能的列式数据检索:
-
cursor.arrow()返回一个完整的pyarrow.Table。 -
cursor.arrow_batch()返回一个pyarrow.RecordBatch。 -
cursor.arrow_reader()返回用于流式传输的pyarrow.RecordBatchReader。
这些方法不会为每个值创建一个 Python 对象。 完整文档请参见 Apache Arrow集成。
sql_variant 类型支持
驱动程序现在会在提取数据时识别 sql_variant 列,解析其底层基础类型,并返回类型正确的 Python 值,而不是原始字节。
注释
sql_variant 列使用流式取用路径,这与固定类型列相比可能会有轻微的性能影响。
有关详细信息,请参阅 数据类型映射。
原生UUID支持
一个新的 native_uuid 设置用于控制是否将 UNIQUEIDENTIFIER 列返回为 uuid.UUID 对象(默认),还是返回为兼容 pyodbc 的大写字符串。 可在模块级别或按连接进行配置。
更多信息请参见 模块配置。
Row 类公共导出
Row该类现已在顶层导出,以供类型注解使用。
更多信息请参见 行对象。
故障修复
- 修复了括号内标识符、字符串文本和注释内的误报
?检测。 - 修复了针对
VARBINARY列的 NULL 参数绑定问题(不再引发隐式转换错误)。 - 修复了
TIME(1)通过TIME(7)列的datetime.time值在往返中丢失微秒的问题。 - 修复了 Arrow 提取路径以正确包含
TIME列的小数秒。 - 修复了使用 Microsoft Entra ID 身份验证方法时的批量复制问题(陈旧的凭据字段不再导致验证错误)。
- 模块级缓存 Azure 身份凭证实例以提升认证性能。
MSSQL-Python 1.4.0
发布日期:2026年2月
新增功能
批量复制支持
现已可通过 cursor.bulkcopy() 实现高性能批量数据加载。 该方法接受 batch_size、timeout、column_mappings、keep_identity、check_constraints、table_lock、keep_nulls、fire_triggers 和 use_internal_transaction 的选项。
更多信息请参见 批量副本。
Improvements
- 针对大型结果集的性能优化。
- 减少批处理操作中的内存使用。
- 增强了批量复制失败时的错误消息。
MSSQL-Python 1.3.0
发布日期:2026年1月
新增功能
Settings 类
通过新Settings类配置模块范围的行为,lowercase其中包含列名设置。cursor.description
更多信息请参见 模块配置。
Improvements
- 改进了 Azure SQL 故障切换期间对连接超时的处理。
- 改进了与 Python 3.13 的兼容性。
MSSQL-Python 1.2.0
发布日期:2026年1月
新增功能
模式发现方法
新的游标方法可用于探索数据库元数据:tables()、columns()、getTypeInfo()、primaryKeys()、foreignKeys()、procedures()以及 statistics()。
更多信息请参见 图式发现。
Improvements
- 增强的元数据缓存,支持重复模式查询。
- 更好地处理
columns()结果中的计算列。
MSSQL-Python 1.1.0
发布日期:2025年12月
新增功能
定制输出转换器
注册自定义函数,以便在获取时使用 add_output_converter()、get_output_converter()、remove_output_converter() 和 clear_output_converters() 转换列值。
更多信息请参见 “定制类型转换器”。
Improvements
- 类型转换失败时提供更好的错误消息。
- 支持返回
None的转换器函数。
MSSQL-Python 1.0.0
发布日期:2025年11月
初始正式发布 (GA)
MSSQL-python 的第一个正式发布版本,是 Microsoft 为 SQL Server 开发的原生 Python 驱动。
更多信息请参见 mssql-python 驱动。
核心功能
- DDBC 架构:无需安装 ODBC 驱动程序即可实现直接数据库连接。
- DB-API 2.0 合规性:标准 Python 数据库接口。
- 连接池:内置连接池管理。
- Microsoft Entra 身份验证:对基于 Azure 身份的身份验证的全面支持 。
- TLS 加密:通过证书验证安全连接。
连接功能
- 21 个连接字符串关键字
- 9种认证模式(SQL、Windows 和 7 种 Microsoft Entra ID 方法)。
- 自动提交控制。
- 执行方法:
execute()、、executemany()batch_execute()和 。 - 通过
set_attr()和getinfo()传递的连接属性。 - 上下文管理器支持。
光标特征
- 标准获取方法:
fetchone()、fetchmany()、fetchall()。 - 扩展方法:
fetchval(),skip()。 - 执行方法:
execute()和executemany()。 - 可通过属性和索引访问的行对象。
- 使用
nextset()进行多结果集导航。
数据类型支持
- 所有 SQL Server 原生类型。
- Python↔SQL 类型映射。
- 用于显式键入的 SQL 类型常量(例如
mssql_python.SQL_DECIMAL)。 - NULL 作为 Python
None处理。
事务支持
- 手动提交和回滚。
- 自动提交模式。
- 隔离层控制。
- 死锁检测与处理。
身份验证模式
| Mode | 描述 |
|---|---|
| SQL Server 身份验证 | 用户名和密码 |
| Windows 身份验证 | Trusted_Connection |
| ActiveDirectoryDefault | DefaultAzureCredential |
| ActiveDirectoryInteractive | 基于浏览器的登录 |
| ActiveDirectoryDeviceCode | 设备代码流 |
| Active Directory 密码 | Microsoft Entra 用户名和密码(已弃用;使用ROPC系统) |
| ActiveDirectoryMSI | 托管标识 |
| ActiveDirectoryServicePrincipal | 服务主体 |
| Active Directory 集成 | Windows Kerberos |
Upgrade
来自 pyodbc
有关详细迁移指南,请参见 “从 pyodbc 迁移”。
主要区别:
-
?(qmark)和%(name)s(pyformat)这两种参数样式都受支持。 你现有的?查询无需做任何更改即可正常运行。 - 没有
callproc()方法。 改用EXECUTE语句。 - 内置连接池。
- 没有外部 ODBC 驱动依赖。
来自 pymssql
有关详细迁移指南,请参见 从 pymssql 迁移。
主要区别:
- 将参数
%s标记替换%d为?或%(name)s。 - 请使用连接字符串,而不是位置参数。
- 没有FreeTDS依赖。
- 每个连接支持多个并发光标。
- 具有属性访问的行对象替换
as_dict=True。
mssql-python 版本之间
升级驱动以获得新功能和修复。
pip install --upgrade mssql-python
在升级生产系统之前,请先查阅发行说明,确认是否存在任何破坏性更改。
路线图
有关即将推出的功能和开发路线图,请参见 GitHub 仓库。