mssql-python 中的新增功能

每个 mssql-python 驱动版本都会引入新功能、性能提升和漏洞修复。 以下章节详细介绍了每个版本。

MSSQL-Python 1.11.0

上映日期：2026年7月

改进

改进的上下文管理器语义

with connection: 现在能够在正常退出时正确提交事务，并在发生异常时回滚事务，使其更符合 Python 风格，行为也更可预测。

import mssql_python

# On clean exit, transaction commits
with mssql_python.connect(connection_string) as conn:
    cursor = conn.cursor()
    cursor.execute("INSERT INTO MyTable (Name) VALUES ('Alice')")
    # Automatically committed on exit

# On exception, transaction rolls back
try:
    with mssql_python.connect(connection_string) as conn:
        cursor = conn.cursor()
        cursor.execute("INSERT INTO MyTable (Name) VALUES ('Bob')")
        raise ValueError("Oops!")
except ValueError:
    pass
# Changes rolled back on exit

故障修复

• 修复了 ODBC 清理路径（conn.close() 和 cursor.close()）中的 GIL 死锁，以及在 SSH 隧道和进程内转发器设置中，针对 None 值参数的 SQLDescribeParam 中的 GIL 死锁。
• 修复了临时表和表变量中的 BINARY 和 VARBINARY NULL 参数问题。 当自动类型解析失败时，驱动程序会发出带有明确cursor.setinputsizes()指导的 Python 警告。
• 修复了 import mssql_python 在 Apple Silicon 上全新安装时无法运行的问题（1.8.0 中的回归问题）。 随附的 ODBC dylib 依赖项现已针对 arm64 和 x86_64 两种架构重写。
• 修复了 Rust 核心中的一个 GIL 死锁问题，该问题会在使用 Authentication=ActiveDirectoryServicePrincipal 进行身份验证时导致批量复制操作卡死。

MSSQL-Python 1.10.0

发布日期：2026 年 6 月

改进

ActiveDirectoryServicePrincipal 对批量复制的支持

cursor.bulkcopy() 现已支持 Authentication=ActiveDirectoryServicePrincipal，允许使用服务主凭证进行批量插入。

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<application-client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes"
)
cursor = conn.cursor()
cursor.execute("CREATE TABLE ##SpDemo (ID INT, Value FLOAT)")
conn.commit()

result = cursor.bulkcopy("##SpDemo", [(1, 1.5), (2, 2.5)])
print(f"Copied {result['rows_copied']} rows")

故障修复

• 修复了 Arrow 获取路径中的非 ASCII VARCHAR 和 CHAR 数据。
• 修复了批量加载操作期间的连接超时问题。

MSSQL-Python 1.9.0

发布日期：2026 年 6 月

改进

批量复制中的行对象

cursor.bulkcopy() 现在可直接接受获取到的 Row 对象，而无需手动将其转换为元组。

import mssql_python

conn = mssql_python.connect(connection_string)
cursor = conn.cursor()

# Fetch rows from source table
cursor.execute("SELECT ProductID, Name, ListPrice FROM Production.Product")
rows = cursor.fetchall()

# Pass fetched Row objects directly to bulkcopy
cursor.execute("CREATE TABLE ##RowBulkDemo (ProductID INT, Name NVARCHAR(50), ListPrice MONEY)")
conn.commit()
result = cursor.bulkcopy("##RowBulkDemo", rows)
print(f"Copied {result['rows_copied']} rows")

故障修复

• 修复了 wheel 包的打包方式，使 simdutf 始终采用静态链接。
• 修复了 executemany() 中的大型DECIMAL插图。
• 修正了NULL参数的错误类型备份。
• 修复了异常对象在 pickle 和 unpickle 往返过程中的问题。
• 已修复 nextset()，使其能够在各个结果集之间保留 PRINT 消息。
• 修复了 executemany() 执行时数据回退路径中对 Row 的处理。
• 修复了静态分析工具对 fetch 方法的类型检查问题。

MSSQL-Python 1.8.0

发布日期：2026 年 5 月

改进

