安装与环境搭建
确定系统环境与Python版本
在开始使用 psycopg2 连接 PostgreSQL 之前，确认系统环境和 Python 版本非常关键。此处我们建议 Python 3.8 及以上，以获得更好的类型提示和依赖管理，并确保操作系统有网络访问能力来安装依赖。
不同操作系统对依赖有差异。对于 Windows、macOS、Linux 等，尽量使用虚拟环境，以避免系统包冲突，避免全局安装，这也有利于后续版本升级。
如何选择 psycopg2 版本
psycopg2 提供两种常用版本：psycopg2-binary 和 psycopg2。二进制包包含 PostgreSQL 客户端库，安装简单，但有时不适用于编译扩展的场景；源代码包需要先安装系统的开发工具和 libpq 依赖，灵活性更高，但安装复杂。
如果你只是快速试用或开发，通常推荐 pip install psycopg2-binary；在生产环境中，若要严格控制依赖，请使用 pip install psycopg2 并确保系统具备 libpq-dev（Linux）/postgresql-client-dev 等依赖。
快速安装命令演示
以下命令展示如何在常见环境中安装 psycopg2。注意网络环境和 Python 环境映射，以避免版本不匹配。
在 macOS/Linux 上，优先使用虚拟环境，再执行安装命令：
# 使用虚拟环境
python3 -m venv venv
source venv/bin/activate# 安装 psycopg2-binary（快速上手）
pip install psycopg2-binary
在 Windows 上，确保你的命令提示符以管理员身份运行，同样创建虚拟环境后执行：
python -m venv venv
venv\\Scripts\\activate
pip install psycopg2-binary
连接与基本查询
建立数据库连接
要使用 psycopg2 连接 PostgreSQL，需要提供连接参数，如数据库名称、用户名、密码、主机和端口。连接对象保存会话信息，后续所有 SQL 都通过游标执行。
合理组织连接参数，避免硬编码，可通过环境变量或配置文件管理，确保安全性和可维护性。若连接失败，捕获异常并记录错误以便排查。
import psycopg2# 建立连接示例（请替换为你自己的参数）
conn = psycopg2.connect(dbname='mydb',user='myuser',password='mypassword',host='127.0.0.1',port=5432
)
连接成功后，应及时创建游标并进行 SQL 操作，同时要注意关闭资源，避免连接泄露。
执行查询与游标管理
执行 SELECT 等查询时，使用游标（cursor）来执行 SQL，并通过 fetchone / fetchmany / fetchall 来获取结果。参数化查询能有效防止 SQL 注入。
在查询完成后，务必关闭游标，并在不再需要时关闭数据库连接，确保资源回收。若遇到网络或权限问题，错误信息可帮助快速定位。
cur = conn.cursor()# 参数化查询，避免 SQL 注入
cur.execute("SELECT id, name FROM users WHERE id = %s", (42,))
row = cur.fetchone()print(row)cur.close()
执行多行查询时，可以使用 fetchall 获取全部结果，或结合 迭代器逐行读取，适用于大数据量场景而不耗尽内存。
事务与错误处理
PostgreSQL 的事务是应用最重要的保障之一。psycopg2 默认是手动提交模式，需要在 commit 或 rollback 之间做明确选择。使用 try/except能够在异常时自动执行回滚，确保数据一致性。
在生产环境，推荐使用上下文管理或显式提交，并对异常进行详细日志记录，帮助快速回溯问题。
try:conn.autocommit = Falsecur = conn.cursor()cur.execute("UPDATE accounts SET balance = balance - %s WHERE id = %s", (100, 1))cur.execute("UPDATE accounts SET balance = balance + %s WHERE id = %s", (100, 2))conn.commit()
except Exception as e:conn.rollback()# 记录错误信息，确保可追踪print("Transaction failed:", e)
finally:cur.close()
实战示例
从CSV导入数据到表
在实际项目中，将外部数据写入 PostgreSQL 表是常见场景。你可以使用 psycopg2 的参数化插入来保障安全性，逐行或批量导入都适用。注意数据类型匹配与事务控制。
下面示例使用 executemany 将多行数据批量写入表，提升性能并减少数据库连接开销。
import psycopg2conn = psycopg2.connect(dbname='mydb', user='myuser', password='mypassword', host='127.0.0.1')
cur = conn.cursor()rows = [(1, 'Alice', 'alice@example.com'),(2, 'Bob', 'bob@example.com'),(3, 'Charlie', 'charlie@example.com')
]cur.executemany("INSERT INTO users (id, name, email) VALUES (%s, %s, %s)", rows)
conn.commit()cur.close()
conn.close()
如果数据量很大，也可以考虑 COPY FROM 将 CSV 等文件直接导入，速度更快，但需要额外的文件处理步骤和权限控制。
import psycopg2
import io
import csvconn = psycopg2.connect(dbname='mydb', user='myuser', password='mypassword', host='127.0.0.1')
cur = conn.cursor()with open('data.csv', 'r', newline='') as f:cur.copy_expert("COPY users (id, name, email) FROM STDIN WITH CSV", f)conn.commit()
cur.close()
conn.close()
参数化查询与防注入
在实战中，避免把用户输入直接拼接到 SQL，应该使用 %s 占位符 进行参数化查询，确保 数据库安全性与稳定性。同时，使用事务提交点，以便回滚何时发生异常。
下面的示例展示如何更新用户信息时进行参数化，并在出现异常时回滚。
def update_user_email(user_id, email):conn = psycopg2.connect(dbname='mydb', user='myuser', password='mypassword', host='127.0.0.1')try:cur = conn.cursor()cur.execute("UPDATE users SET email = %s WHERE id = %s", (email, user_id))conn.commit()except Exception as e:conn.rollback()print("Update failed:", e)finally:cur.close()conn.close()
性能优化与最佳实践
使用连接池提升并发能力
对于高并发场景，直接逐一创建和销毁连接成本较高，因此使用连接池变得非常重要。psycopg2.pool.SimpleConnectionPool可以复用连接，降低创建开销，提升吞吐量。
在部署时，设定合理的最小/最大连接数，并监控连接池的状态，确保不会耗尽数据库资源。注意线程安全和进程模型的匹配。
from psycopg2 import pool# 建立连接池（示例：最小2个，最大10个）
db_pool = pool.SimpleConnectionPool(2, 10,user='myuser', password='mypassword', host='127.0.0.1', database='mydb'
)# 从池中获取连接
conn = db_pool.getconn()
try:cur = conn.cursor()cur.execute("SELECT COUNT(*) FROM users")count = cur.fetchone()[0]print("用户总数:", count)cur.close()
finally:# 归还连接给池db_pool.putconn(conn)# 关闭池
db_pool.closeall()
自动提交、事务边界与锁定注意事项
在涉及多表操作或复杂事务时，细粒度事务边界至关重要。避免长事务以减少锁等待时间，按需提交，并在必要时显式锁定表或行以避免并发冲突。
同时，hello world-level 的并发测试有助于在上线前发现瓶颈，确保你所使用的事务策略符合业务场景。
