PyODBC 安装与配置指南：Python 数据库连接利器

2026-02-06 05:07:22作者：仰钰奇

PyODBC 是一个开源的 Python 模块，它简化了访问 ODBC 数据库的过程。该模块实现了 DB API 2.0 规范，并提供了更多 Pythonic 的便利功能。

项目结构与核心文件

PyODBC 项目采用清晰的结构设计，主要包含以下目录和文件：

核心源码目录 (src/)

pyodbcmodule.cpp: 主模块实现文件
connection.cpp / connection.h: 数据库连接管理
cursor.cpp / cursor.h: 游标操作实现
errors.cpp / errors.h: 错误处理机制
getdata.cpp / getdata.h: 数据获取功能
params.cpp / params.h: 参数处理

测试目录 (tests/)

sqlserver_test.py: SQL Server 测试用例
mysql_test.py: MySQL 测试用例
postgresql_test.py: PostgreSQL 测试用例
sqlite_test.py: SQLite 测试用例

配置文件

setup.py: Python 安装构建脚本
pyproject.toml: 项目元数据和构建配置
requirements-dev.txt: 开发依赖包

安装方法

使用 pip 安装（推荐）

最简单的安装方式是使用 pip 包管理器：

python -m pip install pyodbc

不同平台的安装说明

Windows 系统 Windows 系统内置了 ODBC 驱动管理器，直接安装即可：

pip install pyodbc

macOS 系统 建议先安装 unixODBC，再安装 pyodbc：

brew install unixodbc
pip install pyodbc

Linux 系统 确保系统已安装 ODBC 驱动管理器：

# Ubuntu/Debian
sudo apt-get install unixodbc-dev
pip install pyodbc

# CentOS/RHEL
sudo yum install unixODBC-devel
pip install pyodbc

ODBC 配置

Windows ODBC 配置

在 Windows 上，可以通过控制面板配置 ODBC 数据源：

打开"ODBC 数据源管理器"
在"用户 DSN"或"系统 DSN"选项卡中添加新数据源
选择相应的数据库驱动程序并配置连接参数

Unix/Linux ODBC 配置

在 Unix/Linux 系统上，需要配置 odbcinst.ini 和 odbc.ini 文件：

odbcinst.ini - 驱动程序配置：

[MySQL]
Description = MySQL ODBC Driver
Driver = /usr/lib/x86_64-linux-gnu/odbc/libmyodbc.so

odbc.ini - 数据源配置：

[MyDatabase]
Driver = MySQL
Server = localhost
Port = 3306
Database = testdb
User = username
Password = password

基本用法示例

建立数据库连接

import pyodbc

# 使用 DSN 连接
conn = pyodbc.connect('DSN=MyDatabase')

# 使用连接字符串连接
conn = pyodbc.connect(
    'DRIVER={SQL Server};'
    'SERVER=localhost;'
    'DATABASE=testdb;'
    'UID=username;'
    'PWD=password'
)

执行查询操作

# 创建游标
cursor = conn.cursor()

# 执行查询
cursor.execute("SELECT * FROM users WHERE age > ?", 18)

# 获取结果
for row in cursor:
    print(row.username, row.email)

# 插入数据
cursor.execute("INSERT INTO users (username, email) VALUES (?, ?)", 
               ('john_doe', 'john@example.com'))
conn.commit()

使用上下文管理器

with pyodbc.connect('DSN=MyDatabase') as conn:
    with conn.cursor() as cursor:
        cursor.execute("SELECT @@VERSION")
        version = cursor.fetchone()
        print(f"Database version: {version[0]}")

高级功能

批量操作

# 批量插入数据
data = [
    ('user1', 'user1@example.com'),
    ('user2', 'user2@example.com'),
    ('user3', 'user3@example.com')
]

cursor.executemany("INSERT INTO users (username, email) VALUES (?, ?)", data)
conn.commit()

事务管理

try:
    cursor.execute("UPDATE accounts SET balance = balance - 100 WHERE id = 1")
    cursor.execute("UPDATE accounts SET balance = balance + 100 WHERE id = 2")
    conn.commit()
except Exception as e:
    conn.rollback()
    print(f"Transaction failed: {e}")

错误处理

try:
    conn = pyodbc.connect('DSN=InvalidDSN')
except pyodbc.Error as e:
    print(f"Connection error: {e}")
    print(f"SQLSTATE: {e.args[0]}")
    print(f"Error message: {e.args[1]}")