Python3 模块精讲：psycopg2（第三方）- 连接 PostgreSQL

文章标签：#Python #PostgreSQL #psycopg2 #数据库 #后端开发

📝 本章学习目标

本章聚焦 Python 后端开发、数据存储、微服务与数据分析场景，帮助读者从零到一掌握 psycopg2 连接与操作 PostgreSQL 的全流程技能。通过本章学习，你将全面掌握：

psycopg2 核心概念与工作原理
安全连接、异常处理、上下文管理
增删改查（CRUD）实战与批量操作
事务、存储过程、连接池等高阶用法
生产最佳实践、性能优化与常见问题排查

一、引言：为什么 psycopg2 如此重要

在现代后端架构中，PostgreSQL 以开源免费、支持复杂查询、JSON / 数组类型、地理信息、高并发可靠等优势，成为企业级数据库首选。而 psycopg2 是 PostgreSQL 官方推荐、生态最成熟、性能最稳定的 Python 第三方连接库。

1.1 背景与意义

💡 核心认知：psycopg2 让 Python 与 PostgreSQL 实现高效、安全、稳定的数据交互，是后端、爬虫、数据分析、AI 数据管道的必备基础设施。

纯 C 扩展实现，执行效率远超纯 Python 驱动
完整支持 PostgreSQL 协议、事务、游标、COPY 高速导入
兼容 Python 3.6+，支持 PostgreSQL 9.5 ~ 16+ 全版本
支持 Django、Flask、FastAPI、SQLAlchemy 等主流框架
企业生产环境使用率超过 85%，生态完善、坑少、资料全

1.2 本章结构概览

plaintext

复制代码

📊 概念解析 → 技术原理 → 安装配置 → 基础连接 → 核心操作 → 高级特性 → 实战案例 → 最佳实践 → 常见问题 → 总结展望

二、核心概念解析

2.1 基本定义

概念一：psycopg2 核心特性

表格

特性	说明	应用场景
C 扩展高性能	底层基于 libpq，速度极快	高并发写入 / 查询
完整事务支持	提交、回滚、保存点、两阶段提交	金融 / 订单 / 强一致业务
服务端游标	大数据集流式读取	千万级数据导出 / ETL
类型映射完善	自动适配 JSON / 数组 / UUID / 几何类型	复杂业务存储
COPY 命令支持	高速批量导入 / 导出	日志、埋点、数据仓库
连接池友好	兼容 DBUtils/PgBouncer	高并发 Web 服务

概念二：PostgreSQL 连接核心参数

host ：数据库地址（本地 localhost/127.0.0.1）
port：默认 5432
dbname：数据库名（必填）
user：用户名
password：密码
options：设置字符集、schema 等
connect_timeout：连接超时

2.2 关键术语解释

⚠️ 注意：以下术语是理解本章内容的基础，请务必掌握。

连接对象 connection：Python ↔ PostgreSQL 的通信通道
游标对象 cursor：执行 SQL、获取结果集的操作句柄
服务端游标 server-side cursor：数据库端分页返回，节省内存
参数化查询 % s ：psycopg2 防注入标准写法（不是 Python 格式化）
事务自动提交 ：psycopg2 默认关闭，必须手动 commit
字典游标 RealDictCursor：返回字典格式，字段名 = key，最常用

2.3 技术架构概览

💡 架构理解：

plaintext

复制代码

┌─────────────────────────────────────────┐
│              应用层 (Python)             │
│      FastAPI/Flask/脚本/ETL 任务         │
├─────────────────────────────────────────┤
│              psycopg2 驱动层             │
│    连接管理、游标、事务、协议封装         │
├─────────────────────────────────────────┤
│              libpq 系统层                │
│        PostgreSQL 官方 C 客户端库         │
├─────────────────────────────────────────┤
│              PostgreSQL 服务层           │
│        数据库、表、索引、事务日志         │
└─────────────────────────────────────────┘

三、技术原理深入

3.1 核心技术原理

psycopg2 基于 PostgreSQL 官方 libpq 库 实现，通过 TCP 建立连接，遵循前端 / 后端协议交互：

