使用 mssql-odbc 驱动(预览版)

mssql-python 加载两种原生 ODBC 提供程序之一:

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server Default
mssql-odbc 基于Rust的ODBC驱动 预览版,选择加入

本文介绍了mssql-python-rs 0.5.0中附带的mssql-odbc提供程序及其与msodbcsql18有何不同。

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 以更换提供程序。 将 native_provider 更改为其他提供程序会发出 RuntimeWarning,但没有任何影响。

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

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

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

多子网故障转移默认值

对于符合条件的 TCP 连接,Rust 提供程序默认为 MultiSubnetFailover=yes 。 设置 MultiSubnetFailover=no 以按顺序尝试。 要更改部署默认值,请在首次使用驱动程序之前将 MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT 设置为 true 或 false(不区分大小写)。 其他值会导致错误,除非对连接进行了覆盖。

connection-string关键字会覆盖环境默认值。 pre-connect SQL_COPT_SS_MULTISUBNET_FAILOVER 属性 (1248) 会覆盖这两个属性。

默认选项排除非 TCP 传输、数据库镜像以及需要通过 SQL Server 浏览器发现的命名实例。 这些也拒绝显式的 MultiSubnetFailover=yes。

在 Windows 上,对于裸本地目标(例如 localhost.)也默认禁用。 显式的 TCP 前缀或端口(如 tcp:localhost 或 localhost,1433)可避免本地目标排除。 显式 MultiSubnetFailover=yes 也会覆盖该限制。 参见 高可用性和故障转移。

支持的功能

以下功能受支持,但受已知问题约束。

Area 备注
连接生命周期 连接、close()、with 阻止、登录超时、诊断,以及更改当前数据库。 连接字符串设置包括 IpAddressPreference、PacketSize、KeepAlive、ConnectRetryCount、 / 和 ConnectRetryIntervalMultiSubnetFailoverApplicationIntent(空闲连接弹性)。
网络韧性 符合条件的 TCP 连接默认使用并行地址尝试。 并行模式不会按 IpAddressPreference 对地址确定优先级,并且会拒绝超过 64 个已解析地址。 有关顺序尝试和地址族排序,请参见多子网故障转移默认值。 独立的透明网络IP解析(TNIR)算法尚未实现。 服务器辅助域名系统(DNS)缓存在服务器允许缓存的情况下,在成功登录后于 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。 在 macOS 上, Encrypt=Strict TCP 连接可以与兼容的服务器协商 TLS 1.3。
查询执行 直接执行与预备执行、预备计划重用、qmark 参数,以及 mssql-python 所执行的 pyformat 转换。
ODBC 转义语法 函数、日期/时间、外连接、全局唯一标识符(GUID)、LIKE ... {escape ...}、间隔和 {encrypt ...} 转义形式。
存储过程 通过 execute() 使用 Transact-SQL (T-SQL) 或位置 {call ...} 语法调用它们,读取结果集,然后使用 nextset() 推进。
输入参数 标量参数、SQL NULL、SQL setinputsizes() 以及混合的常规/流式参数。
较大参数 大文本和二进制参数通过普通绑定路径流向服务器。 当 Python 选择在执行时提供数据时,通过 str 的显式 bytes 和 bytearray 绑定也会流式传输:对于 setinputsizes(),声明的大小必须超过 4000;对于 SQL_SS_UDT 或 SQL_SS_XML,必须超过 8000。 用户自定义类型(UDT)绑定要求服务器描述参数的类型。 有些自定义和混合绑定仍然会缓冲。 有关详细信息,请参阅 已知问题。
executemany() 使用 ODBC 参数数组批量处理。 包含流式值的行会回退为逐行执行。
行提取 fetchone()、fetchmany()、fetchall()、迭代、fetchval()、类型转换以及大文本/二进制流式传输。
Arrow 提取 arrow_batch()、 arrow()和 arrow_reader()。 需要 pyarrow。
多个结果集 nextset(),包括由参数数组生成的结果。
Transactions 自动提交、提交、回滚,以及读未提交、读已提交、可重复读、可序列化和快照隔离级别。 关闭自动提交后,连接上下文管理器在成功退出时提交,遇到异常时回滚。
查询超时 在创建光标前,以秒为单位设置 Connection.timeout。 当语句超过超时时,驱动程序引发 OperationalError。 0 表示无超时。 使用 connect(timeout=...) 分别设置登录超时。
连接操作超时 conn.set_attr(mssql_python.SQL_ATTR_CONNECTION_TIMEOUT, seconds) 适用于连接所属的网络请求,包括提交、回滚以及目录和隔离变更。 池化重置将服务器重置推迟到后续的隔离级别设置请求;该请求及之前的任何回滚均使用此超时。 0 使这些请求不受限制。 该超时时间与登录和查询超时分开,且不是完整的池签出截止时间。 取消清理可能会增加调用耗时。
游标清理 关闭光标会在需要时取消待处理的服务器工作,而不是读取所有剩余的结果。 预处理语句清理遵循查询超时设置。 取消清理还有额外的等待时间预算,等于连接超时时长,或者当该超时为 0 时为 120 秒。
连接池 内置 mssql-python 池,包括重用前重置连接。 关于特定于身份验证的池隔离,请参见 身份隔离。
多线程处理 并发连接和查询,每个工作者拥有独立的连接和光标。 不要在不同线程之间共享光标。
元数据 API tables()、columns()、primaryKeys()、foreignKeys()、statistics()、rowIdColumns()、getTypeInfo()、rowVerColumns()、procedures()和getinfo()。 SQL_USER_NAME 报告数据库用户,而非连接字符串 UID。 能力值和基于数据包大小的限制可能与msodbcsql18不同:SQL_NEED_LONG_DATA_LEN报告"N",因为长输入不需要声明总长度。 使用返回的功能和限制。
编码与转换器 默认的宽字符编码、输出转换器、考虑排序规则的非 Unicode 参数以及采用平台客户端编码的窄字符结果。 自定义窄字符译码必须与该编码匹配;不匹配可能导致文本不正确或 bytes。 使用 conn.setdecoding(mssql_python.SQL_CHAR) 恢复默认的宽字符解码。 关于非 Unicode 参数替换,请参见 已知问题。

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

