使用 mssql-odbc 驱动（预览版）

mssql-python 加载两个原生ODBC提供商之一：

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server Default
mssql-odbc 基于Rust的ODBC驱动 预览，选择启用

mssql-python-rs 包含 mssql-odbc 提供程序。

Note

将 msodbcsql18 用于生产工作负载。 在选择预览 mssql-odbc 服务商之前，先查看其 已知问题。

Availability

该驱动程序作为预构建的 wheel 包包含在 mssql-python-rs 软件包中，适用于 CPython 3.10 及更高版本：

Platform Architectures
Windows x64;CPython 3.11及后续版本上的ARM64
macOS Universal 2（x86_64 和 Arm64）、macOS 15 及更高版本
Linux （glibc） x86_64 和 aarch64 （manylinux_2_28 和 manylinux_2_34）
Linux（musl） x86_64 和 aarch64 （musllinux_1_2）

启用驱动程序

安装 mssql-python 时还会安装 mssql-python-rs，其中包含驱动程序 mssql-odbc ：

python -m pip install mssql-python

如果你用 --no-deps 安装，或从私有索引安装，也要明确安装 mssql-python-rs 。

在打开第一个连接前选择提供商。 使用以下方法之一。

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

将 MSSQL_CONNECTION_STRING 环境变量设置为你的应用程序的连接字符串。 保持证书验证处于启用状态 (Encrypt=yes;TrustServerCertificate=no)。 更多信息请参见 连接字符串 、 加密和证书。

请用你选择的供应商运行这个示例：

import os
import mssql_python

with mssql_python.connect(os.environ["MSSQL_CONNECTION_STRING"], timeout=45) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT 1")
        print(cursor.fetchone()[0])

示例输出 1。

提供者选择遵循以下规则：

  • MSSQL_PYTHON_NATIVE_PROVIDER 优先于 native_provider。 将该属性设置为冲突的提供程序时，会发出RuntimeWarning。
  • 在驱动加载前，设置native_provider为None以清除 Python 设置值。 这并不会清除环境变量。
  • 未识别的服务提供者名称会引发 ValueError。 为 native_provider 分配无效名称会立即引发错误；无效的环境变量在连接时会引发错误。 驱动程序不会回退到默认提供商。
  • 当驱动程序开始本地连接尝试时，提供程序即被固定，即使该尝试失败。 重启 Python 以更换提供程序。 换成其他服务商会触发 RuntimeWarning，但没有任何影响。

连接字符串验证错误和缺少提供者包会在此之前发生。 你可以纠正这些错误，选择其他供应商而无需重启。

调用 mssql_python.get_native_provider_info() 确认服务提供者名称、选择方式以及选择是否固定。

要返回到msodbcsql18，请从应用程序中移除MSSQL_PYTHON_NATIVE_PROVIDER和任何native_provider分配，然后重启 Python。

多子网故障转移默认值

Rust 提供商默认对适用的传输控制协议（TCP）连接启用 MultiSubnetFailover。 显式设置 MultiSubnetFailover=no 以请求按顺序进行连接尝试。 要更改部署范围的默认值，请在首次使用原生驱动之前，将 MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT 设置为 false 或 true。 连接字符串关键字覆盖了该默认值。

SQL_COPT_SS_MULTISUBNET_FAILOVER数字属性（1248）在连接前设置时也会覆盖关键词。

驱动程序不对此默认值启用非 TCP 传输、数据库镜像、需要 SQL Server 浏览器发现的命名实例，或省略显式协议和地址的本地 Windows 连接。 为非 TCP 传输、数据库镜像或 SQL Server Browser 发现显式启用 MultiSubnetFailover 会引发连接错误。 更多信息请参见 高可用性和故障切换。

支持的功能

以下功能受已知问题限制，仍受支持。

