Python连接PostgreSQL实战指南-代码聚汇网

1. 为什么选择Python连接PostgreSQL？

在数据驱动的时代，数据库连接是每个开发者必备的基础技能。PostgreSQL作为功能最强大的开源关系型数据库之一，与Python这对黄金组合在数据分析、Web开发、自动化运维等领域有着广泛应用。我最初接触这个技术栈是在2016年一个电商数据分析项目中，当时需要从千万级订单表中提取数据进行分析，正是Python+PostgreSQL的高效配合让任务顺利完成。

Python的psycopg2库是连接PostgreSQL的事实标准，它完美实现了DB-API 2.0规范，支持连接池、异步操作等高级特性。与其他语言相比，Python的简洁语法和丰富的数据处理生态（如Pandas、NumPy）使其成为PostgreSQL数据操作的理想选择。特别是在处理JSON类型数据时，Python的字典结构与PostgreSQL的JSONB类型可以无缝转换，这种便利性在其他技术栈中很难找到。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备与基础连接

2.1 安装必备组件

在开始编码前，我们需要准备好运行环境。以下是在Ubuntu 20.04系统上的安装步骤，Windows用户可以使用WSL或直接安装对应版本：

bash复制# 安装Python3和pip（如果尚未安装）
sudo apt update
sudo apt install python3 python3-pip

# 安装PostgreSQL客户端库
sudo apt install libpq-dev

# 安装psycopg2（推荐使用二进制包）
pip install psycopg2-binary

注意：生产环境建议使用psycopg2而非psycopg2-binary，后者是为方便开发测试预编译的版本。可以通过pip install psycopg2安装，但需要确保系统已安装PostgreSQL开发文件。

2.2 建立基础连接

创建一个名为pg_connect.py的文件，写入以下基础连接代码：

python复制import psycopg2
from psycopg2 import OperationalError

def create_connection(db_name, db_user, db_password, db_host, db_port):
    connection = None
    try:
        connection = psycopg2.connect(
            database=db_name,
            user=db_user,
            password=db_password,
            host=db_host,
            port=db_port,
        )
        print("PostgreSQL连接成功")
    except OperationalError as e:
        print(f"连接PostgreSQL时出错: '{e}'")
    return connection

# 使用示例
conn = create_connection(
    "your_dbname", "your_username", "your_password", "127.0.0.1", "5432"
)

这个基础连接函数处理了连接异常，在实际项目中可以作为数据库操作的起点。我习惯将连接参数放在环境变量中而非硬编码，这在团队协作和项目部署时更加安全方便。

3. 高级连接配置与最佳实践

3.1 连接池管理

在高并发应用中，频繁创建和关闭数据库连接会导致性能问题。psycopg2提供了连接池支持：

python复制from psycopg2 import pool

# 创建连接池
connection_pool = pool.SimpleConnectionPool(
    minconn=1,
    maxconn=10,
    database="your_dbname",
    user="your_username",
    password="your_password",
    host="127.0.0.1",
    port="5432"
)

# 从连接池获取连接
def get_connection():
    return connection_pool.getconn()

# 释放连接回池
def release_connection(connection):
    connection_pool.putconn(connection)

# 使用示例
conn = get_connection()
try:
    # 执行数据库操作
    pass
finally:
    release_connection(conn)

在Web应用中，我通常会将连接池初始化放在应用启动时，在整个应用生命周期内共享使用。连接池大小(maxconn)需要根据应用并发量和服务器配置进行调整，一般建议设置为CPU核心数的2-3倍。

3.2 SSL与SSH隧道连接

生产环境中，我们经常需要通过SSL或SSH隧道连接远程PostgreSQL服务器。以下是SSL连接的配置示例：

python复制conn = psycopg2.connect(
    database="your_dbname",
    user="your_username",
    password="your_password",
    host="db.example.com",
    port="5432",
    sslmode="verify-full",
    sslrootcert="/path/to/root.crt",
    sslcert="/path/to/client.crt",
    sslkey="/path/to/client.key"
)

对于需要通过跳板机访问的情况，可以先用SSH建立隧道：

bash复制# 先建立SSH隧道
ssh -L 63333:localhost:5432 user@jump_host -N

然后在Python中连接本地端口：

python复制conn = psycopg2.connect(
    database="your_dbname",
    user="your_username",
    password="your_password",
    host="127.0.0.1",
    port="63333"
)

