疑難排解 mssql-python 的安裝和連線問題

使用本文來診斷與 mssql-python 驅動程式相關的安裝、連線、容器及持續整合（CI）問題。

安裝問題

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

症狀：

error: Microsoft Visual C++ 14.0 or greater is required
ERROR: Failed building wheel for mssql-python

可能的原因與解決方法：

  • 沒有針對你平台的現成輪子

    • 確認你使用的是支援的 Python 版本（3.10 及以上版本）和平台。 關於相容性矩陣，請參見 支援生命週期 。
    • 安裝前先使用 pip install --upgrade pip 升級 pip。
    • 對於可重複的團隊環境，請使用可 重複部署 中的鎖定工作流程，或在 容器與本地開發 中使用容器模式，以減少本地機器漂移。

  • 虛擬環境未啟用

    • 先啟動你的虛擬環境。 安裝到 Python 系統時可能會造成權限錯誤或衝突。
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python
  • 缺少的 Linux 系統函式庫
    • 該驅動程式在 Linux 上需要多個系統函式庫。 請參閱 特定平台的相依性，以了解需安裝的套件。

驅動程式安裝衝突

症狀：

在同一環境中安裝 mssql-python 和 pyodbc 後，你可能會遇到匯入錯誤或非預期的行為。

Solution:

mssql-python 並且 pyodbc 可以共存。 如果遇到衝突，請建立乾淨的虛擬環境。

python -m venv .venv --clear
.venv\Scripts\activate
pip install mssql-python

連接問題

無法連接伺服器

症狀：

OperationalError: [08001] (0) Client unable to establish connection

可能的原因與解決方法：

  • 伺服器無法連線

    • 確認伺服器名稱和埠口是否正確。
    • 使用 ping <server> 或 telnet <server> 1433 檢查網路連線狀況。
    • 確保防火牆允許1433埠的外出連線。

  • SQL Server 未執行

    • 確認 SQL Server 服務已啟動。
    • 對於命名實例，請確認 SQL Server 瀏覽器服務正在執行。

  • Azure SQL firewall rules

    • 在 Azure 入口網站的 Azure SQL 防火牆規則中加入您的用戶端 IP 位址。
    • 若為 Azure SQL 受控執行個體，請確保您是從允許的網路進行連線。

測試基本 TCP 連線：

import socket

try:
    sock = socket.create_connection(("<server>.database.windows.net", 1433), timeout=5)
    print("TCP connection successful")
    sock.close()
except Exception as e:
    print(f"Cannot reach server: {e}")

登入失敗

症狀：

OperationalError: [28000] (18456) Login failed for user '<user_id>'.

可能的原因與解決方法：

  • 認證模式不匹配

    • 對於 Azure SQL Database、Azure SQL 受控執行個體 以及 Fabric 中的 SQL 資料庫，建議使用 Microsoft Entra 模式，例如 Authentication=ActiveDirectoryDefault。
    • 如果你有意使用 SQL 認證，請確認伺服器是否允許，且你使用的登入格式是否正確。

  • 錯誤的 SQL 認證憑證

    • 驗證使用者 ID 和密碼。
    • 對於 Azure SQL，請包含完整的使用者 ID： <user_id>@<server>。

  • 使用者不存在於資料庫中

    • 確認使用者是否擁有指定的資料庫存取權。
    • 檢查登入是否映射到資料庫使用者。

  • 認證未設定

    • 建議使用 Microsoft Entra 認證：Authentication=ActiveDirectoryDefault。
    • 如果你正在對應接受 SQL 驗證的本機 SQL Server 執行個體進行疑難排解，請確認 SQL Server 使用的是混合模式驗證。

連線超時

症狀：

OperationalError: [HYT00] (0) Timeout expired
OperationalError: [HYT01] (0) Connection timeout expired

可能的原因與解決方法：

  • 伺服器反應緩慢

    • 增加連線逾時時間。
    conn = mssql_python.connect(connection_string, timeout=60)

  • 網路等待時間

    • 檢查伺服器的網路路徑。
    • 可以考慮較短的網路路徑或虛擬私人網路（VPN）。

  • 伺服器負載過重

    • 盡量在非尖峰時段連線。
    • 請聯絡你的資料庫管理員。

SSL 憑證錯誤

症狀：

OperationalError: [08001] SSL Provider: The certificate chain was issued by an authority that is not trusted

解決方案：

偏好受信任的憑證或容器 與本地開發中的本地開發模式。 僅將 TrustServerCertificate=yes 用於針對你所控制的伺服器進行本機開發。

若使用自簽憑證進行開發與測試：

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"  # Don't use in production
)

Caution

TrustServerCertificate=yes 是僅限本地的備用方案。 不要把它帶進共享開發容器、CI 管線或生產部署。 欲了解更多資訊，請參閱 加密與憑證。

在生產環境中，安裝適當的憑證並使用：

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "HostnameInCertificate=<server>.domain.com;"
)

容器與持續整合問題

Linux 缺少的系統函式庫

症狀：

ImportError: libltdl.so.7: cannot open shared object file: No such file or directory
ImportError: libkrb5.so.3: cannot open shared object file

Solution:

安裝你發行版所需的系統套件：

散發 安裝指令
Ubuntu 或 Debian sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
Red Hat 或 Fedora sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

關於 Dockerfile 範例，請參見 容器與本地開發。

macOS 安裝後的 SSL 錯誤

症狀：

從 macOS 連線時，尤其是 Apple Silicon 上，會遇到 SSL 相關的錯誤。

Solution:

安裝 OpenSSL 搭配 Homebrew，並設定連結器旗標：

brew install openssl
export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

相關內容

  • Last updated on