本文列出每個版本 mssql-python 驅動程式的變更，從最新版本開始。 每個章節都會涵蓋某個版本的新功能、行為變更以及錯誤修正。
關於 Microsoft 目前支援的版本，請參見支援生命週期。
MSSQL-Python 1.14.0
發行日期：2026年8月
Enhancements
參數偵測與綁定在原生程式碼中執行
參數型別偵測與繫結現在改為在單一原生管線中執行，而不是對每個參數分別進行 Python 呼叫。 此變更修正了一個重大的效能瓶頸，並在大量插入等較大型作業中帶來更高的端對端吞吐量提升。 不需要更改申請。
錯誤修正
傳遞給 connect() 的 timeout 引數設定的是查詢逾時，而不是驗證逾時
timeout 參數現在會設定 SQL_ATTR_LOGIN_TIMEOUT，並限制認證嘗試的範圍，這正是該參數名稱和說明文件所描述的。 在較早的版本中，它變成了每個陳述式的查詢逾時，因此 connect(timeout=30) 無法限制連線嘗試可執行多久，並且會在 30 秒後中止查詢。 每個陳述句的查詢逾時仍保留在屬性中 Connection.timeout 。
這很重要
如果您先前會將 timeout 傳遞給 connect() 以中止長時間執行的查詢，現在已不再有這種行為。 而是設定 Connection.timeout 。 如果你先前是依靠 bulkcopy() 來延長 connect(timeout=) 供其內部連線使用的連線逾時時間，情況也是一樣：請在建立游標之前設定 Connection.timeout。
更多資訊請參閱 連線逾時。
bulkcopy() 拒絕 timeout=0
0 的 timeout 會引發驗證錯誤，儘管在底層的 bulk copy API 中，0 表示不逾時。 此方法現在接受 0，並停用該作業的逾時設定。 負值、非整數值和布林值仍然被拒絕。
欲了解更多資訊，請參閱 「批量副本」。
清除作業已取代原本的 Arrow 擷取例外
當 Arrow 讀取器的擷取失敗時，驅動程式的清理路徑會觸發第二個錯誤，取代原本的錯誤，因此呼叫者看到的是清理失敗，而非擷取失敗的原因。 清理現在會先檢查游標狀態，並保留原始例外。
executemany() 十進位換算誤差包含參數值
executemany() 中的 十進位 轉換失敗透過鏈式例外回報了導致錯誤的值，這可能使客戶資料出現在應用程式日誌和監控系統中。 錯誤現在只回報列索引、欄位索引和值類型。
如需詳細資訊，請參閱錯誤處理。
批量複製被拒絕的箭頭檢視類型
bulkcopy_arrow() 無法處理可變長度的 Arrow View 陣列，因此 Polars 的 string_view 欄位必須先用 DataFrame.to_arrow() 進行轉換。 String View 值與 NULL 值現在會直接透過 Arrow C 資料介面傳遞。
欲了解更多資訊，請參見 極地積分。
Windows 擴充功能載入時會使用主機的 CPU 架構
在 Windows 上，驅動程式是根據主機 CPU 而非執行中的直譯器選擇原生擴充套件，因此 ARM64 主機上的 x64 Python 會透過備援路徑載入並寫入 stdout 通知。 載入器現在會根據解譯器判定架構，並將回退情況以警告形式回報。
MSSQL-Python 1.13.0
發行日期：2026年8月
Enhancements
ODBC 驅動程式二進位檔案僅隨 mssql-python-odbc 提供
版本 1.13.0 已從 mssql-python wheel 移除 libs/ 備援，並在 install_requires 中宣告 mssql-python-odbc==18.6.2.1。 該指令 pip install mssql-python 仍能產生正常運作的驅動程式。 若您使用 --no-deps 安裝，或是透過未鏡像 mssql-python-odbc 的私有索引安裝，請明確安裝 mssql-python-odbc。
如需詳細資訊，請參閱安裝。
從 Apache Arrow 來源大量複製
新cursor.bulkcopy_arrow()方法載入已是 Apache Arrow 格式的資料，且不會先將每一列轉換成 Python 物件。 將 Arrow 來源傳遞給 bulkcopy() 現在會引發 TypeError。
更多資訊請參閱 Apache Arrow 整合 與 批量複製。
token_provider Microsoft Entra 認證的參數
connect() 函式和 Connection 類別接受 token_provider 引數，因此你可以傳遞例如 DefaultAzureCredential 這樣的認證物件，而不必在連接字串中指定驗證模式。 此引數與 Authentication 關鍵字以及透過 attrs_before 傳遞的權杖互斥，且僅支援 Azure 商業雲端範圍。
如需詳細資訊，請參閱 Microsoft Entra 驗證。
身分感知連線集區
連線池現在依 Microsoft Entra 身份來區分連線。 在較早的版本中，連線池僅依連線字串來區分，因此可能會將以某位使用者身分驗證的連線交給另一位使用者提出的要求。 驅動程式僅在連線請求未通過池時取得令牌，並在令牌到期前 5 分鐘內刷新池連線。
如需詳細資訊，請參閱 連線共用。
錯誤修正
executemany() 當 NULL 出現在第一列之後時，插入零列
executemany()混合非 NULL 與 NULL 數值的呼叫會插入零列且當第一個 NULL 出現在第一列之後時，不會產生例外。 此行為影響了 tinyint、 smallint、 int 和 float 參數。 驅動程式現在會在陣列執行前，為每個固定寬度數值參數初始化 ODBC 指示器。
SQL_WVARCHAR輸出轉換器會轉換非字串欄位
註冊單一字串轉換器也會轉換 int、decimal 和 date 值，因為驅動程式會對任何沒有自己的轉換器的資料欄位回退使用 SQL_WVARCHAR 轉換器。 驅動程式現在只在欄位映射的 Python 型態為 str 或 bytes時使用該備援。
以整數 SQL 類型程式碼註冊的輸出轉換器從未執行
以整數 SQL 類型代碼註冊的轉換器（例如 SQL_DECIMAL）會被儲存起來，但從未被呼叫，因為驅動程式只根據 cursor.description 中的 Python 型別進行分派。 驅動程式現在會先根據整數代碼進行分派，接著根據 Python 型別進行分派，最後則使用 SQL_WVARCHAR 回退機制。
這很重要
如果你在早期版本中用整數 SQL 類型的程式碼註冊轉換器，這些轉換器會在升級時開始運作。 部署前請先檢視，因為先前未更改的欄位值現在會被轉換。
欲了解更多資訊，請參閱 自訂類型轉換器。
關閉 Arrow 讀取器並不會釋放伺服器端的游標
關閉 Arrow 讀取器後，伺服器端游標仍維持已配置狀態，且父 Cursor 處於不一致的狀態，因為 cursor.arrow_reader() 回傳了原始的 pyarrow.RecordBatchReader。 此時，方法會回傳一個包裝器，其 close() 方法會釋放伺服器端游標並重設游標狀態，而包裝器則作為上下文管理器運作。
欲了解更多資訊，請參閱 Apache Arrow 整合。
部分初始化的游標在 Cursor.__del__ 中引發了 AttributeError
初始化失敗的游標在垃圾回收期間以不可引發的例外形式引發了 AttributeError。
Cursor.__init__ 在設定 closed 和 hstmt 屬性之前就被 raised，而 __del__ 隨後嘗試讀取這些屬性。 初始化器現在會在任何程式碼能產生前先設定兩個屬性，並 __del__ 保護其日誌呼叫，確保在解譯器關機時保持安全。
MSSQL-Python 1.12.0
發行日期：2026年7月
Enhancements
獨立的 mssql-python-odbc 配套套件
ODBC 驅動程式二進位檔現在會另外以 mssql-python-odbc 的形式發布，作為固定為版本 18.6.2 的僅含資料配套套件。 你不需要更改任何程式碼，因為 pip install mssql-python 會一併安裝配套套件。 原生載入器會優先使用配套套件；若該套件不存在，則會退回使用 mssql-python wheel 內隨附的二進位檔。
如需詳細資訊，請參閱安裝。
錯誤修正
cursor.bulkcopy() 現在會使用父連線的連線逾時設定
bulkcopy() 現在會使用其父連線的連線逾時時間，而你可使用 connect(..., timeout=<seconds>) 進行設定。 先前，批量複製所開啟的個別連線使用硬式編碼的 15 秒連線逾時時間，且您無法從 Python 覆寫此設定。 使用 timeout=0 建立的父連線仍然採用 15 秒的預設值。
欲了解更多資訊，請參閱 「批量副本」。
cursor.bulkcopy() 支援 CLR 使用者自訂型別欄位
cursor.bulkcopy() 過去任何使用通用語言執行時（CLR）使用者定義型別的目的欄位都失敗 Protocol Error: Unsupported TDS type for bulk copy: 0xF0 ，包括內建的 地理、 幾何和 階層 型態。 驅動程式現在會將 CLR UDT 欄位映射到線上的 varbinary（max）， 並將你提供的位元組作為 UDT IBinarySerialize 的有效載荷串流。 修正版本會在 mssql_py_core 0.1.7 版本推出。
MSSQL-Python 1.11.0
發行日期：2026年7月
Enhancements
改進的上下文管理器語意
with connection: 現在會在區塊正常結束時提交交易，並在因例外而離開區塊時回滾交易。
欲了解更多資訊，請參閱 交易管理。
錯誤修正
- 修正了 ODBC 拆解路徑（
conn.close()和cursor.close()）中的 GIL 死結，以及在 SSH 隧道與程序內轉發器設定中，SQLDescribeParam的None-值參數所引發的 GIL 死結。 - 暫存表格和表格變數中的固定
BINARY參數與VARBINARYNULL 參數。 當自動型別解析失敗時，驅動程式會發出帶有明確cursor.setinputsizes()指引的 Python 警告。 - 修正了
import mssql_python在 Apple Silicon 上進行全新安裝時失敗的問題（1.8.0 版中的回歸問題）。 隨附的 ODBC dylib 相依項目現已針對arm64和x86_64兩種架構重寫。 - 修正了 Rust 核心中一個 GIL 死結，導致在使用
Authentication=ActiveDirectoryServicePrincipal. 進行驗證時，會凍結批量複製操作。
MSSQL-Python 1.10.0
發行日期：2026年6月
Enhancements
ActiveDirectoryServicePrincipal 對批量複製的支援
cursor.bulkcopy() 現在支援 Authentication=ActiveDirectoryServicePrincipal，所以你可以用服務主體憑證批量插入。
更多資訊請參閱批量複製與 Microsoft Entra 認證。
錯誤修正
- 修正了 Arrow 擷取路徑中的非 ASCII
VARCHAR與CHAR資料。 - 已修正執行大量載入作業時的連線逾時問題。
MSSQL-Python 1.9.0
發行日期：2026年6月
Enhancements
批量複製中的列物件
cursor.bulkcopy() 現在可以直接接受取指的 Row 物件，而不需要手動進行元組轉換。
欲了解更多資訊，請參閱 Bulk copy 與 Row 物件。
錯誤修正
- 固定輪圈包裝，因此
simdutf始終靜態連結。 - 修正了
DECIMAL中的大型executemany()插入內容。 - 修正了 NULL 參數的錯誤型別備援。
- 修正了例外在 pickle 與 unpickle 往返處理中的問題。
- 已修正
nextset()，使其可在各個結果集之間保留PRINT訊息。 - 修正了
Row的執行時資料備援路徑中對executemany()的處理。 - 修正了靜態分析工具對 fetch 方法的型別檢查。
MSSQL-Python 1.8.0
發行日期：2026年5月
Enhancements
ActiveDirectoryMSI 對批量複製的支援
cursor.bulkcopy() 現支援 Authentication=ActiveDirectoryMSI 系統指派與使用者指派的管理身份。
更多資訊請參閱批量複製與 Microsoft Entra 認證。
列字串鍵索引
例如，除了位置索引和屬性存取外，你現在還可以透過欄位名稱 row["col"]存取列值。
欲了解更多資訊，請參閱 列物件。
隨附的 ODBC 驅動程式升級
隨附的 Microsoft ODBC SQL Server 驅動程式更新至 18.6.2.1。
錯誤修正
- 修正基於代幣認證中延遲連接屬性壽命的問題。
- 修正了認證路徑中重複的 連接字串 解析。
- 序列輸入的固定
executemany()型別註解。
MSSQL-Python 1.7.1
發行日期：2026年5月
Enhancements
擴大輪圈覆蓋範圍與性能提升
此版本包括：
- 使用相容 RHEL 8 的輪組。
- 恢復了 macOS Python 3.10
universal2輪子。 - 透過
simdutf改善 UTF-16 處理。 - 已優化
execute()熱點路徑。
效能影響：批次執行吞吐量因方法熱路徑優化 execute() 而提升。
如需詳細資訊，請參閱安裝。
錯誤修正
- 修正了認證失敗，因此他們會提出
mssql_pythonDB-API 例外，而不是RuntimeError。 - 擴展 GIL 釋放，涵蓋阻塞 ODBC 執行、取指、交易及連線屬性呼叫。
- 已修正小數值變號時的
executemany()錯誤。 - 修正了跨平台不一致的 CP1252
VARCHAR解碼問題。 - 修正了
cursor.bulkcopy()和NVARCHAR(MAX)欄位中空字串導致的VARCHAR(MAX)失敗問題。
Note
1.7.0 版本因出版問題而被撤回。 使用版本 1.7.1 或更新版本。
MSSQL-Python 1.6.0
發行日期：2026年4月
Enhancements
基於語法分析器的連線字串清理
連線字串淨化現在使用解析器取代正則表達式，因此包含特殊字元的密碼欄位與括號值的連接字串也能正確解析。
如需詳細資訊，請參閱連接字串。
錯誤修正
- 已修正在 ODBC 連線與中斷連線的阻塞作業期間釋放 GIL 的問題。
- 修正了與
setinputsizes()和SQL_DECIMAL提示相關的SQL_NUMERIC當機問題。 - 修正了 ODBC 目錄方法的錯誤
fetchone()行為。 - 修正了使用
reset_cursor=False時發生的無效游標狀態錯誤。 - 修正了以映射為基礎的參數序列的
executemany()型別提示。 - 新增 `
setup_logging(log_file_path=...)` 的路徑遍歷防護機制。
MSSQL-Python 1.5.0
發行日期：2026年4月
新功能
Apache Arrow 擷取支援
三種新的游標方法透過 Arrow C 資料介面提供高效能的欄位資料檢索：
-
cursor.arrow()會傳回完整的pyarrow.Table。 -
cursor.arrow_batch()返回一個pyarrow.RecordBatch。 -
cursor.arrow_reader()會回傳用於串流的pyarrow.RecordBatchReader。
這些方法不會為每個值建立 Python 物件。 完整文件請參閱 Apache Arrow 整合。
sql_variant 類型支援
驅動程式現在會在擷取時偵測 sql_variant 欄位，解析其底層基本型別，並回傳型別正確的 Python 值，而非原始位元組。
Note
sql_variant 欄位採用串流擷取路徑，與固定型欄位相比，可能會對效能造成些微影響。
欲了解更多資訊，請參閱 資料型別映射。
原生 UUID 支援
新的 native_uuid 設定可控制 UNIQUEIDENTIFIER 欄位是以 uuid.UUID 物件（預設）傳回，還是以與 pyodbc 相容的大寫字串傳回。 在模組層級或針對個別連線進行設定。
更多資訊請參見 模組配置。
Row 類別 公開匯出
Row該類別現在會匯出到頂層用於型別註解。
欲了解更多資訊，請參閱 列物件。
錯誤修正
- 修正了在加括號的識別碼、字串常值和註解中將
?誤判為偵測目標的問題。 - 已修正
VARBINARY欄位的 NULL 參數繫結問題（不再引發隱含轉換錯誤）。 - 修正了
datetime.time到TIME(1)欄位中的TIME(7)值在往返轉換時會遺失微秒的問題。 - 已修正 Arrow 擷取路徑，使其能正確包含
TIME欄位的小數秒。 - 已修正使用 Microsoft Entra ID 驗證方法時的大量複製問題（過時的認證欄位不再導致驗證錯誤）。
- 在模組層級快取 Azure Identity 認證實例，以提升驗證效能。
MSSQL-Python 1.4.0
發行日期：2026年2月
新功能
批量複製支援
現在可透過 cursor.bulkcopy(). 提供高效能的大量資料載入服務。 此方法接受用於 batch_size、timeout、column_mappings、keep_identity、check_constraints、table_lock、keep_nulls、fire_triggers 和 use_internal_transaction 的選項。
欲了解更多資訊，請參閱 「批量副本」。
Improvements
- 針對大型結果集的效能優化。
- 減少批次作業中的記憶體使用。
- 大量複製失敗時的增強型錯誤訊息。
MSSQL-Python 1.3.0
發行日期：2026年1月
新功能
設定類別
透過新的 Settings 類別設定模組層級的行為，該類別包含用於 cursor.description 中資料行名稱的 lowercase 設定。
更多資訊請參見 模組配置。
Improvements
- 改善 Azure SQL 故障轉移期間的連線逾時處理。
- 提升與 Python 3.13 的相容性。
MSSQL-Python 1.2.0
發行日期：2026年1月
新功能
結構發現方法
新的游標方法探索資料庫元資料：、tables()、columns()、 statistics()primaryKeys()foreignKeys()procedures()getTypeInfo()。
更多資訊請參閱 結構發現。
Improvements
- 針對重複的結構描述查詢提供增強的中繼資料快取。
- 結果中計算欄位
columns()的處理更佳。
MSSQL-Python 1.1.0
發行日期：2025年12月
新功能
客製化輸出轉換器
註冊自訂函式，以便在擷取時轉換欄位值，函式為 add_output_converter()、get_output_converter()、remove_output_converter() 和 clear_output_converters()。
欲了解更多資訊，請參閱 自訂類型轉換器。
Improvements
- 型別轉換失敗時的錯誤訊息會更好。
- 支援返回
None的轉換函數。
MSSQL-Python 1.0.0
發行日期：2025年11月
最初的通用授權釋出
mssql-python 的首個正式發行版本，Microsoft SQL Server 的原生 Python 驅動程式。
欲了解更多資訊，請參閱 mssql-python 驅動程式。
核心功能
- DDBC 架構：直接進行資料庫連接，無需安裝 ODBC 驅動程式。
- DB-API 2.0 合規性：標準Python資料庫介面。
- 連線集區：內建連線集區管理功能。
- Microsoft Entra 認證：完全支援 Azure 身份認證。
- TLS 加密：具備憑證驗證的安全連線。
連接功能
- 21 個連接字串關鍵字。
- 9 種認證模式（SQL、Windows 及 7 種 Microsoft Entra ID 方法）。
- 自動提交控制。
- 執行方法：
execute()、、executemany()batch_execute()和 。 - 連接屬性透過
set_attr()和getinfo()。 - 情境管理員支援。
游標功能
- 標準擷取方法：
fetchone()、fetchmany()、fetchall()。 - 擴展方法：
fetchval()，skip()。 - 執行方法：
execute()和executemany()。 - 資料列物件可透過屬性和索引存取。
- 使用
nextset()進行多重結果集導覽。
資料類型支援
- 所有 SQL Server 原生類型。
- Python↔SQL 型別對應。
- 用於明確指定型別的 SQL 型別常數（例如
mssql_python.SQL_DECIMAL）。 - Python 中的 NULL 處理
None。
交易支援
- 手動提交與回滾。
- 自動提交模式。
- 隔離層控制。
- 死鎖偵測與處理。
認證模式
| Mode | 描述 |
|---|---|
| SQL Server 認證 | 使用者名稱與密碼 |
| Windows 驗證 | Trusted_Connection |
| ActiveDirectoryDefault | DefaultAzureCredential |
| ActiveDirectoryInteractive | 基於瀏覽器的登入 |
| ActiveDirectoryDeviceCode | 裝置代碼流程 |
| ActiveDirectoryPassword | Microsoft Entra 使用者名稱與密碼（已棄用;使用ROPC系統） |
| ActiveDirectoryMSI | 受管理的識別 |
| ActiveDirectoryServicePrincipal | 服務主體 |
| Active Directory 整合式 | Windows Kerberos |
Upgrade
來自 pyodbc
如需詳細遷移指引，請參見「從 pyodbc 遷移」。
主要差異：
- 支援
?（qmark）與%(name)s（pyformat）兩種參數樣式。 你現有?的查詢無需更改即可運作。 - 沒有
callproc()方法。 改用EXECUTE語句。 - 內建連線池。
- 沒有外部 ODBC 驅動程式依賴。
來自 pymssql
如需詳細遷移指引，請參閱從 pymssql 遷移。
主要差異：
- 將
%s和%d參數標記取代為?或%(name)s。 - 請使用連線字串，而非位置引數。
- 沒有 FreeTDS 依賴。
- 每個連線有多個並行游標。
- 具有屬性存取權的列物件替換
as_dict=True。
mssql-python 各版本之間
升級驅動程式以獲得新功能和修正。
pip install --upgrade mssql-python
升級生產系統前，請先查看發布說明是否有任何破壞性的變更。
藍圖
關於即將推出的功能與開發路線圖，請參閱 GitHub 倉庫。