4. 执行查询与结果处理

4.1 基础CRUD操作

让我们看一个完整的CRUD示例，包含创建表、插入、查询、更新和删除操作：

python复制def execute_query(connection, query, params=None):
    connection.autocommit = False
    cursor = connection.cursor()
    try:
        cursor.execute(query, params or ())
        connection.commit()
        return cursor
    except Exception as e:
        connection.rollback()
        raise e
    finally:
        cursor.close()

# 创建表
create_table_query = """
CREATE TABLE IF NOT EXISTS employees (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    salary NUMERIC(10, 2),
    join_date DATE DEFAULT CURRENT_DATE
)
"""
execute_query(conn, create_table_query)

# 插入数据
insert_query = """
INSERT INTO employees (name, email, salary)
VALUES (%s, %s, %s)
RETURNING id
"""
employee_data = ("张三", "zhangsan@example.com", 8500.50)
cursor = execute_query(conn, insert_query, employee_data)
employee_id = cursor.fetchone()[0]

# 查询数据
def fetch_data(connection, query, params=None):
    cursor = connection.cursor()
    cursor.execute(query, params or ())
    columns = [desc[0] for desc in cursor.description]
    return [dict(zip(columns, row)) for row in cursor.fetchall()]

employees = fetch_data(conn, "SELECT * FROM employees WHERE salary > %s", (8000,))

在实际项目中，我更喜欢使用上下文管理器来处理游标，这样可以确保游标正确关闭：

python复制from contextlib import contextmanager

@contextmanager
def get_cursor(connection):
    cursor = connection.cursor()
    try:
        yield cursor
    finally:
        cursor.close()

with get_cursor(conn) as cur:
    cur.execute("SELECT * FROM employees")
    for record in cur:
        print(record)

4.2 批量操作与性能优化

当需要处理大量数据时，逐条执行SQL语句效率极低。psycopg2提供了高效的批量操作方式：

python复制# 使用execute_values进行批量插入
from psycopg2.extras import execute_values

data = [
    ("李四", "lisi@example.com", 9200.00),
    ("王五", "wangwu@example.com", 7800.50),
    ("赵六", "zhaoliu@example.com", 10500.75)
]

with get_cursor(conn) as cur:
    execute_values(
        cur,
        "INSERT INTO employees (name, email, salary) VALUES %s",
        data,
        template="(%s, %s, %s)",
        page_size=100
    )

对于超大数据集（百万级以上），我通常采用以下优化策略：

使用COPY命令代替INSERT
分批提交（每1万条提交一次）
临时禁用索引和约束
增加work_mem等PostgreSQL参数

以下是使用COPY命令的示例：

python复制import io

# 准备内存文件
output = io.StringIO()
for emp in data:
    output.write(f"{emp[0]}\t{emp[1]}\t{emp[2]}\n")
output.seek(0)

with get_cursor(conn) as cur:
    cur.copy_from(
        output,
        "employees",
        columns=("name", "email", "salary"),
        null=""
    )

5. 事务管理与错误处理

5.1 事务控制模式

psycopg2提供了三种事务控制方式：

自动提交模式（autocommit）
```
python复制conn.autocommit = True
```

手动提交（推荐）

python复制try:
    cur.execute("...")
    conn.commit()
except:
    conn.rollback()

使用保存点（复杂事务）

python复制cur.execute("SAVEPOINT my_savepoint")
try:
    cur.execute("...")
except:
    cur.execute("ROLLBACK TO SAVEPOINT my_savepoint")

在金融类项目中，我通常会实现一个装饰器来处理事务：

python复制def with_transaction(func):
    def wrapper(conn, *args, **kwargs):
        conn.autocommit = False
        try:
            result = func(conn, *args, **kwargs)
            conn.commit()
            return result
        except Exception as e:
            conn.rollback()
            raise e
    return wrapper

@with_transaction
def transfer_funds(conn, from_acc, to_acc, amount):
    # 扣款
    cur = conn.cursor()
    cur.execute("UPDATE accounts SET balance = balance - %s WHERE id = %s", 
               (amount, from_acc))
    # 存款
    cur.execute("UPDATE accounts SET balance = balance + %s WHERE id = %s", 
               (amount, to_acc))

5.2 常见错误处理

PostgreSQL操作中常见的错误包括：

