使用 pyodbc (推荐)

pyodbc 是一个功能强大且广泛使用的数据库连接库，它通过 ODBC (Open Database Connectivity) 驱动来连接数据库，这意味着你的系统需要先安装 ODBC 驱动。

安装 ODBC 驱动

在连接之前,你的操作系统必须安装相应的 SQL Server ODBC 驱动。

• Windows: 通常会自动安装，或者你可以从 Microsoft ODBC Driver for SQL Server 官网下载安装。
• macOS: 使用 Homebrew 安装。

  brew install unixodbc
  brew install microsoft/mssql-release/current/mssql-tools

• Linux: 参考官方文档进行安装，例如在 Ubuntu/Debian 上：

  # 下载并运行 Microsoft SQL Server Red Hat repository configuration script
  curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
  curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql.list
  sudo apt-get update
  sudo ACCEPT_EULA=Y apt-get install -y msodbcsql17 mssql-tools

安装 pyodbc 库

使用 pip 安装 pyodbc。

pip install pyodbc

编写 Python 连接代码

连接字符串是关键,它包含了所有连接数据库所需的信息。

连接字符串格式: DRIVER={...};SERVER=...;DATABASE=...;UID=...;PWD=...

• DRIVER: 指定 ODBC 驱动名称，你可以在系统 ODBC 数据源管理器中查看已安装的驱动名称。ODBC Driver 17 for SQL Server。
• SERVER: SQL Server 实例的地址，可以是服务器名、IP 地址或 服务器名\实例名，对于本地默认实例，可以写 localhost 或 0.0.1。
• DATABASE: 你要连接的数据库名称。
• UID: 用户名。
• PWD: 密码。

示例代码:

import pyodbc
# --- 1. 定义连接字符串 ---
# 请根据你的实际情况修改以下信息
server = 'localhost'  # 或你的服务器 IP, 如 '192.168.1.100'
database = 'YourDatabaseName'  # 你的数据库名
username = 'your_username'      # 你的用户名
password = 'your_password'      # 你的密码
# ODBC 驱动名称，根据你安装的版本修改
# Windows 上可能是 'ODBC Driver 17 for SQL Server' 或 'ODBC Driver 18 for SQL Server'
# macOS/Linux 上可能是 'ODBC Driver 17 for SQL Server'
driver = 'ODBC Driver 17 for SQL Server'
# --- 2. 建立连接 ---
try:
    conn_str = f'DRIVER={{{driver}}};SERVER={server};DATABASE={database};UID={username};PWD={password}'
    print("正在尝试连接数据库...")
    conn = pyodbc.connect(conn_str)
    print("连接成功！")
    # --- 3. 创建游标并执行查询 ---
    cursor = conn.cursor()
    cursor.execute("SELECT @@VERSION AS SQL_Version;")
    # --- 4. 获取并打印结果 ---
    row = cursor.fetchone()
    if row:
        print(f"SQL Server 版本: {row[0]}")
    # --- 5. 关闭连接 ---
    cursor.close()
    conn.close()
    print("连接已关闭。")
except pyodbc.Error as e:
    print(f"连接数据库时出错: {e}")

使用 pymssql

pymssql 是一个纯 Python 实现的 SQL Server 客户端库，它不依赖 ODBC 驱动，安装和配置通常更简单，但在某些高级功能或性能上可能不如 pyodbc。

安装 pymssql 库

使用 pip 安装非常直接。

pip install pymssql

编写 Python 连接代码

pymssql 的连接方式更直接，参数与 pyodbc 类似。

示例代码:

import pymssql
# --- 1. 定义连接参数 ---
# 请根据你的实际情况修改以下信息
server = 'localhost'  # 或你的服务器 IP
database = 'YourDatabaseName'  # 你的数据库名
user = 'your_username'      # 你的用户名
password = 'your_password'      # 你的密码
# --- 2. 建立连接 ---
try:
    print("正在尝试连接数据库...")
    # 如果使用 Windows 身份验证，可以省略 user 和 password，并设置 trusted=True
    # conn = pymssql.connect(server=server, database=database, trusted=True)
    conn = pymssql.connect(server=server, database=database, user=user, password=password)
    print("连接成功！")
    # --- 3. 创建游标并执行查询 ---
    cursor = conn.cursor(as_dict=True) # as_dict=True 可以让结果以字典形式返回，更易读
    cursor.execute("SELECT TOP 3 * FROM YourTableName;") # 替换成你的表名
    # --- 4. 获取并打印结果 ---
    print("查询结果:")
    for row in cursor:
        print(row) # 因为 as_dict=True，row 是一个字典
    # --- 5. 关闭连接 ---
    conn.close()
    print("连接已关闭。")