ActiveDirectoryMSI 对批量复制的支持

cursor.bulkcopy() 现在支持 Authentication=ActiveDirectoryMSI 系统分配和用户分配的托管身份。

import mssql_python

# System-assigned managed identity
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "Encrypt=yes"
)
cursor = conn.cursor()
cursor.execute("CREATE TABLE ##MsiDemo (ID INT, Name NVARCHAR(50))")
conn.commit()

result = cursor.bulkcopy("##MsiDemo", [(1, "Alice"), (2, "Bob")])
print(f"Copied {result['rows_copied']} rows")

行字符串键索引

例如，你现在除了位置索引和属性访问外，还可以通过列名 row["col"]访问行值。

import mssql_python

conn = mssql_python.connect(connection_string)
cursor = conn.cursor()

cursor.execute("SELECT ProductID, Name, ListPrice FROM Production.Product WHERE ProductID = 1")
row = cursor.fetchone()

# Access by column name (new in 1.8.0)
print(row["ProductID"]) # Access by key
print(row["Name"])

# Still supports positional indexing
print(row[0])           # Positional access

# And attribute access
print(row.Name)         # Attribute access

随附 ODBC 驱动程序升级

捆绑的 Microsoft ODBC SQL Server 驱动更新至 18.6.2.1。

故障修复

• 修复了基于令牌认证的延迟连接属性生命周期问题。
• 修复了认证路径中重复的 连接字符串 解析问题。
• 修复了序列输入的 executemany() 类型注解。

MSSQL-Python 1.7.1

发布日期：2026 年 5 月

改进

扩展轮毂覆盖范围与性能提升

该版本新增了兼容 RHEL 8 的 wheel 包，恢复了 macOS Python 3.10 universal2 wheel 包，通过 simdutf 改进了 UTF-16 处理，并优化了 execute() 热路径。

性能影响：由于方法中的 execute() 热路径优化，典型工作负载的批处理吞吐量提升了~15%。

故障修复

• 修复了登录失败时会引发 mssql_python DB-API 异常而不是 RuntimeError 的问题。
• 将 GIL 释放扩展到阻塞式 ODBC 执行、提取、事务和连接属性调用。
• 修复了小数值变号时的 executemany() 故障。
• 修复了跨平台解码不一致的CP1252 VARCHAR 问题。
• 已修复 NVARCHAR(MAX) 和 VARCHAR(MAX) 列中空字符串导致的 cursor.bulkcopy() 故障。

MSSQL-Python 1.6.0

发布日期：2026 年 4 月

改进

基于解析器的连接字符串清理

这一改进确保了密码字段和括号中特殊字符的正确解析。

import mssql_python

# Complex passwords with special characters now parse correctly
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "UID=user@contoso;"
    "PWD={p@ssw0rd;with{braces}};"  # Braced values now handled correctly
    "Encrypt=yes"
)

连接字符串清理已从基于正则表达式的逻辑改为基于解析器的处理，以正确处理 ODBC 连接字符串语法。

故障修复

• 修复了在阻塞式 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 值，而不是原始字节。

原生UUID支持

一个新的 native_uuid 设置用于控制是否将 UNIQUEIDENTIFIER 列返回为 uuid.UUID 对象（默认），还是返回为兼容 pyodbc 的大写字符串。 可在模块级别或针对每个连接进行配置：

# Module-level default
settings = mssql_python.get_settings()
settings.native_uuid = True  # default

# Per-connection override
conn = mssql_python.connect(connection_string, native_uuid=False)

更多信息请参见 模块配置。

行类公共导出

Row 类现已在顶层导出，可用于类型注释：

from mssql_python import Row

故障修复

• 修复了在带方括号的标识符、字符串字面量和注释中误报检测到 ? 的问题。
• 修复了针对 VARBINARY 列的 NULL 参数绑定问题（不再引发隐式转换错误）。
• 修复了 TIME(1) 至 TIME(7) 列在往返转换过程中 datetime.time 值丢失微秒精度的问题。
• 修复了 Arrow 获取路径，使其能够正确包含 TIME 列的小数秒。
• 修复了使用 Microsoft Entra ID 身份验证方法时的批量复制问题（陈旧的凭据字段不再导致验证错误）。
• 模块级缓存 Azure 身份凭证实例以提升认证性能。