应用调用 psycopg2.connect() 建立 TCP 连接
身份验证（密码 / SCRAM / 证书）
创建连接，返回 connection 对象
创建 cursor，发送 SQL 语句
PostgreSQL 执行并返回结果
psycopg2 解析为 Python 类型
手动 commit/rollback 控制事务
关闭游标 → 关闭连接，释放资源

技术一：连接与游标生命周期

python

运行

复制代码

# 标准流程（必须掌握）
1. 建立连接 connect()
2. 创建游标 cursor()
3. 执行 execute()
4. 获取结果 fetchone()/fetchall()
5. 提交事务 commit() / 回滚 rollback()
6. 关闭游标 close()
7. 关闭连接 close()

技术二：参数化查询原理

psycopg2 使用 %s 作为占位符，自动转义，彻底防止 SQL 注入。

错误写法：拼接字符串 → 高危注入
正确写法：execute(sql, (param1, param2))

3.2 数据交互机制

📊 标准数据流：用户请求 → 建立连接 → 创建游标 → 执行参数化SQL → 获取结果 → 提交/回滚 → 关闭资源

3.3 性能优化策略

💡 优化技巧：

表格

优化方向	具体方法	效果
连接复用	使用连接池，避免频繁建连	提升 60%+ 响应速度
批量写入	executemany / copy_from	提升 10~100 倍写入
大数据集	服务端游标 + 分批 fetch	内存占用降低 90%
事务优化	批量包裹事务，减少 fsync	写入提速 5~10 倍
类型优化	使用原生 JSON / 数组，避免字符串	查询更快、空间更小

四、安装与环境准备

4.1 安装 psycopg2

bash

运行

复制代码

# 安装二进制包（推荐，无需编译）
pip install psycopg2-binary

# 源码编译版（生产环境可选）
pip install psycopg2

# 国内镜像加速
pip install psycopg2-binary -i https://pypi.tuna.tsinghua.edu.cn/simple

4.2 安装验证

python

运行

复制代码

# 验证安装
import psycopg2
from psycopg2 import errors

# 输出版本
print("psycopg2 版本:", psycopg2.__version__)

4.3 PostgreSQL 准备

创建数据库

sql

复制代码

CREATE DATABASE test_db OWNER postgres ENCODING 'UTF8';

创建测试表（后续用）

sql

sql 复制代码

CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    age INT,
    email VARCHAR(100),
    create_time TIMESTAMP DEFAULT NOW()
);

五、基础连接实战（核心代码）

5.1 最简连接（无异常处理）

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2

# 连接配置
config = {
    "host": "127.0.0.1",
    "port": 5432,
    "dbname": "test_db",
    "user": "postgres",
    "password": "你的密码",
}

# 1. 建立连接
conn = psycopg2.connect(**config)

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

print("✅ 连接成功")

# 3. 关闭
cur.close()
conn.close()
print("✅ 已关闭连接")

5.2 安全连接（异常捕获，生产必备）

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2
from psycopg2 import OperationalError, ProgrammingError

def safe_connect():
    config = {
        "host": "127.0.0.1",
        "port": 5432,
        "dbname": "test_db",
        "user": "postgres",
        "password": "你的密码",
    }
    try:
        conn = psycopg2.connect(**config)
        cur = conn.cursor()
        print("✅ 连接成功")
        return conn, cur
    except OperationalError as e:
        print(f"❌ 连接失败：账号/密码/服务异常 {e}")
        return None, None
    except ProgrammingError as e:
        print(f"❌ 数据库不存在 {e}")
        return None, None
    except Exception as e:
        print(f"❌ 未知错误 {e}")
        return None, None

# 使用
conn, cur = safe_connect()
if cur:
    cur.close()
if conn:
    conn.close()

5.3 上下文管理器连接（自动关闭，强烈推荐）

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2
from psycopg2.extras import RealDictCursor

def connect_with_context():
    config = {
        "host": "127.0.0.1",
        "port": 5432,
        "dbname": "test_db",
        "user": "postgres",
        "password": "你的密码",
    }
    try:
        # with 自动关闭连接
        with psycopg2.connect(**config) as conn:
            # 字典游标，返回 {字段名: 值}
            with conn.cursor(cursor_factory=RealDictCursor) as cur:
                print("✅ 字典游标连接成功")
                return True
    except Exception as e:
        print(f"❌ 失败 {e}")
        return False

connect_with_context()

5.4 远程 PostgreSQL 连接

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2

