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 批次和錯誤訊息:
- Rust 驅動程式問題: https://github.com/microsoft/mssql-rs/issues
-
mssql-python問題: https://github.com/microsoft/mssql-python/issues
在 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 以停用追蹤功能。