Linux环境sqlalchemy连接MSSQL首次触发IndexError: tuple index out of range

问题根因 #

错误的核心原因是FreeTDS驱动的连接参数写法错误：你错误地将PORT、TDS_VERSION这些独立的连接参数直接拼到了driver参数的值里，导致SQLAlchemy无法正常完成数据库连接初始化，无法获取到MSSQL服务端版本信息，最终访问空元组下标触发IndexError。

修复方案 #

保留sqlalchemy.create_engine的使用方式，按如下规则修改Linux端的连接代码即可：

• 单独配置DRIVER变量为纯驱动名，不要拼接其他参数
• 端口、TDS版本等参数单独作为URL的查询参数传递，或者直接拼到DB_SERVER字段后

修正后的Linux端代码 #

import sqlalchemy
DRIVER="FreeTDS"
# 写法1：端口直接写在DB_SERVER后，参数单独拼接
engine = sqlalchemy.create_engine(f"mssql+pyodbc://{USER}:{PASS}@{DB_SERVER}:1433/{DB_NAME}?driver={DRIVER}&TDS_Version=8.0")

# 写法2：所有参数都放在查询串里也可正常运行
# engine = sqlalchemy.create_engine(f"mssql+pyodbc://{USER}:{PASS}@{DB_SERVER}/{DB_NAME}?driver={DRIVER}&PORT=1433&TDS_Version=8.0")

验证说明 #

• 上述写法完全兼容你后续调用pd.read_sql、pd.to_sql的需求，不需要修改后续业务代码
• 可以先执行engine.connect()测试连接是否正常，无报错再跑业务查询即可
• 如果连接仍有问题可先检查Linux主机是否已正确安装freetds、unixodbc相关依赖，可通过tsql -C命令验证FreeTDS是否安装正常

内容的提问来源于stack exchange，提问作者ajoseps