Area 备注
连接生命周期 连接、close()、with 阻止、登录超时、诊断，以及更改当前数据库。 连接字符串设置包括 IpAddressPreference、PacketSize、KeepAlive、ConnectRetryCount、 / 和 ConnectRetryIntervalMultiSubnetFailoverApplicationIntent（空闲连接弹性）。 本地驱动还会协商服务器辅助的域名系统（DNS）缓存和增强路由，当服务器支持时。
Authentication SQL 认证（UID / PWD）；Windows 身份验证（Trusted_Connection=Yes，在 Windows 上使用安全支持提供程序接口 (SSPI)，或在 Linux 和 macOS 上使用 Kerberos）；以及 Microsoft Entra ID 交互式、集成、设备代码、服务主体、托管身份、默认凭据和访问令牌。 不支持Microsoft Entra ID密码认证。 有关详细信息，请参阅 已知问题。
传输层安全性 （TLS） Encrypt、TrustServerCertificate、HostnameInCertificate 和 ServerCertificate。
查询执行 直接执行与预备执行、预备计划重用、qmark 参数，以及 mssql-python 所执行的 pyformat 转换。
ODBC 转义语法 函数、日期/时间、外连接、全局唯一标识符（GUID）、LIKE ... {escape ...}、间隔和 {encrypt ...} 转义形式。
存储过程 用 Transact-SQL（T-SQL）或位置{call ...}语法通过execute()调用它们，读取结果集，并用nextset()推进。
输入参数 标量参数、SQL NULL、SQL setinputsizes() 以及混合的常规/流式参数。
较大参数 大文本、二进制、可扩展标记语言（XML）和用户定义类型（UDT）参数支持执行时数据流式传输。
executemany() 使用 ODBC 参数数组批量处理。 包含流式值的行会回退为逐行执行。
行提取 fetchone()、fetchmany()、fetchall()、迭代、fetchval()、类型化转换，以及大型文本/二进制流式处理。
Arrow 提取 arrow_batch()、 arrow()和 arrow_reader()。 需要 pyarrow。
多个结果集 nextset()，包括参数数组产生的结果。
Transactions 自动提交、提交、回滚，以及读未提交、读已提交、可重复读、可序列化和快照隔离级别。 关闭自动提交后，连接上下文管理器在成功退出时提交，遇到异常时回滚。
查询超时 在创建光标前，以秒为单位设置 Connection.timeout。 当语句超过超时时，驱动程序引发 OperationalError。 0 表示没有超时。 使用connect(timeout=...)分别设置登录超时。
连接池 内置的 mssql-python 连接池，包括重用前重置连接。 关于特定于身份验证的池隔离，请参见 身份隔离。
元数据 API tables()、、columns()、primaryKeys()foreignKeys()、statistics()、rowIdColumns()、rowVerColumns()、、 procedures()和getTypeInfo()。
编码与转换器 默认宽字符编码、输出转换器和支持排序规则的非 Unicode 参数，包括 UTF-8 和遗留的 SQL 排序 ID 排序规则。 自定义窄字符解码必须与客户端代码页匹配。 有关详细信息，请参阅 已知问题。

Microsoft Entra ID集成认证使用Windows上登录的Windows账户。 在 Linux 和 macOS 上，它使用 Kerberos 工单认证租户的 Active Directory 联合身份验证服务（AD FS）端点。 关于先决条件，请参见 Windows 集成认证。

关闭 arrow_reader() 会发送 SQLCancel 以中断正在进行的提取。 close 调用会等待取消清理完成。 更多信息请参见 Apache Arrow集成。

数据类型

驱动程序以 Python 对象的形式返回 str、json 和 vector 值，其中 vector 表示为 JavaScript 对象表示法（JSON）数组。 它返回常见的语言运行时（CLR）类型，如 geometry、geography 和 hierarchyid，作为 Python bytes 对象。 更多信息请参见 数据类型映射 和 已知问题。

已知问题

在从 msodbcsql18 切换工作负载前，先检查这些差异。