唯一约束冲突（UniqueViolation）
外键约束冲突（ForeignKeyViolation）
死锁（DeadlockDetected）
连接超时（OperationalError）

以下是一个健壮的错误处理示例：

python复制from psycopg2 import errors

try:
    cur.execute("INSERT INTO employees (email) VALUES (%s)", 
               ("exists@example.com",))
except errors.UniqueViolation:
    print("邮箱已存在")
except errors.ForeignKeyViolation as e:
    print(f"外键约束错误: {e}")
except errors.DeadlockDetected:
    print("死锁发生，请重试")
except psycopg2.OperationalError as e:
    print(f"数据库操作错误: {e}")
    # 检查连接是否中断，必要时重新连接
    if "connection" in str(e).lower():
        conn = create_connection(...)

在实际项目中，我通常会实现一个重试机制来处理临时性错误（如死锁、连接中断）：

python复制import time
from functools import wraps

def retry_on_db_error(max_retries=3, delay=1):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            retries = 0
            while retries < max_retries:
                try:
                    return func(*args, **kwargs)
                except (errors.DeadlockDetected, psycopg2.OperationalError) as e:
                    retries += 1
                    if retries == max_retries:
                        raise
                    time.sleep(delay * retries)
        return wrapper
    return decorator

6. 与Python生态集成

6.1 使用SQLAlchemy ORM

虽然psycopg2功能强大，但在大型项目中，使用ORM可以提高开发效率。SQLAlchemy是Python中最流行的ORM工具之一：

python复制from sqlalchemy import create_engine, Column, Integer, String, Numeric, Date
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

# 创建引擎
engine = create_engine("postgresql+psycopg2://user:password@localhost/dbname")

Base = declarative_base()

class Employee(Base):
    __tablename__ = "employees"
    
    id = Column(Integer, primary_key=True)
    name = Column(String(100), nullable=False)
    email = Column(String(100), unique=True, nullable=False)
    salary = Column(Numeric(10, 2))
    join_date = Column(Date, server_default="CURRENT_DATE")

# 创建表
Base.metadata.create_all(engine)

# 使用会话
Session = sessionmaker(bind=engine)
session = Session()

# 添加新员工
new_emp = Employee(name="钱七", email="qianqi@example.com", salary=9500.00)
session.add(new_emp)
session.commit()

# 查询
high_salary_emps = session.query(Employee).filter(Employee.salary > 8000).all()

在性能敏感的场景中，我通常会混合使用ORM和原始SQL，比如复杂报表查询直接使用SQL，而业务逻辑操作使用ORM。

6.2 与Pandas集成

对于数据分析任务，将PostgreSQL数据直接读入Pandas DataFrame非常方便：

python复制import pandas as pd

def query_to_dataframe(conn, query, params=None):
    return pd.read_sql_query(query, conn, params=params)

# 使用示例
df = query_to_dataframe(conn, "SELECT * FROM employees WHERE salary > %s", (8000,))
print(df.describe())

# 将DataFrame写回数据库
df_new = pd.DataFrame({
    "name": ["周八", "吴九"],
    "email": ["zhouba@example.com", "wujiu@example.com"],
    "salary": [8800.00, 10200.50]
})

df_new.to_sql(
    "employees",
    conn,
    if_exists="append",
    index=False,
    method="multi"  # 批量插入
)

在数据科学项目中，我经常使用这种工作流：从PostgreSQL读取数据 → 在Pandas中处理 → 结果写回数据库。对于大型数据集，可以使用chunksize参数分块读取：

python复制chunk_iter = pd.read_sql_query(
    "SELECT * FROM large_table",
    conn,
    chunksize=10000
)

for chunk in chunk_iter:
    process(chunk)  # 处理每个数据块

7. 性能监控与调试

7.1 连接与查询性能分析

在生产环境中监控数据库性能至关重要。psycopg2提供了一些有用的属性和方法：

python复制# 获取查询执行计划
with get_cursor(conn) as cur:
    cur.execute("EXPLAIN ANALYZE SELECT * FROM employees WHERE salary > 8000")
    plan = cur.fetchall()
    for line in plan:
        print(line[0])

# 监控连接状态
print(f"连接状态: {'已开启事务' if conn.get_transaction_status() else '空闲'}")
print(f"服务器版本: {conn.server_version}")
print(f"协议版本: {conn.protocol_version}")