如果在你关闭一个 arrow_reader()、close() 时某个提取操作正在运行,则 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 设定 数值身份验证选择器(SQL_COPT_SS_AUTHENTICATION)和应用意图属性仍不支持。 实现了多子网故障转移和集成安全属性。 元数据标识符匹配(SQL_ATTR_METADATA_ID)也不支持。 在适用时使用 Authentication 和 ApplicationIntent connection-string 关键字。
fork() 连接后 在 Linux 上,父进程连接后 fork 出的进程在使用驱动时可能会卡住,即使使用新的连接。 启用池化后,父节点也会挂起。 (#566) 使用 spawn 启动方法,并在每个辅助角色中建立连接。
Linux 上的原生追踪 启用原生追踪后,Python 可以在进程退出时的驱动清理期间中止。 Linux上保持 MSSQL_TDS_TRACE 不设置。
自定义大参数绑定时的内存使用 绑定为固定宽度SQL_CHAR、SQL_WCHAR或SQL_BINARY的执行时数据值会被缓冲以进行转换。 混合缓冲参数和流式参数还可以缓冲较早的大值,同时等待较晚的缓冲值。 优先使用默认的可变长度绑定。 当内存占用很重要时,避免通过 setinputsizes() 使用大型固定宽度覆盖。
非 Unicode 字符替换 对于超出非 Unicode 参数目标代码页的字符,驱动程序可以使用 msodbcsql18 进行替换,而 ? 则使用最接近的字符。 当需要保留文本时,优先使用 Unicode SQL 类型和默认的 Python 字符串绑定。
原始 SQL 后的隔离变更 在原始文件之后 SET TRANSACTION ISOLATION LEVEL,将连接属性设置为驱动程序缓存级别,可以在不恢复服务器上该级别的情况下返回成功。 (#798) 避免将原始 SQL 和基于属性的隔离更改混用。 恢复级别时使用明确的 SET TRANSACTION ISOLATION LEVEL 标记。
内存不足故障 一些驱动程序分配失败会终止 Python 进程,而不是引发MemoryError异常。 (#484) 限制你发送和取回的值大小。
读取大型值的性能 varchar(max)和nvarchar(max)数据的分块读取速度可能比使用msodbcsql18时更慢。 结果取决于平台和工作负载。 (#473) 对你的工作负载进行基准测试。

此列表并不详尽。

报告问题

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

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

在 Windows 上,在启动 Python 前先在 PowerShell 中设置这些变量,以便收集本地驱动的诊断数据。 在选中 mssql-odbc 的情况下重现该问题。 在 Linux 上,由于 MSSQL_TDS_TRACE 中描述的进程退出失败,请保持 未设置。

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"
$env:MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB = "100"

MSSQL_TDS_TRACE 启用跟踪, MSSQL_TDS_TRACE_LEVEL 选择日志过滤器,并 MSSQL_TDS_TRACE_DIR 从原生 ODBC 驱动程序中选择每个进程跟踪文件的目录,而非标准错误输出。 MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB 设置每个文件的滚动阈值(默认为 100 MiB;接受 1-1024)。 它并不是总磁盘空间上限:单个文件可以超过阈值,旧文件不会被删除。 Rust配套包也会在当前目录下 mssql_python_logs 创建日志文件。 更改这些设置后重启 Python。

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