使用 mssql-odbc 驅動程式（預覽版）

mssql-python 載入兩個原生 ODBC 提供者之一：

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server 預設
mssql-odbc 基於 Rust 的 ODBC 驅動程式 預覽, 同意加入

mssql-python-rs 0.4.0 套件包含 mssql-odbc 提供者。

Note

使用 msodbcsql18 處理正式作業工作負載。 在你選擇預覽 mssql-odbc 服務提供者之前，先先檢視其 已知的問題。

Availability

驅動程式隨 mssql-python-rs 套件提供，並以適用於 CPython 3.10 及更新版本的預先建置的 wheel 套件形式發佈：

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。

多子網故障轉移預設

Rust 提供者預設會對適用的傳輸控制協定（TCP）連線啟用 MultiSubnetFailover。 明確設定 MultiSubnetFailover=no，以要求依序進行連線嘗試。 若要更改部署整體預設，請在首次使用原生驅動程式之前，將 MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT 設為 true 或 false。 連接字串關鍵字會覆蓋此預設值。

數值 SQL_COPT_SS_MULTISUBNET_FAILOVER 屬性（1248）在連接前設定時也會覆蓋關鍵字。

驅動程式對於非 TCP 傳輸、資料庫鏡像、需要 SQL Server 瀏覽器探索的命名執行個體，或省略明確通訊協定與位址的本機 Windows 連線，不會啟用此預設值。 對非 TCP 傳輸、資料庫鏡像或 SQL Server Browser 探索明確啟用 MultiSubnetFailover 會引發連線錯誤。 欲了解更多資訊，請參閱 高可用性與故障轉移。

支援的功能

以下功能受已知問題限制。

Area Notes
連線生命週期 連線、close()with區塊、登入逾時、診斷，以及更改目前資料庫。 連接字串設定包括 ApplicationIntent、MultiSubnetFailover、IpAddressPreference、PacketSize、KeepAlive，以及 ConnectRetryCount / ConnectRetryInterval（閒置連線恢復能力）。 原生驅動程式也會協商伺服器輔助的網域名稱系統（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 參數，以及 pyformat 所執行的轉換 mssql-python。
ODBC 轉義語法 函數、日期/時間、外部聯結、全域唯一識別碼（GUID）、LIKE ... {escape ...}、間隔及 {encrypt ...} 逸出語法。
預存程序 用 Transact-SQL（T-SQL）或位置 {call ...} 語法透過 execute() 呼叫它們，讀取結果集，然後使用 nextset() 移至下一個結果集。
輸入參數 標量參數、SQL NULL、 setinputsizes()以及混合的常規/串流參數。
大型參數 大型文字、二進位、可擴充標記語言（XML）及使用者定義型別（UDT）參數支援執行時串流資料。
executemany() 使用 ODBC 參數陣列批次處理。 包含串流值的列會回退到逐列執行。
取得資料列 fetchone()、fetchmany()、fetchall()、迭代、fetchval()、類型轉換，以及大型文字/二進位串流。
擷取箭頭 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 sort-ID 定序。 自訂的窄字元解碼必須與客戶端的程式碼頁相符。 如需詳細資訊，請參閱已知問題。

Microsoft Entra ID整合驗證是使用Windows上登入的Windows帳號。 在 Linux 和 macOS 上，它使用 Kerberos 票證向租戶的 Active Directory 同盟服務（AD FS）端點驗證身分。 關於前置條件，請參見 Windows 整合認證。

關閉 arrow_reader() 會傳送 SQLCancel，以中斷正在進行的擷取。 此 close call 會等待取消清理完成。 欲了解更多資訊，請參閱 Apache Arrow 整合。

數據類型

驅動程式會以 Python 物件的形式回傳 str、json 和 vector 值，而 vector 則以 JavaScript 物件標記法（JSON）陣列表示。 它會將 bytes、geography 和 hierarchyid 等常見的通用語言執行階段（CLR）類型以 Python 物件的形式傳回。 欲了解更多資訊，請參閱 資料型別映射 與 已知問題。

已知問題

在從 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 以停用追蹤功能。

相關內容

  • 上次更新時間：