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

本文详解在 python 中通过 pyodbc 连接 azure sql 数据库的完整流程，涵盖 odbc 驱动安装、连接字符串构造、安全连接实践及常见错误排查。

要成功使用 pyodbc 连接 Azure SQL 数据库，仅编写 Python 代码是不够的——关键前提是系统中必须已安装兼容且受支持的 Microsoft ODBC 驱动程序。你遇到的 pyodbc.InterfaceError: 'Data source name not found and no default driver specified' 错误，根本原因正是：{ODBC Driver 18 for SQL Server} 这一驱动名称在本地系统中未注册（即驱动未安装），导致 pyodbc 无法解析并加载对应驱动。

✅ 步骤一：安装 Microsoft ODBC Driver for SQL Server

请根据操作系统选择对应版本安装（推荐 ODBC Driver 18，它原生支持 TLS 1.2+、Azure AD 认证和最新 Azure SQL 功能）：

• Windows：
  下载并运行官方安装包（x64 推荐）：
  ? ODBC Driver 18 for SQL Server (Windows)
  安装完成后，可通过 PowerShell 验证：

  Get-OdbcDriver | Where-Object Name -like "*ODBC Driver 18*"

• 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  # 自动修复依赖

⚠️ 注意：Ubuntu/Debian 用户需确保已添加 Microsoft GPG 密钥与源；CentOS/RHEL 用户请参考官方文档选择 .rpm 包。

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

Azure 门户提供的 ODBC 连接字符串通常形如：
Driver={ODBC Driver 18 for SQL Server};Server=tcp:yourserver.database.windows.net,1433;Database=yourdb;Uid=username;Pwd=password;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;

立即学习“Python免费学习笔记（深入）”；

⚠️ 关键配置项说明（必须显式设置，否则连接失败）：

• Encrypt=yes：强制加密（Azure SQL 强制要求）
• TrustServerCertificate=no：启用证书链验证（生产环境必需）
• Connection Timeout=30：避免无限等待

优化后的 Python 示例（含异常处理与连接验证）：

import pyodbc

# 替换为你的实际参数（建议从环境变量读取，避免硬编码密码）
DRIVER = "{ODBC Driver 18 for SQL Server}"
SERVER = "yourserver.database.windows.net"
DATABASE = "yourdb"
USERNAME = "youruser"
PASSWORD = "yourpassword"

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"数据库管理系统: {conn.getinfo(pyodbc.SQL_DBMS_NAME)}")
    print(f"版本: {conn.getinfo(pyodbc.SQL_DBMS_VER)}")

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

    conn.close()
except pyodbc.Error as e:
    print("❌ 连接失败:", str(e))

? 安全增强建议（生产环境必读）

• ✅ 避免明文密码：使用 os.getenv("AZURE_SQL_PASSWORD") 或 Azure Key Vault + azure-identity 库获取凭据；
• ✅ 启用 Azure AD 身份验证（更安全）：将 Uid 和 Pwd 替换为 Authentication=ActiveDirectoryPassword 并配合 azure-identity 使用；
• ✅ 防火墙与网络：确认 Azure SQL 服务器防火墙已允许客户端 IP，或已配置虚拟网络服务终结点；
• ✅ 最小权限原则：数据库用户应仅授予必要权限（如 db_datareader / db_datawriter），而非 db_owner。

完成上述步骤后，你将获得稳定、安全、符合 Azure 最佳实践的 Python 到 Azure SQL 数据库连接能力。