MSSQL-Python 1.4.0

上映日期：2025年3月

新增功能

批量复制支持

现已可通过 cursor.bulkcopy() 进行高性能批量数据加载：

import mssql_python

conn = mssql_python.connect(connection_string)
cursor = conn.cursor()

cursor.execute("CREATE TABLE ##BulkDemo (ID INT, Name NVARCHAR(50), Price DECIMAL(10,2))")
conn.commit()

data = [
    (1, "Item 1", 10.50),
    (2, "Item 2", 20.75),
    # ... potentially millions of rows
]

result = cursor.bulkcopy("##BulkDemo", data)
print(f"Copied {result['rows_copied']} rows")

该方法接受 batch_size、timeout、column_mappings、keep_identity、check_constraints、table_lock、keep_nulls、fire_triggers 和 use_internal_transaction 的选项。

完整文档请参见 批量副本 。

Improvements

• 针对大型结果集的性能优化。
• 减少批处理操作中的内存使用。
• 增强了批量复制失败时的错误消息。

MSSQL-Python 1.3.0

上映日期：2025年1月

新增功能

设置类

通过新 Settings 类配置模块范围的行为：

import mssql_python

settings = mssql_python.get_settings()
settings.lowercase = True       # Lowercase column names in cursor.description

详情请参见 模块配置 。

Improvements

• 改进了 Azure SQL 故障切换期间对连接超时的处理。
• 改进了与 Python 3.13 的兼容性。

MSSQL-Python 1.2.0

上映日期：2024年11月

新增功能

模式发现方法

用于数据库元数据探索的新光标方法：

cursor = conn.cursor()

# List all tables
cursor.tables(schema="dbo")

# Get column information
cursor.columns(table="Product", schema="Production")

# Get primary keys
cursor.primaryKeys(table="Product", schema="Production")

# Get foreign key relationships
cursor.foreignKeys(table="SalesOrderDetail", schema="Sales")

# Get stored procedures
cursor.procedures(schema="dbo")

# Get index statistics
cursor.statistics(table="Product", schema="Production")

# Get type information
cursor.getTypeInfo()

完整文档请参见 模式发现 。

Improvements

• 增强的元数据缓存，支持重复模式查询。
• 在 columns() 结果中更好地处理计算列。

MSSQL-Python 1.1.0

上映日期：2024年9月

新增功能

定制输出转换器

注册自定义函数，以便在获取时转换列值：

import mssql_python
from decimal import Decimal

conn = mssql_python.connect(connection_string)

# Convert decimals to float (converter receives Decimal)
def decimal_to_float(value):
    if value is None:
        return None
    return float(value)  # value is already a Decimal object

conn.add_output_converter(mssql_python.SQL_DECIMAL, decimal_to_float)

# Custom money formatting
def format_money(value):
    if value is None:
        return "$0.00"
    return f"${float(value):,.2f}"  # value is already a Decimal object

conn.add_output_converter(mssql_python.SQL_DECIMAL, format_money)

管理方法：

• add_output_converter(sql_type, converter_func)
• get_output_converter(sql_type)
• remove_output_converter(sql_type)
• clear_output_converters()

完整文档请参见 “定制类型转换器”。

Improvements

• 类型转换失败时提供更好的错误消息。
• 支持返回 None 的转换器函数。

MSSQL-Python 1.0.0

上映日期：2024年7月

最初的通用版发布

MSSQL-python 的第一个正式发布版本，是 Microsoft 为 SQL Server 开发的原生 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）。
• 像 Python 一样处理 NULLNone。

事务支持

• 手动提交和回滚。
• 自动提交模式。
• 隔离层控制。
• 死锁检测与处理。

身份验证模式

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 仓库。

相关内容

• MSSQL-Python 驱动
• 支持生命周期
• 安装
• GitHub 发布