def remote_connect():
    config = {
        "host": "47.xxx.xxx.xxx",  # 公网IP
        "port": 5432,
        "dbname": "test_db",
        "user": "postgres",
        "password": "远程密码",
        "connect_timeout": 5,  # 超时5秒
    }
    try:
        conn = psycopg2.connect(**config)
        print("✅ 远程连接成功")
        return conn
    except Exception as e:
        print(f"❌ 远程连接失败 {e}")
        return None

conn = remote_connect()
if conn:
    conn.close()

六、核心 CRUD 操作实战

6.1 单条插入（参数化，防注入）

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2

def insert_one(username, age, email):
    config = {...}  # 同上
    conn = psycopg2.connect(**config)
    cur = conn.cursor()

    # 参数化 SQL（%s 是 psycopg2 占位符）
    sql = """
    INSERT INTO users (username, age, email)
    VALUES (%s, %s, %s) RETURNING id;
    """
    try:
        cur.execute(sql, (username, age, email))
        # 获取返回的自增ID
        user_id = cur.fetchone()[0]
        # 必须提交！
        conn.commit()
        print(f"✅ 插入成功，ID={user_id}")
    except Exception as e:
        conn.rollback()
        print(f"❌ 插入失败 {e}")
    finally:
        cur.close()
        conn.close()

# 调用
insert_one("zhangsan", 23, "zhangsan@test.com")

6.2 批量插入（高性能）

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2

def insert_batch(user_list):
    config = {...}
    conn = psycopg2.connect(**config)
    cur = conn.cursor()

    sql = "INSERT INTO users (username, age, email) VALUES (%s, %s, %s);"
    try:
        # 批量执行，效率极高
        cur.executemany(sql, user_list)
        conn.commit()
        print(f"✅ 批量插入 {cur.rowcount} 条")
    except Exception as e:
        conn.rollback()
        print(f"❌ 批量失败 {e}")
    finally:
        cur.close()
        conn.close()

# 测试数据
users = [
    ("lisi", 24, "lisi@test.com"),
    ("wangwu", 25, "wangwu@test.com"),
]
insert_batch(users)

6.3 查询单条数据

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2
from psycopg2.extras import RealDictCursor

def get_one(user_id):
    config = {...}
    try:
        with psycopg2.connect(**config) as conn:
            with conn.cursor(cursor_factory=RealDictCursor) as cur:
                sql = "SELECT * FROM users WHERE id = %s;"
                cur.execute(sql, (user_id,))
                user = cur.fetchone()
                print("✅ 查询结果:", user)
                return user
    except Exception as e:
        print(f"❌ 查询失败 {e}")
        return None

get_one(1)

6.4 查询多条 / 全部数据

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2
from psycopg2.extras import RealDictCursor

def get_all():
    config = {...}
    try:
        with psycopg2.connect(**config) as conn:
            with conn.cursor(cursor_factory=RealDictCursor) as cur:
                sql = "SELECT id,username,age FROM users ORDER BY id DESC;"
                cur.execute(sql)
                rows = cur.fetchall()
                print(f"✅ 共 {len(rows)} 条")
                for r in rows:
                    print(r)
                return rows
    except Exception as e:
        print(f"❌ {e}")
        return []

get_all()

6.5 更新数据

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2

def update_age(user_id, new_age):
    config = {...}
    conn = psycopg2.connect(**config)
    cur = conn.cursor()
    sql = "UPDATE users SET age = %s WHERE id = %s;"
    try:
        cur.execute(sql, (new_age, user_id))
        conn.commit()
        print(f"✅ 更新成功，影响行数 {cur.rowcount}")
    except Exception as e:
        conn.rollback()
        print(f"❌ 更新失败 {e}")
    finally:
        cur.close()
        conn.close()

update_age(1, 26)

6.6 删除数据

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2

def delete_user(user_id):
    config = {...}
    conn = psycopg2.connect(**config)
    cur = conn.cursor()
    sql = "DELETE FROM users WHERE id = %s;"
    try:
        cur.execute(sql, (user_id,))
        conn.commit()
        print(f"✅ 删除成功 {cur.rowcount}")
    except Exception as e:
        conn.rollback()
        print(f"❌ 删除失败 {e}")
    finally:
        cur.close()
        conn.close()

