本文按最新版本在前的顺序列出了 mssql-python 驱动在各个版本中的更改内容。 每个章节都涵盖一个版本的新功能、行为变更和bug修复。
关于 Microsoft 目前支持的版本，请参见支持生命周期。
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。
更多信息请参见 连接超时。
bulkcopy() 拒绝 timeout=0
timeout 为 0 时引发了验证错误，尽管 0 在底层批量复制 API 中表示无超时。 该方法现在接受 0 并禁用操作超时。 负值、非整数值和布尔值仍然被拒绝。
更多信息请参见 批量副本。
清理操作替换了原来的 Arrow 提取异常
当从 Arrow 读取器获取数据失败时，驱动程序的清理流程又引发了第二个错误，覆盖了原始错误，因此调用方看到的是清理失败，而不是获取失败的原因。 清理现在先检查光标状态，并保留原始例外。
executemany() 包含参数值的十进制转换误差
executemany() 中的十进制转换失败通过链式异常报告了违规值，这可能会导致客户数据进入应用程序日志和监视系统。 错误现在只报告行索引、列索引和值类型。
有关详细信息，请参阅错误处理。
批量复制拒绝了 Arrow View 类型
bulkcopy_arrow() 无法处理可变长度的 Arrow View 数组，因此 Polars 的 string_view 列必须先使用 DataFrame.to_arrow() 进行转换。 字符串视图的值和 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_provider Microsoft 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) 用户定义类型的目标列都会因 Protocol Error: Unsupported TDS type for bulk copy: 0xF0 而失败，其中包括内置的 geography、geometry 和 hierarchyid 类型。 驱动程序现在会在传输中将 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 仓库。