排查 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

可能的原因和解决方案：

  • 服务器无法访问

    • 请确认服务器名称和端口是否正确。
    • 使用telnet <server> 1433或ping <server>检查网络连接。
    • 确保防火墙允许端口1433进行出站连接。

  • SQL Server 无法运行

    • 确认 SQL Server 服务已启动。
    • 对于命名实例，请确认 SQL Server 浏览器服务正在运行。

  • Azure SQL firewall rules

    • 在Azure门户中添加您的客户端IP地址到Azure SQL防火墙规则中。
    • 对于 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 数据库、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;"
)

容器和CI问题

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
红帽或 Fedora sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

关于 Dockerfile 示例，请参见 容器与本地开发。

macOS 安装后出现的 SSL 错误

症状：

从 macOS 连接时，尤其是在使用 Apple 芯片的 Mac 上，你会遇到与 SSL 相关的错误。

Solution:

用Homebrew安装OpenSSL，并设置链接器标志：

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

相关内容

  • Last updated on