如何解决pyodbc连接SQL Server时的Driver语法错误？

问题描述 #

在Windows机器上使用Python的SQLAlchemy连接SQL Server，当前生成的引擎连接字符串如下：

Engine(mssql+pyodbc://P-CEP-SQL:1433/services_vars?driver={ODBC Driver 18 for SQL Server})

此前连接同服务器另一实例的字符串可正常工作：

Engine(mssql+pyodbc://cam-tls1:1433/services_vars?driver=SQL Server)

但使用ODBC Driver 18的字符串时触发语法错误：

sqlalchemy.exc.DBAPIError: (pyodbc.Error) ('IM012', '[IM012] [Microsoft][ODBC Driver Manager] DRIVER keyword syntax error (0) (SQLDriverConnect)')

移除大括号后又报驱动未找到：

sqlalchemy.exc.InterfaceError: (pyodbc.InterfaceError) ('IM002', '[IM002] [Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified (0) (SQLDriverConnect)')

确认驱动名称正确，但带大括号的字符串报错，需明确是否需要额外转义及解决方式。

解决方案 #

• 核心原因：SQLAlchemy的URL格式中，查询参数内的特殊字符（如空格）需进行URL编码，大括号并非驱动名称的一部分，添加后反而触发语法错误。
• 方法1：手动URL编码驱动名称
  将驱动名称中的空格替换为%20，去掉多余的大括号，修改后的连接字符串如下：

  Engine(mssql+pyodbc://P-CEP-SQL:1433/services_vars?driver=ODBC%20Driver%2018%20for%20SQL%20Server)
  

• 方法2：使用SQLAlchemy URL构造器（推荐）
  借助SQLAlchemy内置的URL类构建连接字符串，自动处理特殊字符，避免手动编码失误：

  from sqlalchemy import create_engine
  from sqlalchemy.engine import URL
  
  connection_url = URL.create(
      "mssql+pyodbc",
      host="P-CEP-SQL",
      port=1433,
      database="services_vars",
      query={"driver": "ODBC Driver 18 for SQL Server"}
  )
  engine = create_engine(connection_url)
  

• 补充说明：旧驱动SQL Server的空格能直接生效，是因为ODBC驱动管理器对短名称的兼容机制，但长驱动名称含多个空格时，必须通过编码或构造器处理才能被正确识别。

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