# 查询耗时统计
import time

def timed_query(conn, query, params=None):
    start = time.perf_counter()
    cursor = conn.cursor()
    cursor.execute(query, params or ())
    elapsed = time.perf_counter() - start
    print(f"查询耗时: {elapsed:.4f}秒")
    return cursor

我习惯在项目中使用装饰器记录所有重要查询的执行时间，当发现慢查询时，可以使用PostgreSQL的pg_stat_statements扩展进一步分析。

7.2 使用连接中间件

对于大型应用，可以考虑使用连接中间件如PgBouncer。配置PgBouncer后，Python连接代码只需修改连接端口：

python复制conn = psycopg2.connect(
    database="your_dbname",
    user="your_username",
    password="your_password",
    host="127.0.0.1",
    port="6432"  # PgBouncer默认端口
)

在Kubernetes环境中部署时，我通常会使用连接池服务如CloudNativePG或PgBouncer sidecar容器来管理数据库连接。

8. 安全最佳实践

8.1 凭证管理

永远不要将数据库凭证硬编码在代码中。推荐的做法：

使用环境变量

python复制import os

conn = psycopg2.connect(
    database=os.getenv("DB_NAME"),
    user=os.getenv("DB_USER"),
    password=os.getenv("DB_PASSWORD"),
    host=os.getenv("DB_HOST"),
    port=os.getenv("DB_PORT")
)

使用配置文件（确保不提交到版本控制）

python复制import configparser

config = configparser.ConfigParser()
config.read("config.ini")

conn = psycopg2.connect(**config["postgresql"])

使用秘密管理服务（如AWS Secrets Manager、HashiCorp Vault）

8.2 SQL注入防护

psycopg2默认使用参数化查询，这是防止SQL注入的最佳方式：

python复制# 正确做法 - 使用参数化查询
cur.execute("SELECT * FROM users WHERE username = %s", (user_input,))

# 错误做法 - 字符串拼接（易受SQL注入攻击）
cur.execute(f"SELECT * FROM users WHERE username = '{user_input}'")

对于动态表名或列名等无法参数化的情况，可以使用psycopg2的sql模块安全地组合SQL：

python复制from psycopg2 import sql

table_name = "employees"
column_name = "salary"

query = sql.SQL("SELECT {} FROM {} WHERE {} > %s").format(
    sql.Identifier(column_name),
    sql.Identifier(table_name),
    sql.Identifier(column_name)
)

cur.execute(query, (8000,))

在代码审查时，我特别注意查找所有直接拼接SQL字符串的地方，确保团队遵循参数化查询的最佳实践。

9. 实际项目经验分享

在多年的项目实践中，我总结了以下经验教训：

连接泄漏排查：曾经在一个长时间运行的服务中遇到PostgreSQL连接数耗尽的问题。后来发现是因为异常路径中没有正确关闭连接。解决方案是使用上下文管理器确保连接总是被正确关闭：

python复制from contextlib import contextmanager

@contextmanager
def get_connection(dsn):
    conn = psycopg2.connect(dsn)
    try:
        yield conn
    finally:
        conn.close()

批量操作优化：处理百万级数据导入时，最初使用单条INSERT语句性能极差。后来改用COPY命令配合临时表，性能提升200倍以上：

python复制# 创建临时表
cur.execute("CREATE TEMP TABLE temp_import (LIKE employees INCLUDING DEFAULTS)")

# 使用COPY导入数据
with open("large_data.csv") as f:
    cur.copy_expert("COPY temp_import FROM STDIN WITH CSV HEADER", f)

# 将数据从临时表插入主表
cur.execute("""
    INSERT INTO employees
    SELECT * FROM temp_import
    ON CONFLICT (email) DO UPDATE SET
        name = EXCLUDED.name,
        salary = EXCLUDED.salary
""")

JSONB数据处理技巧：PostgreSQL的JSONB类型与Python字典完美配合：

python复制# 插入JSON数据
data = {"skills": ["Python", "PostgreSQL"], "level": "senior"}
cur.execute("INSERT INTO profiles (user_id, data) VALUES (%s, %s)", 
           (user_id, psycopg2.extras.Json(data)))

# 查询JSON字段
cur.execute("SELECT data->>'level' FROM profiles WHERE data @> %s", 
           (psycopg2.extras.Json({"skills": ["PostgreSQL"]}),))

