请参阅本文，查找有关 mssql-python 驱动程序的故障排除指南。 从符合你问题的症状或错误信息开始。
安装问题
pip 安装失败或从源代码生成
对于不支持的 Python 版本、缺失的轮子、非活跃的虚拟环境以及缺失的 Linux 库，请参见“排查安装和连接问题”。
冲突的驱动程序安装
如果同时安装了 pyodbc 和 mssql-python 时出现导入错误或发生异常行为，请参见排查安装和连接问题。
连接问题
无法连接到服务器
关于SQLSTATE08001、不可访问服务器、停止服务以及Azure SQL防火墙规则，请参见“排查安装和连接问题”。
登录失败
关于SQLSTATE 28000、认证模式不匹配、凭证无效和数据库用户缺失，请参见 “排查安装和连接问题”。
连接超时
关于SQLSTATE HYT00 或 HYT01网络延迟、服务器慢速和连接超时设置，请参见 “排查安装和连接问题”。
SSL 证书错误
关于不可信证书错误和安全的本地开发选项，请参见 “排查安装和连接问题”。
查询执行问题
未找到表格或对象
关于 SQLSTATE 42S02、数据库上下文、模式资格和表存在性检查，请参见 故障排除查询、数据和操作问题。
语法错误
关于 SQLSTATE42000、SQL 语法、字符串逃逸和参数化查询，请参见“排查查询、数据和操作问题”。
参数误差
关于 SQLSTATE 07001、占位符计数和支持的参数样式，请参见 “排查查询、数据和操作问题”。
数据类型问题
日期时间转换错误
关于 SQLSTATE 22007 和 datetime 参数转换，请参见 “排查查询、数据和操作问题”。
十进制精度问题
关于截断或四舍五入的十进制值，请参见 “故障排除查询、数据和操作问题”。
Unicode 编码问题
关于杂乱的特殊字符和 Unicode 列类型，请参见 “故障排除查询、数据和操作问题”。
性能问题
查询执行缓慢
关于索引、大型结果集和连接池，请参见 “故障排除查询、数据和操作问题”。
大型结果集的内存问题
有关如何流式处理和分页显示大型结果集，请参见 排查查询、数据和操作问题。
交易问题
自动提交模式下的临时表作用域
对于回滚后会消失的临时表以及需要自动提交的 DDL 语句，请参见 排查查询、数据和操作问题。
事务未提交
对于连接关闭后不持续的数据变更，请参见 “排查查询、数据和操作问题”。
死锁错误
关于 SQLSTATE40001、重试指南和定期死锁分析，请参见“排查查询、数据和操作问题”。
批量加载问题
批量复制期间的约束违规
有关批量复制期间发生的主键、唯一约束、检查约束或外键约束违反问题，请参阅 排查查询、数据和操作问题。
列映射错误
有关批量复制中的列数和列顺序不匹配问题，请参阅 查询、数据和操作问题疑难解答。
批量复制时出现类型不匹配
对于批量复制后截断、四舍五入或错误的值，请参见 “故障排除查询、数据和操作问题”。
NumPy 类型绑定失败
关于 NumPy 整数或浮点类型参数绑定失败，请参见 “排查查询、数据和操作问题”。
使用临时表的批量复制
有关使用 会话临时表时出现的 Invalid object name 错误，请参阅 bulkcopy()。
容器和CI问题
Linux 上缺失的系统库
有关 Linux 环境中缺少 libltdl 或 Kerberos 库的问题，请参见 排查安装和连接问题。
macOS 安装后出现的 SSL 错误
关于macOS上的SSL相关错误，包括苹果芯片，请参见 “安装和连接问题的故障排除”。
诊断工具
启用驱动程序日志
使用 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")
注意
日志记录会带来性能开销。 只有在排查问题时才启用。 不要在生产环境中默认启用它。
获取驾驶员信息
从活跃连接中获取驱动版本和服务器详细信息：
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 | 常见原因 | Troubleshooting |
|---|---|---|---|
| 客户端无法建立连接 | 08001 |
服务器无法访问 | 无法连接到服务器 |
| 登录失败 | 28000 |
凭据不正确 | 登录失败 |
| 已超时 |
HYT00 或 HYT01 |
网络速度缓慢 | 连接超时 |
| 对象名称无效 | 42S02 |
表格或模式错误 | 未找到表格或对象 |
| 语法错误 | 42000 |
SQL 错误 | 语法错误 |
| 违反约束 | 23000 |
外键或主键违规 | 批量复制期间违反约束 |
| 死锁 | 40001 |
锁争用 | 死锁错误 |