except pymssql.Error as e:
    print(f"连接数据库时出错: {e}")

高级用法：使用连接池

对于 Web 应用或频繁连接数据库的场景，每次都创建和销毁连接是非常低效的，使用连接池可以复用连接，显著提升性能。

pyodbc 本身不提供连接池，但可以结合第三方库 pyodbcpool 或在 Web 框架（如 Flask, Django）中实现。

这里展示一个简单的 pyodbcpool 用法：

1. 安装 pyodbcpool

   pip install pyodbcpool

2. 示例代码

   import pyodbc
   from pyodbcpool import Pool
   # 连接字符串 (与方法一相同)
   conn_str = "DRIVER={ODBC Driver 17 for SQL Server};SERVER=localhost;DATABASE=YourDatabaseName;UID=your_username;PWD=your_password"
   # 创建一个连接池，最大连接数为 5
   pool = Pool(max_connections=5, conn_str=conn_str)
   try:
       # 从池中获取一个连接
       conn = pool.get_connection()
       print("从连接池中成功获取连接。")
       cursor = conn.cursor()
       cursor.execute("SELECT COUNT(*) FROM YourTableName;") # 替换成你的表名
       count = cursor.fetchone()[0]
       print(f"表 'YourTableName' 中的记录数: {count}")
       # 使用完毕后，将连接放回池中，而不是关闭它
       pool.return_connection(conn)
       print("连接已返回连接池。")
   except Exception as e:
       print(f"发生错误: {e}")
       # 如果连接出错，确保它被从池中移除
       if 'conn' in locals():
           pool.discard_connection(conn)
   finally:
       # 应用结束时，销毁连接池
       pool.dispose()
       print("连接池已销毁。")

最佳实践和注意事项

1. 不要硬编码凭据：永远不要在代码中直接写用户名和密码，应该使用环境变量、配置文件（如 .ini 或 .yaml）或密钥管理服务来存储敏感信息。

   使用环境变量的例子:

   import os
   import pyodbc
   server = os.environ.get('SQL_SERVER_HOST', 'localhost')
   database = os.environ.get('SQL_SERVER_DB', 'YourDatabaseName')
   username = os.environ.get('SQL_SERVER_USER')
   password = os.environ.get('SQL_SERVER_PASSWORD')
   if not all([username, password]):
       raise ValueError("用户名和密码必须通过环境变量设置！")
   conn_str = f'DRIVER={{ODBC Driver 17 for SQL Server}};SERVER={server};DATABASE={database};UID={username};PWD={password}'
   # ... 后续连接代码

2. 使用 with 语句管理资源：为了确保游标和连接总是被正确关闭，推荐使用 with 语句（上下文管理器）。pymssql 的游标和连接对象原生支持 with 语句。

   pymssql 使用 with 语句:

   import pymssql
   with pymssql.connect(server='localhost', database='YourDatabaseName', user='user', password='pass') as conn:
       with conn.cursor(as_dict=True) as cursor:
           cursor.execute("SELECT * FROM YourTable WHERE id = %s", (1,)) # 使用参数化查询防止SQL注入
           row = cursor.fetchone()
           print(row)
   # 退出 with 块后，conn 和 cursor 会自动关闭

3. 使用参数化查询：为了防止 SQL 注入攻击，永远不要用字符串拼接来构建 SQL 查询，使用参数化查询（或预处理语句）。

   错误示例 (SQL注入风险极高):

   user_id = "1; DROP TABLE YourTable; --"
   sql = f"SELECT * FROM Users WHERE id = {user_id}"
   cursor.execute(sql)

   正确示例 (安全):

   # pyodbc 使用问号作为占位符
   user_id = 1
   cursor.execute("SELECT * FROM Users WHERE id = ?", user_id)
   # pymssql 使用 %s 作为占位符
   user_id = 1
   cursor.execute("SELECT * FROM Users WHERE id = %s", user_id)

对于新项目,pyodbc 是更主流和推荐的选择，因为它通常被认为是更健壮和性能更好的方案，如果你在配置 ODBC 驱动时遇到困难，pymssql 是一个很好的备选方案。