连接超时处理：对于不稳定的网络环境，建议设置连接和查询超时：

python复制conn = psycopg2.connect(
    "...",
    connect_timeout=5,  # 连接超时5秒
    options="-c statement_timeout=30000"  # 查询超时30秒
)

连接健康检查：长时间空闲的连接可能会被服务器关闭，使用前应检查连接状态：

python复制def is_connection_usable(conn):
    try:
        with conn.cursor() as cur:
            cur.execute("SELECT 1")
            return True
    except:
        return False

10. 调试技巧与常见问题解决

10.1 连接问题排查

当遇到连接问题时，可以按照以下步骤排查：

检查网络连通性
```
bash复制telnet db_host 5432
```

验证凭据是否正确

bash复制psql -h db_host -U username -d dbname

检查PostgreSQL日志

bash复制tail -f /var/log/postgresql/postgresql-13-main.log

检查pg_hba.conf配置

bash复制cat /etc/postgresql/13/main/pg_hba.conf

10.2 常见错误解决方案

"psycopg2.OperationalError: could not connect to server"
- 检查PostgreSQL服务是否运行
- 检查防火墙设置
- 确认连接参数（主机、端口）是否正确

"psycopg2.OperationalError: server closed the connection unexpectedly"

可能是服务器端超时设置过短

解决方案：增加keepalives参数

python复制conn = psycopg2.connect(
    "...",
    keepalives=1,
    keepalives_idle=30,
    keepalives_interval=10,
    keepalives_count=5
)

"psycopg2.errors.InFailedSqlTransaction"
- 当前事务已失败，需要回滚
- 解决方案：
```
python复制conn.rollback()
```

"psycopg2.errors.UniqueViolation"

违反了唯一约束

解决方案：使用ON CONFLICT处理冲突

python复制cur.execute("""
    INSERT INTO employees (email, name)
    VALUES (%s, %s)
    ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name
""", ("exists@example.com", "New Name"))

10.3 性能问题诊断

当遇到查询性能问题时，可以使用以下方法诊断：

使用EXPLAIN ANALYZE分析查询计划

python复制cur.execute("EXPLAIN ANALYZE SELECT * FROM large_table WHERE condition")

检查索引使用情况

python复制cur.execute("""
    SELECT indexname, indexdef
    FROM pg_indexes
    WHERE tablename = 'employees'
""")

查看表统计信息

python复制cur.execute("""
    SELECT relname, n_live_tup, n_dead_tup, last_autovacuum
    FROM pg_stat_user_tables
    WHERE relname = 'employees'
""")

监控长时间运行的事务

python复制cur.execute("""
    SELECT pid, now() - xact_start AS duration, query
    FROM pg_stat_activity
    WHERE state = 'active' 
    AND now() - xact_start > interval '5 minutes'
""")

11. 项目结构建议

对于使用PostgreSQL的Python项目，我推荐以下目录结构：

code复制project_root/
│
├── config/
│   ├── __init__.py
│   ├── database.py       # 数据库连接配置
│   └── settings.py       # 应用设置
│
├── models/
│   ├── __init__.py
│   ├── base.py           # 基础模型类
│   └── employee.py       # 具体模型
│
├── repositories/
│   ├── __init__.py
│   └── employee_repo.py  # 数据库操作类
│
├── services/
│   ├── __init__.py
│   └── employee_service.py # 业务逻辑
│
├── scripts/
│   ├── __init__.py
│   └── db_migrate.py     # 数据库迁移脚本
│
└── tests/
    ├── __init__.py
    └── test_employees.py # 测试用例

在这种结构中，数据库连接通常在应用启动时初始化：

python复制# config/database.py
import psycopg2
from psycopg2 import pool

connection_pool = None

def init_db(app_config):
    global connection_pool
    connection_pool = pool.SimpleConnectionPool(
        minconn=1,
        maxconn=app_config.DB_POOL_SIZE,
        database=app_config.DB_NAME,
        user=app_config.DB_USER,
        password=app_config.DB_PASSWORD,
        host=app_config.DB_HOST,
        port=app_config.DB_PORT
    )

def get_db_connection():
    return connection_pool.getconn()

def release_db_connection(conn):
    connection_pool.putconn(conn)

模型层定义数据结构和验证逻辑：

python复制# models/employee.py
from dataclasses import dataclass
from datetime import date
from typing import Optional