delete_user(3)

七、高级特性实战

7.1 事务与保存点

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2

def transaction_with_savepoint():
    config = {...}
    conn = psycopg2.connect(**config)
    cur = conn.cursor()
    try:
        # 步骤1
        cur.execute("INSERT INTO users (username) VALUES ('test1');")
        # 创建保存点
        conn.savepoint("sp1")

        # 步骤2（故意出错）
        cur.execute("INSERT INTO users (username) VALUES ('test1');")

        conn.commit()
    except Exception as e:
        # 回滚到保存点，保留步骤1
        conn.rollback("sp1")
        conn.commit()
        print("✅ 回滚到保存点，已提交前半段")
    finally:
        cur.close()
        conn.close()

transaction_with_savepoint()

7.2 服务端游标（处理千万级数据）

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2

def server_side_cursor():
    config = {...}
    conn = psycopg2.connect(**config)
    # 创建服务端游标
    cur = conn.cursor(name='server_cursor')
    try:
        cur.execute("SELECT * FROM users;")
        # 每次取100条
        while True:
            batch = cur.fetchmany(100)
            if not batch:
                break
            print(f"✅ 读取 {len(batch)} 条")
    finally:
        cur.close()
        conn.close()

server_side_cursor()

7.3 高速 COPY 导入（百万级秒级）

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2
import io

def copy_from_csv():
    config = {...}
    conn = psycopg2.connect(**config)
    cur = conn.cursor()

    # 构造内存文本
    data = "user1,20,user1@a.com\nuser2,21,user2@a.com"
    f = io.StringIO(data)

    try:
        cur.copy_from(
            file=f,
            table="users",
            sep=",",
            columns=("username", "age", "email")
        )
        conn.commit()
        print("✅ COPY 导入完成")
    except Exception as e:
        conn.rollback()
        print(f"❌ {e}")
    finally:
        cur.close()
        conn.close()

copy_from_csv()

7.4 连接池（高并发必备）

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2
from dbutils.pooled_db import PooledDB

# 连接池
pool = PooledDB(
    creator=psycopg2,
    maxconnections=10,
    mincached=2,
    maxcached=5,
    host="127.0.0.1",
    port=5432,
    dbname="test_db",
    user="postgres",
    password="你的密码",
)

def query_pool():
    conn = pool.connection()
    cur = conn.cursor()
    try:
        cur.execute("SELECT COUNT(*) FROM users;")
        print("✅ 连接池查询:", cur.fetchone())
    finally:
        cur.close()
        conn.close()  # 归还连接池

query_pool()

八、最佳实践分享

8.1 安全最佳实践

必须使用 参数化 % s，禁止字符串拼接 SQL
密码不硬编码，使用环境变量 / 配置文件
业务账号最小权限，禁止用 superuser
所有异常捕获，避免信息泄露
生产关闭自动提交，手动控制事务

8.2 性能最佳实践

高并发必须用 连接池
批量写入优先用 copy_from / executemany
大数据集用 服务端游标
避免 SELECT *，只查需要字段
合理建索引，定期 ANALYZE

8.3 代码规范

配置抽离，统一管理
封装工具类，复用逻辑
强制使用 with 自动关闭
统一日志、统一错误返回
SQL 格式化，便于阅读与维护

九、常见问题解答

Q1：操作不生效，无报错

原因：psycopg2 默认不自动提交 解决：增删改必须 conn.commit()

Q2：报错 `operator does not exist: integer == integer`

原因：PostgreSQL 用 = 不用 ==解决：修正 SQL 语法

Q3：中文乱码

解决：数据库与连接均使用 UTF8

Q4：远程连接超时

解决：

防火墙放行 5432
postgresql.conf 设 listen_addresses = '*'
pg_hba.conf 允许客户端 IP

Q5：too many connections

解决：使用连接池，避免频繁创建连接

十、总结与展望

10.1 核心要点回顾

psycopg2 是 Python 操作 PostgreSQL 工业标准
核心流程：连接 → 游标 → 执行 → 提交 → 关闭
安全基石：参数化查询 防 SQL 注入
性能关键：连接池、批量、COPY、服务端游标
生产规范：异常处理、事务控制、资源释放

10.2 未来趋势

