SQLAlchemy使用OLE DB驱动连接MS SQL的连接字符串配置问题

问题背景 #

当前在Python环境中使用SQLAlchemy搭配SQL Server Native Client访问MS SQL数据库。根据微软官方文档说明，SQL Server Native Client已被弃用，官方推荐替代方案为Microsoft OLE DB Driver for SQL Server，但调整连接字符串后始终连接失败。

故障复现 #

• 原Native Client环境下可正常运行的连接代码：

engine = sqlalchemy.create_engine(f'mssql+pyodbc://{databaseAccess}@{Hostname:Port}/{database}?driver=SQL+Server+Native+Client+11.0', echo=True)

• 自行调整后的连接代码运行失败，初步怀疑是driver参数配置错误，或需要替换pyodbc模块：

sqlalchemy.create_engine(f'mssql+pyodbc://{databaseAccess}@{Hostname:Port}/{database}?driver=Microsoft+OLE+DB+Driver+19+for+SQL+Server', echo=True)

• 运行返回德语接口错误，核心含义为未找到数据源名称、未指定默认驱动，判定为连接字符串配置错误，报错原文：

(pyodbc.InterfaceError) ('IM002', '[IM002] [Microsoft][ODBC Driver Manager] Der Datenquellenname wurde nicht gefunden, und es wurde kein Standardtreiber angegeben (0) (SQLDriverConnect)')

故障原因 #

1. 驱动适配错误：pyodbc是ODBC连接层，仅支持ODBC协议的驱动，无法直接调用OLE DB Driver。配置的Microsoft OLE DB Driver 19 for SQL Server属于OLE DB协议驱动，pyodbc无法识别。
2. 驱动名称不匹配：系统中不存在填写的名称对应的ODBC驱动，因此触发IM002找不到驱动的报错。

正确配置步骤 #

• 安装适配pyodbc的官方替代驱动：下载安装Microsoft ODBC Driver 18/19 for SQL Server（注意选择和Python运行环境位数一致的安装包，32位Python对应32位驱动，64位对应64位驱动）。
• 查询系统中已安装驱动的准确名称：打开对应位数的ODBC数据源管理器，在「驱动」选项卡中找到刚安装的ODBC驱动，复制其完整显示名称（常见名称为ODBC Driver 18 for SQL Server、ODBC Driver 19 for SQL Server，必须和系统显示完全一致，不能自行修改）。
• 编写连接代码，使用urllib.parse.quote_plus转义驱动名中的空格，避免URL解析错误，参考代码如下：

from sqlalchemy import create_engine
from urllib.parse import quote_plus

# 替换为实际查到的驱动名称
driver = "ODBC Driver 18 for SQL Server"
conn_url = (
    f"mssql+pyodbc://{databaseAccess}@{Hostname}:{Port}/{database}"
    f"?driver={quote_plus(driver)}"
    # 测试环境使用自签名证书时可添加以下参数跳过证书校验，生产环境请勿启用
    # "&TrustServerCertificate=yes"
)
engine = create_engine(conn_url, echo=True)

补充说明：如果确实需要使用OLE DB Driver而非ODBC Driver，需要将连接层从pyodbc替换为支持OLE DB协议的模块（如adodbapi），连接串前缀改为mssql+adodbapi，但目前Python生态下ODBC Driver + pyodbc是兼容性、稳定性最好的组合，也是微软官方推荐的SQL Server Python连接方案。

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