@dataclass
class Employee:
    id: Optional[int] = None
    name: str = ""
    email: str = ""
    salary: float = 0.0
    join_date: date = date.today()
    
    def validate(self):
        if not self.name:
            raise ValueError("员工姓名不能为空")
        if "@" not in self.email:
            raise ValueError("邮箱格式不正确")

仓库层封装数据库操作：

python复制# repositories/employee_repo.py
from typing import List, Optional
from ..models.employee import Employee

class EmployeeRepository:
    def __init__(self, conn):
        self.conn = conn
    
    def save(self, employee: Employee) -> Employee:
        with self.conn.cursor() as cur:
            if employee.id is None:
                cur.execute("""
                    INSERT INTO employees (name, email, salary, join_date)
                    VALUES (%s, %s, %s, %s)
                    RETURNING id
                """, (employee.name, employee.email, employee.salary, employee.join_date))
                employee.id = cur.fetchone()[0]
            else:
                cur.execute("""
                    UPDATE employees 
                    SET name = %s, email = %s, salary = %s, join_date = %s
                    WHERE id = %s
                """, (employee.name, employee.email, employee.salary, employee.join_date, employee.id))
        return employee
    
    def find_by_id(self, id: int) -> Optional[Employee]:
        with self.conn.cursor() as cur:
            cur.execute("SELECT * FROM employees WHERE id = %s", (id,))
            row = cur.fetchone()
            if row:
                return Employee(id=row[0], name=row[1], email=row[2], 
                              salary=row[3], join_date=row[4])
            return None
    
    def find_all(self) -> List[Employee]:
        with self.conn.cursor() as cur:
            cur.execute("SELECT * FROM employees ORDER BY name")
            return [
                Employee(id=row[0], name=row[1], email=row[2], 
                        salary=row[3], join_date=row[4])
                for row in cur.fetchall()
            ]

这种分层架构使代码更易于维护和测试，特别是在大型项目中优势明显。

12. 测试策略

12.1 单元测试

对于数据库相关代码，我通常使用以下测试策略：

使用pytest作为测试框架
为每个测试用例创建独立的事务，测试后回滚
使用fixture管理测试数据

示例测试代码：

python复制# tests/test_employees.py
import pytest
from ..models.employee import Employee
from ..repositories.employee_repo import EmployeeRepository

@pytest.fixture
def repo(db_connection):
    return EmployeeRepository(db_connection)

@pytest.fixture
def sample_employee():
    return Employee(name="测试员工", email="test@example.com", salary=5000.00)

def test_save_and_retrieve_employee(repo, sample_employee):
    # 测试保存
    saved_emp = repo.save(sample_employee)
    assert saved_emp.id is not None
    
    # 测试查询
    retrieved_emp = repo.find_by_id(saved_emp.id)
    assert retrieved_emp.name == sample_employee.name
    assert retrieved_emp.email == sample_employee.email

12.2 集成测试

对于涉及多个组件的测试，可以使用测试容器启动真实的PostgreSQL实例：

python复制# conftest.py
import pytest
from docker import from_env
from docker.errors import DockerException

def pytest_addoption(parser):
    parser.addoption("--no-docker", action="store_true", help="跳过需要Docker的测试")

def pytest_configure(config):
    config.addinivalue_line("markers", "docker: 需要Docker环境的测试")

def pytest_runtest_setup(item):
    if "docker" in item.keywords and item.config.getoption("--no-docker"):
        pytest.skip("需要Docker环境 (使用--no-docker跳过)")

@pytest.fixture(scope="session")
def postgres_container():
    try:
        client = from_env()
        container = client.containers.run(
            "postgres:13",
            environment={
                "POSTGRES_PASSWORD": "test",
                "POSTGRES_USER": "test",
                "POSTGRES_DB": "test"
            },
            ports={"5432/tcp": None},
            detach=True,
            remove=True
        )
        
        # 等待PostgreSQL启动
        import time
        time.sleep(5)
        
        yield container
        
        container.stop()
    except DockerException:
        pytest.skip("Docker不可用")

