使用本文来诊断 mssql-python 驱动程序的安装、连接、容器和持续集成(CI)问题。
安装问题
pip 安装失败或从源代码生成
症状:
error: Microsoft Visual C++ 14.0 or greater is required
ERROR: Failed building wheel for mssql-python
可能的原因及解决方案:
没有适用于你的平台的预构建 wheel
虚拟环境未激活
- 先激活你的虚拟环境。 安装到系统中的 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 认证,请确认服务器是否允许,并且你使用的登录格式是否正确。
- 对于 Azure SQL 数据库、Azure SQL 托管实例 和 Fabric 中的 SQL 数据库,优先使用 Microsoft Entra 模式,例如
SQL 身份验证凭据不正确
- 验证用户ID和密码。
- 对于 Azure SQL,请包含完整的用户 ID:
<user_id>@<server>。
数据库中不存在用户
- 验证用户是否访问指定的数据库。
- 检查登录是否映射到数据库用户。
身份验证未配置
- 使用 Microsoft Entra 认证(推荐):
Authentication=ActiveDirectoryDefault。 - 如果你正在排查一个应当接受 SQL 身份验证的本地 SQL Server 实例,请确认 SQL Server 使用的是混合模式身份验证。
- 使用 Microsoft Entra 认证(推荐):
连接超时
症状:
OperationalError: [HYT00] (0) Timeout expired
OperationalError: [HYT01] (0) Connection timeout expired
可能的原因及解决方案:
服务器响应较慢
- 增大连接超时时间。
conn = mssql_python.connect(connection_string, timeout=60)网络延迟
- 检查通往服务器的网络路径。
- 考虑更短的网络路径或虚拟专用网络(VPN)。
服务器负载过重
- 尽量在非高峰时段连接。
- 请联系你的数据库管理员。
网络中断后结账缓慢
如果 connect() 调用在重复使用共用连接时停滞,请升级驱动并设置正向登录超时:
conn = mssql_python.connect(connection_string, timeout=30)
在默认提供者中 msodbcsql18 ,驱动程序在重用该连接前会检查一个池连接,而该检查中的每个请求都将该值用作超时。 如果你在 attrs_before 中设置 SQL_ATTR_LOGIN_TIMEOUT,驱动程序则会改为使用该值。 如果登录超时为零或未设置,驱动程序会使用15秒。
如果检查失败,驱动程序会在新连接上登录,该登录会获得自己的完整登录超时。 检查可以发送多个请求,因此 timeout=30 不会把整个通话时间限制在 30 秒。 Microsoft Entra ID 令牌获取不计入登录超时。 如果服务器或网络仍然不可用,请使用应用程序的重试策略处理连接错误。
选择启用的 mssql-odbc 提供程序在重置池连接时,对每个请求应用相同的超时。 当它取消请求时,会单独等待取消完成,因此总等待时间可能超过超时时间。 更多信息,请参阅 连接健康检查、 本地提供程序支持功能和 重试逻辑。
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 上缺失的系统库
症状:
当 libltdl 或 Kerberos 库缺失时, import mssql_python 成功了,但第一个 connect() 呼叫出现 OperationalError了:
OperationalError: Driver Error: Connection operation failed; DDBC Error: Failed to load the driver. Please read the documentation (https://github.com/microsoft/mssql-python#installation) to install the required dependencies.
在 Alpine Linux 上,当缺少 libstdc++ 时,import mssql_python 会失败:
ImportError: Error loading shared library libstdc++.so.6: No such file or directory
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 libstdc++ |
关于 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"