如何用SqlAlchemy连接Azure SQL数据库？代码报错排查与解决

问题描述 #

尝试用SQLAlchemy连接Azure SQL数据库时遇到多个错误，当前触发错误1，尝试其他方法时还出现过错误2和错误3，需指出代码问题并给出正确连接方式。

错误详情 #

错误1（当前代码触发） #

(pyodbc.Error) ('IM010', '[IM010] [Microsoft][ODBC Driver Manager] Data source name too long (0) (SQLDriverConnect)')
pyodbc.Error: ('IM010', '[IM010] [Microsoft][ODBC Driver Manager] Data source name too long (0) (SQLDriverConnect)')

错误2 #

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

错误3（不使用urllib时触发） #

ValueError: invalid literal for int() with base 10

原代码 #

import pyodbc
import time
import GW_PDR_Queries   as qu
import pandas           as pd
import sqlalchemy
import urllib

server   = 'myserver.database.windows.net'
database = 'myDatabase'
username = 'myUsername'
password = 'myPassword'   
# driver   = '{ODBC Driver 17 for SQL Server}'
driver   = 'Driver={SQL Server}'
# connection_string = 'DRIVER='+driver+';SERVER=tcp:'+server+';PORT=1433;DATABASE='+database+';UID='+username+';PWD='+ password
connection_string = driver+';SERVER=tcp:'+server+';PORT=1433;DATABASE='+database+';UID='+username+';PWD='+ password
# connection_string = username + '@' + server + ':' + password + '@' + server

connection_string = urllib.parse.quote_plus(connection_string)

#'DRIVER={SQL Server};SERVER=yoursqlAzureServer.database.windows.net,1433', user='yourName@yoursqlAzureServer', password='Password', database='DBName'
engine = sqlalchemy.create_engine('mssql+pyodbc://'+ connection_string)
# engine = sqlalchemy.create_engine(connection_string)

query = 'SELECT * FROM panel.panel_table'

with engine.begin() as conn:
    df = pd.read_sql_query(sql=text(query), con=conn)

问题分析与正确连接方法 #

代码问题点 #

1. 驱动版本过时：使用的Driver={SQL Server}是旧版驱动，Azure SQL推荐使用{ODBC Driver 17 for SQL Server}或更高版本，这是错误2的核心原因。
2. 连接字符串格式错误：
   • driver变量已包含Driver=前缀，拼接时重复添加导致字符串格式混乱，触发错误1。
   • SQLAlchemy的mssql+pyodbc URL格式错误，正确写法应为mssql+pyodbc:///?odbc_connect=<编码后的连接字符串>，而非直接拼接编码字符串。
3. 缺失依赖导入：代码中使用text(query)但未从sqlalchemy导入该对象，会导致运行报错。

正确代码实现 #

import pyodbc
import pandas as pd
import sqlalchemy
from sqlalchemy import text  # 导入text对象
import urllib

# 配置信息
server = 'myserver.database.windows.net'
database = 'myDatabase'
username = 'myUsername'
password = 'myPassword'
driver = '{ODBC Driver 17 for SQL Server}'  # 使用官方推荐驱动

# 构造标准ODBC连接字符串
connection_string = (
    f"DRIVER={driver};"
    f"SERVER=tcp:{server},1433;"  # Azure SQL用逗号分隔服务器与端口，无需PORT参数
    f"DATABASE={database};"
    f"UID={username};"
    f"PWD={password}"
)

# 编码连接字符串（转义特殊字符）
encoded_conn = urllib.parse.quote_plus(connection_string)

# 构造SQLAlchemy引擎
engine = sqlalchemy.create_engine(f"mssql+pyodbc:///?odbc_connect={encoded_conn}")

# 执行查询
query = 'SELECT * FROM panel.panel_table'
with engine.begin() as conn:
    df = pd.read_sql_query(sql=text(query), con=conn)

print(df.head())

各错误根源 #

• 错误1：连接字符串格式混乱（重复的Driver=前缀）+ 错误的URL拼接方式，导致ODBC驱动识别的数据源名称过长。
• 错误2：系统找不到旧版{SQL Server}驱动，需安装并使用推荐的ODBC驱动版本。
• 错误3：未编码的连接字符串被SQLAlchemy当作URL解析，部分字符串被误判为端口号尝试转整数，触发类型错误。

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