@pytest.fixture
def test_db_connection(postgres_container):
    import psycopg2
    from psycopg2 import sql
    
    # 获取映射的端口
    port = postgres_container.attrs["NetworkSettings"]["Ports"]["5432/tcp"][0]["HostPort"]
    
    conn = psycopg2.connect(
        database="test",
        user="test",
        password="test",
        host="localhost",
        port=port
    )
    
    # 设置测试环境
    conn.autocommit = False
    with conn.cursor() as cur:
        cur.execute("CREATE TABLE IF NOT EXISTS employees (id SERIAL PRIMARY KEY, name TEXT, email TEXT)")
    
    yield conn
    
    conn.rollback()
    conn.close()

13. 部署注意事项

13.1 连接池配置

在生产环境中，连接池配置对应用性能至关重要。以下是一些建议：

Web框架集成：
- Flask: 使用flask_pg扩展或自定义teardown处理
- Django: 内置连接管理
- FastAPI: 使用依赖项或中间件管理

连接池大小：

python复制# 根据公式计算建议值
max_pool_size = (core_count * 2) + effective_spindle_count

连接验证：

python复制connection_pool = pool.ThreadedConnectionPool(
    minconn=5,
    maxconn=20,
    host="localhost",
    port="5432",
    database="mydb",
    user="user",
    password="pass",
    options="-c statement_timeout=30000",
    keepalives=1,
    keepalives_idle=30
)

13.2 Kubernetes部署

在Kubernetes环境中部署时，建议：

使用Readiness探针确保应用准备好接受请求

yaml复制readinessProbe:
  exec:
    command:
    - python
    - -c
    - "import psycopg2; conn = psycopg2.connect('dbname=test user=postgres'); conn.close()"
  initialDelaySeconds: 5
  periodSeconds: 10

使用ConfigMap管理连接配置

yaml复制apiVersion: v1
kind: ConfigMap
metadata:
  name: db-config
data:
  DB_HOST: "postgres-service"
  DB_PORT: "5432"
  DB_NAME: "appdb"
  DB_POOL_MIN: "5"
  DB_POOL_MAX: "20"

使用Secret管理凭证

yaml复制apiVersion: v1
kind: Secret
metadata:
  name: db-secret
type: Opaque
data:
  DB_USER: "cG9zdGdyZXM="  # base64编码
  DB_PASSWORD: "cGFzc3dvcmQ="

14. 性能优化进阶

14.1 连接池调优

对于高并发应用，连接池参数需要精心调优：

监控连接池使用情况：

python复制print(f"当前连接数: {connection_pool._used}")
print(f"空闲连接数: {connection_pool._rused}")

动态调整大小：

python复制if connection_pool._used / connection_pool.maxconn > 0.8:
    connection_pool.maxconn += 5

连接预热：

python复制# 应用启动时预先建立最小连接数
[connection_pool.getconn() for _ in range(connection_pool.minconn)]

14.2 查询优化技巧

使用服务器端游标处理大结果集：

python复制with conn.cursor(name="server_side_cursor") as cur:
    cur.itersize = 1000  # 每次获取1000条
    cur.execute("SELECT * FROM large_table")
    for row in cur:
        process(row)

使用PREPARE语句加速重复查询：

python复制with conn.cursor() as cur:
    cur.execute("PREPARE emp_plan AS SELECT * FROM employees WHERE id = $1")
    cur.execute("EXECUTE emp_plan (%s)", (employee_id,))

利用PostgreSQL的JIT编译：

python复制# 在会话级别启用JIT
with conn.cursor() as cur:
    cur.execute("SET jit = on")
    cur.execute("SET jit_above_cost = 100000")

15. 替代方案比较

虽然psycopg2是Python连接PostgreSQL的主流选择，但也有其他值得了解的库：

asyncpg (异步驱动)
- 优点：性能极高，原生支持async/await
- 缺点：API与DB-API不兼容
- 适用场景：高性能异步应用
SQLAlchemy (ORM + 核心)
- 优点：高级抽象，支持多种数据库
- 缺点：有一定学习曲线，性能开销
- 适用场景：需要数据库抽象的中大型应用
peewee (轻量ORM)
- 优点：简单易用，轻量级
- 缺点：功能相对有限
- 适用场景：小型项目或原型开发
records (基于SQL的简单封装)
- 优点：极简API，适合快速脚本
- 缺点：功能有限
- 适用场景：简单数据导出/导入脚本

在实际项目中，我通常会根据项目规模和团队经验做出选择：

小型脚本：直接使用psycopg2
Web应用：SQLAlchemy ORM + psycopg

Python连接PostgreSQL实战指南