疑難排解 mssql-python

請參考這篇文章，為駕駛人尋找故障排除指引 mssql-python 。先從符合你問題的症狀或錯誤訊息開始。

安裝問題

PIP 安裝失敗或從原始碼建置

關於不支援的 Python 版本、缺少的輪子、非活躍的虛擬環境以及缺少的 Linux 函式庫，請參見「故障排除安裝與連線問題」。

驅動程式安裝衝突

關於匯入錯誤或同時安裝時mssql-pythonpyodbc的異常行為，請參見「安裝與連線問題故障排除」。

連接問題

無法連接伺服器

關於 SQLSTATE08001、無法到達的伺服器、停止服務以及 Azure SQL 防火牆規則，請參見「故障排除安裝與連線問題」。

關於 SQLSTATE 28000、認證模式不符、憑證無效及缺少資料庫使用者，請參見「故障排除安裝與連線問題」。

連線超時

關於 SQLSTATE HYT00 或 HYT01，網路延遲、伺服器緩慢及連線逾時設定，請參見「故障排除安裝與連線問題」。

SSL 憑證錯誤

關於不受信任的憑證錯誤及安全本地開發選項，請參見「故障排除安裝與連線問題」。

查詢執行問題

找不到表格或物件

關於 SQLSTATE 42S02、資料庫上下文、架構資格及資料表存在性檢查，請參見故障排除查詢、資料與操作問題。

語法錯誤

關於 SQLSTATE 42000、SQL 語法、字串逃逸及參數化查詢，請參見「疑難排解查詢、資料與操作問題」。

參數錯誤

關於 SQLSTATE 07001、佔位符計數及支援的參數樣式，請參見故障排除查詢、資料與操作問題。

資料型別問題

日期時間轉換錯誤

關於 SQLSTATE 22007 與 datetime 參數轉換，請參見「疑難排解查詢、資料及操作問題」。

十進位精度問題

關於截斷或四捨五入的十進位值，請參見故障排除查詢、資料及操作問題。

Unicode 編碼問題

關於混亂的特殊字元與 Unicode 欄位類型，請參見故障排除查詢、資料與操作問題。

效能問題

查詢執行緩慢

關於索引、大型結果集及連線池，請參見「疑難排解查詢、資料及操作問題」。

大型結果時的記憶體問題

關於串流與分頁大型結果集，請參見「故障排除查詢、資料及操作問題」。

交易問題

自動提交模式下的暫存資料表作用範圍

如需了解在復原後會消失的暫存資料表，以及需要自動提交的 DDL 陳述式，請參閱「疑難排解查詢、資料和作業問題」。

交易未承諾

關於連線關閉後不持續的資料變更，請參見「疑難排解查詢、資料與操作問題」。

死結錯誤

關於 SQLSTATE 40001、重試指引及重複死結分析，請參見「故障排除查詢、資料與操作問題」。

散裝載重問題

批量複製期間的限制違規

關於主鍵、唯一鍵、檢查金鑰或外鍵在批量複製過程中的違規，請參見故障排除查詢、資料及操作問題。

欄位映射錯誤

關於批量複製欄位數量與欄位順序不符，請參見故障排除查詢、資料及操作問題。

批量複製時的類型不匹配

若在批量複製後出現截斷、四捨五入或錯誤的值，請參見「故障排除查詢、資料與操作問題」。

NumPy 類型繫結失敗

關於 NumPy 整數或浮點數型態的參數綁定失敗，請參見「疑難排解查詢、資料與操作問題」。

使用暫存資料表的批量複製

如需了解當您將 bulkcopy() 與工作階段暫存資料表搭配使用時發生的 Invalid object name 錯誤，請參閱「針對查詢、資料及作業問題進行疑難排解」。

容器與持續整合問題

Linux 缺少的系統函式庫

關於 Linux 環境中缺少 libltdl 或 Kerberos 函式庫，請參見「故障排除安裝與連線問題」。

macOS 安裝後的 SSL 錯誤

關於 macOS 上與 SSL 相關的錯誤，包括 Apple Silicon，請參見「安裝與連線問題故障排除」。

診斷工具

啟用驅動程式記錄

使用 mssql_python.setup_logging() 啟用 DEBUG 記錄。驅動程式會記錄 SQL 語句、參數、內部 ODBC 操作及連線狀態變更。

import mssql_python

# Enable logging to file (default)
mssql_python.setup_logging()

# Output to stdout (useful for CI/CD and containers)
mssql_python.setup_logging(output="stdout")

# Output to both file and stdout
mssql_python.setup_logging(output="both")

# Custom log file path (must use .txt, .log, or .csv extension)
mssql_python.setup_logging(log_file_path="/var/log/myapp/mssql.log")

日誌檔案採用 CSV 格式，並在達到 512 MB 時自動輪替，保留五個備份檔。驅動程式會在日誌輸出中淨化密碼和存取權杖等敏感資料。

要將應用程式條目加入驅動程式日誌，請使用 driver_logger：

import mssql_python
from mssql_python.logging import driver_logger

mssql_python.setup_logging()

driver_logger.debug("[App] Starting data processing")
driver_logger.error("[App] Failed to process record")

Caution

記錄日誌會產生效能負擔。僅在進行問題疑難排解時啟用。不要預設在生產環境啟用它。

取得駕駛資訊

從活躍連線中取得驅動程式版本及伺服器資料：

import mssql_python

conn = mssql_python.connect(connection_string)

print(f"Version: {mssql_python.__version__}")
print(f"Server name: {conn.getinfo(mssql_python.SQL_SERVER_NAME)}")
print(f"Database name: {conn.getinfo(mssql_python.SQL_DATABASE_NAME)}")

檢查連線狀態

執行一個輕量級查詢來測試連線是否仍然開啟：

import mssql_python

try:
    cursor = conn.cursor()
    cursor.execute("SELECT 1")
    print("Connection is open")
except mssql_python.Error:
    print("Connection is closed or broken")

快速參考：常見錯誤

錯誤	SQLSTATE	常見原因	故障排除
用戶端無法建立連線	`08001`	無法連線到伺服器	無法連接伺服器
登入失敗	`28000`	不正確的認證	登入失敗
逾時期限已到	`HYT00` 或 `HYT01`	慢速網路	連接逾時
無效的物件名稱。	`42S02`	錯誤的表格或結構	找不到表格或物件
語法錯誤	`42000`	SQL 錯誤	語法錯誤
約束違反	`23000`	外鍵或主鍵違規	批量複製期間的限制違規
死結	`40001`	鎖定爭用	死結錯誤

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-21