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

本文详解在 python 中通过 pyodbc 连接 azure sql 数据库的完整流程，重点解决“data source name not found”驱动缺失错误，并提供跨平台（windows/linux）驱动安装指南与安全连接示例。

要成功使用 pyodbc 连接到 Azure SQL 数据库，仅编写连接代码是不够的——关键前提是系统中必须已安装兼容且已注册的 Microsoft ODBC 驱动程序。你遇到的错误：

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

明确表明：Python 找不到你指定的驱动 {ODBC Driver 18 for SQL Server}，即该驱动尚未安装或未正确注册到操作系统 ODBC 管理器中。

✅ 正确步骤：先装驱动，再连数据库

1. 下载并安装 Microsoft ODBC Driver for SQL Server

请根据你的操作系统选择对应版本（推荐最新稳定版，如 v18）：

• Windows（x64）：
  直接下载并运行官方安装包：
  https://www./link/5bf38e0fcbeebe423cbc6b20775bc2b4
  安装完成后，无需额外配置，驱动将自动注册为 {ODBC Driver 18 for SQL Server}。

• Linux（以 Debian 12 为例）：

  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 -i msodbcsql18.deb
  sudo apt-get install -f  # 自动修复依赖

? 提示：安装后可通过命令验证驱动是否就绪（Linux）：odbcinst -j 查看 ODBC 配置路径；odbcinst -j | grep "Driver" | xargs ls 可确认驱动文件是否存在。

2. 构建健壮的连接字符串（推荐使用关键字参数格式）

避免手动拼接易出错的字符串。使用 pyodbc.connect() 的关键字参数方式更清晰、安全：

import pyodbc

# 替换为你的实际值（建议从 Azure 门户「Connection strings」→「ODBC」标签页复制基础结构）
server = "your-server.database.windows.net"
database = "your-database"
username = "your-username"
password = "your-password"

conn_str = (
    "DRIVER={ODBC Driver 18 for SQL Server};"
    f"SERVER={server};"
    f"PORT=1433;"
    f"DATABASE={database};"
    f"UID={username};"
    f"PWD={password};"
    "Encrypt=yes;"           # ⚠️ Azure SQL 强制加密，必须设为 yes
    "TrustServerCertificate=no;"  # 禁用证书信任（生产环境必须）
    "Connection Timeout=30;"
)

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

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

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

? 安全注意事项（务必遵守）

• 永不硬编码密码：生产环境中应使用 Azure Key Vault、环境变量（os.getenv("AZURE_SQL_PASSWORD")）或托管标识（Managed Identity）进行凭据管理。
• 启用加密与证书验证：Azure SQL 要求 Encrypt=yes 且 TrustServerCertificate=no（强制 TLS + 服务端证书校验）。
• 防火墙与网络策略：确保 Azure SQL 服务器的防火墙允许客户端 IP，或已配置虚拟网络规则（VNet Service Endpoint / Private Link）。

✅ 验证驱动是否可用（调试必备）

运行以下代码快速检查驱动是否被系统识别：

import pyodbc
for driver in pyodbc.drivers():
    if "ODBC Driver 18" in driver:
        print("✅ 检测到驱动：", driver)
        break
else:
    print("❌ 未找到 ODBC Driver 18，请重新安装驱动")

完成驱动安装并采用上述连接方式后，即可稳定、安全地访问 Azure SQL 数据库。记住：驱动是桥梁，代码只是指令；没有桥，再优美的指令也无法抵达彼岸。