psycopg3 已发布，异步、类型更强
异步驱动 asyncpg 成为高并发新选择
云原生 PostgreSQL + 自动扩缩容成为主流
AI 数据管道大量依赖 PostgreSQL + psycopg2

10.3 学习建议

先练基础连接、CRUD、异常处理
再掌握事务、批量、服务端游标
最后封装工具类、接入连接池
结合 FastAPI/Flask 做真实项目

十一、生产级工具类封装（可直接复制使用）

python

运行

python 复制代码

# -*- coding: utf-8 -*-
import psycopg2
from psycopg2 import errors
from psycopg2.extras import RealDictCursor
from typing import List, Dict, Optional

class PGHelper:
    def __init__(self, host, port, dbname, user, password):
        self.config = {
            "host": host,
            "port": port,
            "dbname": dbname,
            "user": user,
            "password": password,
        }

    def _get_conn(self):
        try:
            conn = psycopg2.connect(**self.config)
            return conn
        except Exception as e:
            print(f"❌ 连接失败 {e}")
            return None

    def execute(self, sql: str, params: tuple = None) -> int:
        conn = self._get_conn()
        if not conn:
            return -1
        try:
            with conn:
                with conn.cursor() as cur:
                    cur.execute(sql, params)
                    return cur.rowcount
        except Exception as e:
            print(f"❌ 执行失败 {e}")
            return -1
        finally:
            conn.close()

    def fetch_one(self, sql: str, params: tuple = None) -> Optional[Dict]:
        conn = self._get_conn()
        if not conn:
            return None
        try:
            with conn:
                with conn.cursor(cursor_factory=RealDictCursor) as cur:
                    cur.execute(sql, params)
                    return cur.fetchone()
        except Exception as e:
            print(f"❌ {e}")
            return None
        finally:
            conn.close()

    def fetch_all(self, sql: str, params: tuple = None) -> List[Dict]:
        conn = self._get_conn()
        if not conn:
            return []
        try:
            with conn:
                with conn.cursor(cursor_factory=RealDictCursor) as cur:
                    cur.execute(sql, params)
                    return cur.fetchall()
        except Exception as e:
            print(f"❌ {e}")
            return []
        finally:
            conn.close()

# 使用示例
if __name__ == "__main__":
    pg = PGHelper(
        host="127.0.0.1",
        port=5432,
        dbname="test_db",
        user="postgres",
        password="你的密码",
    )
    users = pg.fetch_all("SELECT id,username FROM users;")
    print(users)

Python3 模块精讲：psycopg2（第三方）- 连接 PostgreSQL

📝 本章学习目标

一、引言：为什么 psycopg2 如此重要

1.1 背景与意义

1.2 本章结构概览

二、核心概念解析

2.1 基本定义

概念一：psycopg2 核心特性

概念二：PostgreSQL 连接核心参数

2.2 关键术语解释

2.3 技术架构概览

三、技术原理深入

3.1 核心技术原理

技术一：连接与游标生命周期

技术二：参数化查询原理

3.2 数据交互机制

3.3 性能优化策略

四、安装与环境准备

4.1 安装 psycopg2

4.2 安装验证

4.3 PostgreSQL 准备

五、基础连接实战（核心代码）

5.1 最简连接（无异常处理）

5.2 安全连接（异常捕获，生产必备）

5.3 上下文管理器连接（自动关闭，强烈推荐）

5.4 远程 PostgreSQL 连接

六、核心 CRUD 操作实战

6.1 单条插入（参数化，防注入）

6.2 批量插入（高性能）

6.3 查询单条数据

6.4 查询多条 / 全部数据

6.5 更新数据

6.6 删除数据

七、高级特性实战

7.1 事务与保存点

7.2 服务端游标（处理千万级数据）

7.3 高速 COPY 导入（百万级秒级）

7.4 连接池（高并发必备）

八、最佳实践分享

8.1 安全最佳实践

8.2 性能最佳实践

8.3 代码规范

九、常见问题解答

Q1：操作不生效，无报错

Q2：报错 operator does not exist: integer == integer

Q3：中文乱码

Q4：远程连接超时

Q5：too many connections

十、总结与展望

10.1 核心要点回顾

10.2 未来趋势

10.3 学习建议

十一、生产级工具类封装（可直接复制使用）

Q2：报错 `operator does not exist: integer == integer`