如何在 Python 中使用 pyodbc 连接 Azure SQL 数据库

本文详解使用 pyodbc 连接 azure sql 数据库的完整流程，涵盖 odbc 驱动安装、连接字符串构造、安全连接实践及常见错误排查，助你快速建立稳定数据库连接。

要在 Python 中通过 pyodbc 成功连接 Azure SQL 数据库，仅安装 pyodbc 包是不够的——它只是一个 Python 接口层，底层依赖系统级的 Microsoft ODBC Driver for SQL Server。你遇到的 IM002 错误（“Data source name not found and no default driver specified”）正表明：系统中未安装或未正确注册该驱动程序。

✅ 第一步：安装 Microsoft ODBC Driver

Windows 用户

• 访问官方下载页：ODBC Driver for SQL Server
• 推荐安装 ODBC Driver 18 for SQL Server（支持 TLS 1.2+ 和 Azure AD 身份验证）。
• 下载对应架构的安装包（如 x64）：
  ? Direct link for ODBC Driver 18 (x64)
• 双击 .exe 安装，全程默认选项即可（无需重启，但建议验证后重试脚本）。

Linux 用户（以 Debian 12 为例）

# 下载并安装 ODBC Driver 18
curl https://packages.microsoft.com/debian/12/prod/pool/main/m/msodbcsql18/msodbcsql18_18.3.2.1-1_amd64.deb -o msodbcsql18.deb
sudo ACCEPT_EULA=Y dpkg --install msodbcsql18.deb

# 解决依赖（如提示 missing dependencies）
sudo apt-get update && sudo apt-get install -f -y

? 其他发行版请参考 Microsoft 官方 Linux 安装指南。

✅ 第二步：构建并验证连接字符串

Azure 门户提供的 ODBC 连接字符串通常形如：

Driver={ODBC Driver 18 for SQL Server};Server=tcp:your-server.database.windows.net,1433;Database=your-db;Uid=your-user;Pwd=your-password;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;

⚠️ 注意以下关键点：

• Driver= 后的名称必须与系统中已安装驱动的精确显示名一致（可通过 pyodbc.drivers() 查看）；
• 必须显式指定 Encrypt=yes（Azure SQL 强制加密）；
• 建议添加 TrustServerCertificate=no（启用证书链验证，提升安全性）；
• 端口 1433 应显式写在 Server= 后（逗号分隔），而非用 Port= 参数（部分驱动不识别）。

✅ 推荐的 Python 连接代码（含错误处理与验证）：

import pyodbc

# 1. 检查可用驱动（调试用）
print("Available drivers:", pyodbc.drivers())

# 2. 构建连接字符串（推荐使用 f-string 或字典格式化，避免 str.format 潜在格式错误）
driver = "{ODBC Driver 18 for SQL Server}"
server = "your-server.database.windows.net"
database = "your-db"
username = "your-user"
password = "your-password"

conn_str = (
    f"Driver={driver};"
    f"Server={server},1433;"
    f"Database={database};"
    f"Uid={username};"
    f"Pwd={password};"
    "Encrypt=yes;"
    "TrustServerCertificate=no;"
    "Connection Timeout=30;"
)

try:
    conn = pyodbc.connect(conn_str)
    print("✅ 连接成功！")
    print(f"DBMS 名称: {conn.getinfo(pyodbc.SQL_DBMS_NAME)}")
    print(f"DBMS 版本: {conn.getinfo(pyodbc.SQL_DBMS_VER)}")

    # 示例：执行简单查询
    cursor = conn.cursor()
    cursor.execute("SELECT @@VERSION;")
    print("SQL Server 版本:", cursor.fetchone()[0])

except pyodbc.Error as e:
    print("❌ 连接失败:", e)
finally:
    if 'conn' in locals() and conn:
        conn.close()
        print("? 连接已关闭")

⚠️ 常见问题与最佳实践

• 驱动名不匹配？ 运行 pyodbc.drivers() 查看真实驱动名（例如 Windows 上可能是 ODBC Driver 18 for SQL Server，Linux 上为 ODBC Driver 18 for SQL Server 或 ODBC Driver 17 for SQL Server）。
• 防火墙/网络限制？ 确保 Azure SQL 服务器的防火墙允许你的客户端 IP，或已启用“允许 Azure 服务和资源访问此服务器”。
• 凭据安全？ 切勿硬编码密码！推荐使用 Azure Key Vault、环境变量（os.getenv("DB_PASSWORD")）或 Azure AD 托管标识（生产环境首选）。
• 连接池？ 生产应用建议使用 pyodbc.pooling = True（默认开启）并复用连接，避免频繁创建/销毁开销。

完成以上步骤后，你将获得一个稳定、安全、可扩展的 Azure SQL 数据库 Python 连接方案。