Issue Details Workaround
Microsoft Entra ID 密码认证 不支持 Authentication=ActiveDirectoryPassword。 该方法无法通过多重身份验证（MFA）。 SQL认证（UID / PWD）不受影响。 使用其他 Microsoft Entra ID 方法，如服务主体、托管身份或访问令牌。
attrs_before设置 Microsoft Entra ID 的认证模式和应用意图不能设置为数字连接属性。 使用 Authentication 和 ApplicationIntent 连接字符串关键词。
连接操作超时 SQL_ATTR_CONNECTION_TIMEOUT 控制取消时的清理。 它不会对池化连接重置强制执行超时。 如果服务器在重置时停止响应，连接请求可能会被阻挡。 没有可用的池化重置超时。 将 connect(timeout=...) 设为登录，将 Connection.timeout 设为对账单。
多地址主机 msodbcsql18 默认启用透明网络 IP 解析（TNIR）；mssql-odbc 不支持 TNIR。 mssql-python 在使用任一提供程序时都会拒绝 TransparentNetworkIPResolution 连接字符串关键字。 将 MultiSubnetFailover=yes 用于可用性组侦听器和其他多地址主机。 有关默认设置，请参见多子网故障转移默认设置。
数据分类 敏感度分类元数据不可用，并且不支持 SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400)。 查询 sys.sensitivity_classifications。
fork() 连接后 在 Linux 上，父进程连接后 fork 出的进程在使用驱动时可能会卡住，即使使用新的连接。 启用池化后，父节点也会挂起。 （#566） 使用 spawn 启动方法，并在每个辅助角色中建立连接。
Linux 上的原生追踪 启用原生追踪后，Python 可以在进程退出时的驱动清理期间中止。 Linux上保持 MSSQL_TDS_TRACE 不设置。
未读结果 关闭光标或运行另一个语句会读取并丢弃剩余结果，而不是取消这些结果，这可能会很慢。 准备语句清理使用该语句的查询超时，但超时为零则该清理无界。 只取你需要的行，比如用 TOP，然后在创建光标前设置 Connection.timeout 。
自定义窄字符解码 原生驱动在 Windows 上使用 Windows 的 ANSI 代码页，在 Linux 和 macOS 上使用进程区域设置的代码页来处理窄文本。 如果显式 Python 解码与该代码页不匹配，可能会产生错误的文本或 bytes。 使用默认的宽字符解码： conn.setdecoding(mssql_python.SQL_CHAR)。
Connection.getinfo() 某些能力值和基于数据包大小的限制与 msodbcsql18不同。 SQL_USER_NAME 报告数据库主体，而非连接字符串 UID。 当所声明的功能或限制对你的应用有影响时，查询具体服务器元数据。
内存不足故障 一些驱动程序分配失败会终止 Python 进程，而不是引发MemoryError异常。 （#484） 限制你发送和取回的值大小。
大值读取性能 varchar(max)和nvarchar(max)数据的分块读取速度可能比使用msodbcsql18时更慢。 （#473） 对你的工作负载进行基准测试。

报告问题

如果遇到缺陷，请使用 msodbcsql18 重现，并记录在两个提供程序中是否都会发生。 关于切换说明，请参见 启用驱动程序。

在报告中包含 mssql_python.get_native_provider_info() 的输出、您的操作系统、Python 和驱动版本，以及失败的 T-SQL 批处理和错误信息：

在 Windows 上，在启动 Python 前先在 PowerShell 中设置这些变量，以便收集本地驱动的诊断数据。 在选中 mssql-odbc 的情况下重现问题：

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = ".\traces"

MSSQL_TDS_TRACE 启用追踪，MSSQL_TDS_TRACE_LEVEL 选择日志级别，并且 MSSQL_TDS_TRACE_DIR 选择由本地 ODBC 驱动程序生成的每进程跟踪文件的目录，而非标准错误输出。 Rust配套包也会在当前目录下 mssql_python_logs 创建日志文件。

跟踪可以包含 T-SQL 文本和参数值。 在分享摘录前请对敏感数据进行遮蔽。 诊断后，移除这些变量并重启 Python 以禁用追踪功能。

相关内容

  • 上次更新时间为