Mac环境下SQLAlchemy适配SQL Server ODBC Driver 18配置求助

1. 确认ODBC Driver 18已正确安装 #

先确保你已经按照微软官方的《Install the Microsoft ODBC driver for SQL Server (macOS)》教程完成驱动安装。可以通过以下命令验证驱动是否存在：

odbcinst -j

在输出的ODBC Drivers部分，应该能看到ODBC Driver 18 for SQL Server的条目。

2. 安装Python依赖包 #

需要安装SQLAlchemy和pyodbc（SQLAlchemy依赖它来连接ODBC数据源）：

pip install sqlalchemy pyodbc

3. 构建正确的连接字符串（关键配置） #

方式一：SQLAlchemy URL格式

直接在URL的查询参数中加入TrustServerCertificate=yes，注意驱动名称中的空格要替换为+：

from sqlalchemy import create_engine

# 替换为你的实际数据库信息
username = "your_username"
password = "your_password"
server = "your_server_address"
port = 1433  # 默认端口，自定义端口请修改
database = "your_database_name"

connection_url = f"mssql+pyodbc://{username}:{password}@{server}:{port}/{database}?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
engine = create_engine(connection_url)

# 测试连接
with engine.connect() as conn:
    result = conn.execute("SELECT 1")
    print(result.scalar())

方式二：基于pyodbc连接字符串

如果你的密码或服务器地址包含特殊字符（比如@、&），建议先构建pyodbc格式的连接字符串，再转义后传给SQLAlchemy：

from sqlalchemy import create_engine
import urllib.parse

conn_str = (
    "DRIVER={ODBC Driver 18 for SQL Server};"
    "SERVER=your_server_address,1433;"
    "DATABASE=your_database_name;"
    "UID=your_username;"
    "PWD=your_password;"
    "TrustServerCertificate=yes"
)
# 转义特殊字符
escaped_conn_str = urllib.parse.quote_plus(conn_str)
engine = create_engine(f"mssql+pyodbc:///?odbc_connect={escaped_conn_str}")

# 测试连接
with engine.connect() as conn:
    print(conn.execute("SELECT @@VERSION").fetchone())

关键注意事项 #

• TrustServerCertificate=yes的必要性：Mac环境下，SQL Server默认的SSL证书验证逻辑容易导致连接失败，必须显式设置该参数跳过证书验证（如果是生产环境且有可信证书，可根据情况调整）。
• 驱动名称必须完全匹配：确保驱动名称和odbcinst -j输出的一致，比如不能写成ODBC Driver 17或者省略版本号。
• 端口设置：如果SQL Server使用默认1433端口，URL中可以省略:1433；自定义端口必须明确指定。

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