使用 mssql-odbc 驅動程式(預覽版)

mssql-python 載入兩種原生 ODBC 提供者之一:

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

本文介紹隨 mssql-python-rs 0.5.0 附帶的 mssql-odbc 供應商,以及與 msodbcsql18 之間的差異。

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=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 Notes
連線生命週期 連線、close()with區塊、登入逾時、診斷,以及更改目前資料庫。 連接字串設定包括 ApplicationIntent、MultiSubnetFailover、IpAddressPreference、PacketSize、KeepAlive,以及 ConnectRetryCount / ConnectRetryInterval(閒置連線恢復能力)。
網路韌性 符合條件的 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 參數,以及 pyformat 所執行的轉換 mssql-python。
ODBC 轉義語法 函數、日期/時間、外部聯結、全域唯一識別碼(GUID)、LIKE ... {escape ...}、間隔及 {encrypt ...} 逸出語法。
預存程序 用 Transact-SQL(T-SQL)或位置 {call ...} 語法透過 execute() 呼叫它們,讀取結果集,然後使用 nextset() 移至下一個結果集。
輸入參數 標量參數、SQL NULL、 setinputsizes()以及混合的常規/串流參數。
大型參數 大型文字與二進位參數會透過一般綁定路徑串流到伺服器。 透過 setinputsizes() 的明確 SQL_SS_XML 和 SQL_SS_UDT 繫結,在 Python 選擇資料於執行時傳送時也會串流:針對 bytes,宣告的大小必須超過 4000;針對 bytearray 或 str,則必須超過 8000。 使用者自訂型別(UDT)綁定需要伺服器描述參數的型別。 有些自訂或混合綁定仍會緩衝。 如需詳細資訊,請參閱已知問題。
executemany() 使用 ODBC 參數陣列批次處理。 包含串流值的列會回退到逐列執行。
取得資料列 fetchone()、 fetchmany()、 fetchall()、迭代、 fetchval()、型別轉換,以及大型文字/二進位串流。
擷取箭頭 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 讓這些請求不受限制。 此逾時與登入及查詢逾時分開,並非完整的連線池簽出截止時間。 取消清理可能會增加呼叫耗時。
游標清理 關閉游標會在需要時取消待處理的伺服器工作,而不是讀取所有剩餘結果。 Prepared-statement 清理會尊重查詢逾時。 取消清理會有額外的等待時間,等於連線逾時時間;若該逾時為 0,則為 120 秒。
連線池化 內建的 mssql-python 池,包括在重用前重設連線。 關於驗證專用的集區隔離,請參見 身分隔離。
多線程 每個工作者使用各自獨立的連線與游標進行並行連線與查詢。 不要在不同執行緒之間共用游標。
中繼資料 API tables(),columns(),primaryKeys(),foreignKeys(),getinfo(),statistics(),rowIdColumns(),rowVerColumns(),procedures(),和 getTypeInfo()。 SQL_USER_NAME 報告資料庫使用者,而非 connection-string 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()會取消擷取,並在擷取停止後返回。 關閉先前查詢的讀取器不會影響同游標上的後續查詢。 欲了解更多資訊,請參閱 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 設定 數值驗證選擇器(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 以停用追蹤功能。