每個 mssql-python 驅動程式版本都會引入新功能、效能提升及錯誤修正。 以下章節將詳細介紹每個版本。
MSSQL-Python 1.11.0
發行日期：2026年7月
Enhancements
改進的上下文管理器語意
with connection: 現在會在正常結束時正確提交事務，並在發生例外時回滾，使其更符合 Python 風格，且行為更可預測。
import mssql_python
# On clean exit, transaction commits
with mssql_python.connect(connection_string) as conn:
cursor = conn.cursor()
cursor.execute("INSERT INTO MyTable (Name) VALUES ('Alice')")
# Automatically committed on exit
# On exception, transaction rolls back
try:
with mssql_python.connect(connection_string) as conn:
cursor = conn.cursor()
cursor.execute("INSERT INTO MyTable (Name) VALUES ('Bob')")
raise ValueError("Oops!")
except ValueError:
pass
# Changes rolled back on exit
錯誤修正
- 修正了 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，允許使用服務主體憑證進行批量插入。
import mssql_python
conn = mssql_python.connect(
"Server=<server>.database.windows.net;"
"Database=<database>;"
"Authentication=ActiveDirectoryServicePrincipal;"
"UID=<application-client-id>;"
"PWD=<client-secret>;"
"Encrypt=yes"
)
cursor = conn.cursor()
cursor.execute("CREATE TABLE ##SpDemo (ID INT, Value FLOAT)")
conn.commit()
result = cursor.bulkcopy("##SpDemo", [(1, 1.5), (2, 2.5)])
print(f"Copied {result['rows_copied']} rows")
錯誤修正
- 修正了 Arrow 擷取路徑中的非 ASCII
VARCHAR與CHAR資料。 - 已修正執行大量載入作業時的連線逾時問題。
MSSQL-Python 1.9.0
發行日期：2026年6月
Enhancements
批量複製中的列物件
cursor.bulkcopy() 現在可以直接接受取指的 Row 物件，而不需要手動進行元組轉換。
import mssql_python
conn = mssql_python.connect(connection_string)
cursor = conn.cursor()
# Fetch rows from source table
cursor.execute("SELECT ProductID, Name, ListPrice FROM Production.Product")
rows = cursor.fetchall()
# Pass fetched Row objects directly to bulkcopy
cursor.execute("CREATE TABLE ##RowBulkDemo (ProductID INT, Name NVARCHAR(50), ListPrice MONEY)")
conn.commit()
result = cursor.bulkcopy("##RowBulkDemo", rows)
print(f"Copied {result['rows_copied']} rows")
錯誤修正
- 固定輪圈包裝，因此
simdutf始終靜態連結。 - 修正了
executemany()中的大型DECIMAL插入內容。 - 修正了 NULL 參數的錯誤型別備援。
- 修正了例外在 pickle 與 unpickle 往返處理中的問題。
- 已修正
nextset()，使其可在各個結果集之間保留PRINT訊息。 - 修正了
executemany()的執行時資料備援路徑中對Row的處理。 - 修正了靜態分析工具對 fetch 方法的型別檢查。
MSSQL-Python 1.8.0
發行日期：2026年5月
Enhancements
ActiveDirectoryMSI 對批量複製的支援
cursor.bulkcopy() 現支援 Authentication=ActiveDirectoryMSI 系統指派與使用者指派的管理身份。
import mssql_python
# System-assigned managed identity
conn = mssql_python.connect(
"Server=<server>.database.windows.net;"
"Database=<database>;"
"Authentication=ActiveDirectoryMSI;"
"Encrypt=yes"
)
cursor = conn.cursor()
cursor.execute("CREATE TABLE ##MsiDemo (ID INT, Name NVARCHAR(50))")
conn.commit()
result = cursor.bulkcopy("##MsiDemo", [(1, "Alice"), (2, "Bob")])
print(f"Copied {result['rows_copied']} rows")
列字串鍵索引
例如，除了位置索引和屬性存取外，你現在還可以透過欄位名稱 row["col"]存取列值。
import mssql_python
conn = mssql_python.connect(connection_string)
cursor = conn.cursor()
cursor.execute("SELECT ProductID, Name, ListPrice FROM Production.Product WHERE ProductID = 1")
row = cursor.fetchone()
# Access by column name (new in 1.8.0)
print(row["ProductID"]) # Access by key
print(row["Name"])
# Still supports positional indexing
print(row[0]) # Positional access
# And attribute access
print(row.Name) # Attribute access
隨附的 ODBC 驅動程式升級
隨附的 Microsoft ODBC SQL Server 驅動程式更新至 18.6.2.1。
錯誤修正
- 修正基於代幣認證中延遲連接屬性壽命的問題。
- 修正了認證路徑中重複的 連接字串 解析。
- 序列輸入的固定
executemany()型別註解。
MSSQL-Python 1.7.1
發行日期：2026年5月
Enhancements
擴大輪圈覆蓋範圍與性能提升
此版本新增了相容於 RHEL 8 的 wheel 套件，恢復了 macOS Python 3.10 的 universal2 wheel 套件，並透過 simdutf 改善了 UTF-16 的處理，同時最佳化了 execute() 熱路徑。
效能影響：由於熱路徑優化 execute() ，批次執行吞吐量在典型工作負載上提升了約 15%。
錯誤修正
- 已修正登入失敗問題，使其引發
mssql_pythonDB-API 例外，而非RuntimeError。 - 擴展 GIL 釋放，涵蓋阻塞 ODBC 執行、取指、交易及連線屬性呼叫。
- 已修正小數值變號時的
executemany()錯誤。 - 修正了跨平台不一致的 CP1252
VARCHAR解碼問題。 - 修正了
NVARCHAR(MAX)和VARCHAR(MAX)欄位中空字串導致的cursor.bulkcopy()失敗問題。
Note
1.7.0 版本因出版問題而被撤回。 使用版本 1.7.1 或更新版本。
MSSQL-Python 1.6.0
發行日期：2026年4月
Enhancements
基於語法分析器的連線字串清理
此強化確保密碼欄位及括號值中特殊字元的正確解析。
import mssql_python
# Complex passwords with special characters now parse correctly
conn = mssql_python.connect(
"Server=<server>.database.windows.net;"
"Database=<database>;"
"UID=user@contoso;"
"PWD={p@ssw0rd;with{braces}};" # Braced values now handled correctly
"Encrypt=yes"
)
連線字串清理已從以正則表達式為基礎的邏輯，改為以剖析器為基礎的處理方式，以正確處理 ODBC 連線字串語法。
錯誤修正
- 已修正在 ODBC 連線與中斷連線的阻塞作業期間釋放 GIL 的問題。
- 修正了與
SQL_DECIMAL和SQL_NUMERIC提示相關的setinputsizes()當機問題。 - 修正了 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 相容的大寫字串傳回。 在模組層級或依各個連線進行設定：
# Module-level default
settings = mssql_python.get_settings()
settings.native_uuid = True # default
# Per-connection override
conn = mssql_python.connect(connection_string, native_uuid=False)
更多資訊請參見 模組配置。
Row 類別 公開匯出
Row該類別現在在頂層匯出用於型別註解：
from mssql_python import Row
錯誤修正
- 修正了在加括號的識別碼、字串常值和註解中將
?誤判為偵測目標的問題。 - 已修正
VARBINARY欄位的 NULL 參數繫結問題（不再引發隱含轉換錯誤）。 - 修正了
TIME(1)到TIME(7)欄位中的datetime.time值在往返轉換時會遺失微秒的問題。 - 已修正 Arrow 擷取路徑，使其能正確包含
TIME欄位的小數秒。 - 已修正使用 Microsoft Entra ID 驗證方法時的大量複製問題（過時的認證欄位不再導致驗證錯誤）。
- 在模組層級快取 Azure Identity 認證實例，以提升驗證效能。
MSSQL-Python 1.4.0
上映日期：2025年3月
新功能
批量複製支援
高效能大量資料載入現已可透過 cursor.bulkcopy() 使用：
import mssql_python
conn = mssql_python.connect(connection_string)
cursor = conn.cursor()
cursor.execute("CREATE TABLE ##BulkDemo (ID INT, Name NVARCHAR(50), Price DECIMAL(10,2))")
conn.commit()
data = [
(1, "Item 1", 10.50),
(2, "Item 2", 20.75),
# ... potentially millions of rows
]
result = cursor.bulkcopy("##BulkDemo", data)
print(f"Copied {result['rows_copied']} rows")
此方法接受用於 batch_size、timeout、column_mappings、keep_identity、check_constraints、table_lock、keep_nulls、fire_triggers 和 use_internal_transaction 的選項。
完整文件請參閱 「批量副本 」。
Improvements
- 針對大型結果集的效能優化。
- 減少批次作業中的記憶體使用。
- 大量複製失敗時的增強型錯誤訊息。
MSSQL-Python 1.3.0
發行日期：2025年1月
新功能
設定類別
透過新 Settings 類別配置模組範圍的行為：
import mssql_python
settings = mssql_python.get_settings()
settings.lowercase = True # Lowercase column names in cursor.description
詳情請參見 模組配置 。
Improvements
- 改善 Azure SQL 故障轉移期間的連線逾時處理。
- 提升與 Python 3.13 的相容性。
MSSQL-Python 1.2.0
發行日期：2024年11月
新功能
結構發現方法
用於資料庫元資料探索的新游標方法：
cursor = conn.cursor()
# List all tables
cursor.tables(schema="dbo")
# Get column information
cursor.columns(table="Product", schema="Production")
# Get primary keys
cursor.primaryKeys(table="Product", schema="Production")
# Get foreign key relationships
cursor.foreignKeys(table="SalesOrderDetail", schema="Sales")
# Get stored procedures
cursor.procedures(schema="dbo")
# Get index statistics
cursor.statistics(table="Product", schema="Production")
# Get type information
cursor.getTypeInfo()
完整文件請參閱 結構發現 。
Improvements
- 針對重複的結構描述查詢提供增強的中繼資料快取。
- 結果中計算欄位
columns()的處理更佳。
MSSQL-Python 1.1.0
上映日期：2024年9月
新功能
客製化輸出轉換器
註冊自訂函式，以便在擷取時轉換欄位值：
import mssql_python
from decimal import Decimal
conn = mssql_python.connect(connection_string)
# Convert decimals to float (converter receives Decimal)
def decimal_to_float(value):
if value is None:
return None
return float(value) # value is already a Decimal object
conn.add_output_converter(mssql_python.SQL_DECIMAL, decimal_to_float)
# Custom money formatting
def format_money(value):
if value is None:
return "$0.00"
return f"${float(value):,.2f}" # value is already a Decimal object
conn.add_output_converter(mssql_python.SQL_DECIMAL, format_money)
管理方法：
add_output_converter(sql_type, converter_func)get_output_converter(sql_type)remove_output_converter(sql_type)clear_output_converters()
完整文件請參閱 「自訂類型轉換器」。
Improvements
- 型別轉換失敗時的錯誤訊息會更好。
- 支援返回
None的轉換函數。
MSSQL-Python 1.0.0
發行日期：2024年7月
最初的通用授權釋出
mssql-python 的首個正式發行版本，Microsoft SQL Server 的原生 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 倉庫。