macOS（Brew）下Python连接SQL Server遇SSL协议不支持错误求助

问题重现 #

在macOS的Brew环境中，Python（Django）连接SQL Server时抛出以下错误：

conn = Database.connect(connstr, **args)
django.db.utils.OperationalError: ('08001', '[08001] [Microsoft][ODBC Driver 17 for SQL Server]SSL Provider: [error:0A000102:SSL routines::unsupported protocol] (-1) (SQLDriverConnect)')

已确认网络连通性（可ping通服务器）和凭据正确性（Azure Data Studio可正常连接），尝试指定OpenSSL版本、设置Encrypt=false;TrustServerCertificate=true均无效。

解决方案 #

1. 强制指定TLS协议版本 #

SQL Server可能使用较旧的TLS版本（如TLS 1.2），而OpenSSL 3默认禁用部分旧协议。直接在连接字符串中指定兼容的TLS版本：

• 原生pyodbc连接：

conn_str = (
    "DRIVER={ODBC Driver 17 for SQL Server};"
    "SERVER=你的服务器地址;"
    "DATABASE=你的数据库名;"
    "UID=用户名;"
    "PWD=密码;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"
    "TLS_Version=TLSv1.2"
)

• Django配置（settings.py）：

DATABASES = {
    'default': {
        'ENGINE': 'sql_server.pyodbc',
        'NAME': '你的数据库名',
        'USER': '用户名',
        'PASSWORD': '密码',
        'HOST': '你的服务器地址',
        'PORT': '1433',
        'OPTIONS': {
            'driver': 'ODBC Driver 17 for SQL Server',
            'extra_params': 'Encrypt=yes;TrustServerCertificate=yes;TLS_Version=TLSv1.2',
        },
    }
}

注：若服务器支持TLS 1.3，可替换为TLSv1.3

2. 重新绑定ODBC驱动到OpenSSL 1.1 #

Brew安装的ODBC驱动可能默认关联OpenSSL 3，重新安装驱动并指定依赖OpenSSL 1.1：

# 卸载现有驱动
brew uninstall msodbcsql17 mssql-tools
# 安装OpenSSL 1.1
brew install openssl@1.1
# 从源码编译安装ODBC驱动，绑定OpenSSL 1.1
brew install msodbcsql17 mssql-tools --build-from-source --with-openssl@1.1
# 配置环境变量优先使用OpenSSL 1.1（以zsh为例）
echo 'export PATH="/usr/local/opt/openssl@1.1/bin:$PATH"' >> ~/.zshrc
echo 'export LDFLAGS="-L/usr/local/opt/openssl@1.1/lib"' >> ~/.zshrc
echo 'export CPPFLAGS="-I/usr/local/opt/openssl@1.1/include"' >> ~/.zshrc
source ~/.zshrc

3. 调整OpenSSL安全级别 #

若上述方法无效，降低OpenSSL的安全级别以允许旧协议：

# 临时生效
export SSL_CIPHERS="DEFAULT@SECLEVEL=1"
# 永久生效（zsh）
echo 'export SSL_CIPHERS="DEFAULT@SECLEVEL=1"' >> ~/.zshrc
source ~/.zshrc

关键说明 #

• Encrypt=false无效的原因：部分SQL Server实例强制要求加密连接，客户端设置会被服务器端配置覆盖，因此需主动指定兼容的加密协议而非关闭加密。
• OpenSSL版本指定无效的原因：仅设置环境变量可能未让ODBC驱动重新加载依赖，需重新编译驱动确保绑定目标OpenSSL版本。

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