下面我将为你提供一个从安装到完整使用示例的详细指南。

第1步：安装 psycopg2 库

你需要安装 psycopg2 库，你可以使用 pip 来安装。

打开你的终端或命令行工具,运行以下命令：

pip install psycopg2-binary

注意：

• psycopg2 vs psycopg2-binary：psycopg2-binary 是一个预编译的版本，非常适合开发和测试，因为它包含了所有需要的依赖，在生产环境中，你可能需要从源代码编译 psycopg2 以获得更好的性能和灵活性，但对于初学者来说，psycopg2-binary 是最简单、最直接的选择。
• 如果遇到问题：在某些系统上（特别是 Windows），你可能需要先安装一个 C 编译器和 PostgreSQL 的开发库，如果安装失败，请查阅 psycopg2 的官方文档或搜索相关解决方案。

第2步：获取数据库连接信息

在连接数据库之前，你需要从你的 PostgreSQL 服务器管理员或服务提供商那里获取以下信息：

1. 主机名：数据库服务器的地址，localhost（本地）或 db.example.com（远程）。
2. 端口：PostgreSQL 的默认端口是 5432。
3. 数据库名称：你要连接的具体数据库的名称。
4. 用户名：用于认证的用户名。
5. 密码：该用户的密码。

第3步：编写 Python 代码连接数据库

下面是一个完整的 Python 脚本示例，展示了如何连接到 PostgreSQL 数据库，执行一个简单的查询,并处理结果。

示例代码：connect_postgres.py

import psycopg2
import os
# --- 1. 定义数据库连接信息 ---
# 建议将敏感信息（如密码）存储在环境变量中，而不是硬编码在脚本里
DB_HOST = os.getenv("DB_HOST", "localhost")
DB_PORT = os.getenv("DB_PORT", "5432")
DB_NAME = os.getenv("DB_NAME", "testdb")
DB_USER = os.getenv("DB_USER", "postgres")
DB_PASSWORD = os.getenv("DB_PASSWORD", "your_password")
# --- 2. 建立连接 ---
try:
    # 使用 connect() 函数建立连接
    # 它会返回一个 connection 对象
    conn = psycopg2.connect(
        host=DB_HOST,
        port=DB_PORT,
        dbname=DB_NAME,
        user=DB_USER,
        password=DB_PASSWORD
    )
    print("成功连接到 PostgreSQL 数据库！")
    # --- 3. 创建一个游标对象 ---
    # 游标用于执行 SQL 查询并获取结果
    cur = conn.cursor()
    # --- 4. 执行 SQL 查询 ---
    # 示例：查询 'employees' 表中的前5条记录
    # 假设表结构为: id (SERIAL), name (VARCHAR), department (VARCHAR)
    cur.execute("SELECT id, name, department FROM employees LIMIT 5;")
    # --- 5. 获取查询结果 ---
    # fetchone() 获取下一行结果
    # fetchmany(size) 获取指定数量的结果
    # fetchall() 获取所有剩余结果
    print("\n查询结果:")
    for row in cur:
        # row 是一个元组，(1, 'Alice', 'Engineering')
        print(f"ID: {row[0]}, Name: {row[1]}, Department: {row[2]}")
    # --- 6. 执行插入操作 (示例) ---
    print("\n--- 执行插入操作 ---")
    insert_query = "INSERT INTO employees (name, department) VALUES (%s, %s);"
    # 注意：使用 %s 作为占位符，这是防止 SQL 注入的安全方式
    # 不要使用 f-string 或 % 格式化来直接插入变量值，
    # cur.execute(f"INSERT INTO ... VALUES ('{name}', '{department}');") # 危险！
    new_employee = ("Bob", "Marketing")
    cur.execute(insert_query, new_employee)
    # --- 7. 提交事务 ---
    # 在 PostgreSQL 中，DML 操作（如 INSERT, UPDATE, DELETE）需要显式提交
    conn.commit()
    print(f"成功插入新员工: {new_employee[0]}")
    # --- 8. 关闭游标和连接 ---
    # 好习惯是先关闭游标，再关闭连接
    cur.close()
    conn.close()
    print("\n数据库连接已关闭。")
except psycopg2.Error as e:
    # --- 9. 处理异常 ---
    print(f"数据库错误: {e}")
    # 如果发生错误，回滚事务（撤销未提交的更改）
    if 'conn' in locals() and conn is not None:
        conn.rollback()

第4步：使用上下文管理器（推荐的最佳实践）

手动管理游标和连接的关闭 (cur.close(), conn.close()) 很容易出错，尤其是在发生异常时。psycopg2 提供了上下文管理器（with 语句）来自动处理这些资源，这是更安全、更推荐的做法。

使用上下文管理器的代码示例：

import psycopg2
import os
# 数据库连接信息（同上）
DB_HOST = "localhost"
DB_NAME = "testdb"
DB_USER = "postgres"
DB_PASSWORD = "your_password"
# 使用 with 语句管理连接
try:
    with psycopg2.connect(
        host=DB_HOST,
        dbname=DB_NAME,
        user=DB_USER,
        password=DB_PASSWORD
    ) as conn:
        print("成功连接到 PostgreSQL 数据库！")
        # 使用 with 语句管理游标
        with conn.cursor() as cur:
            # 执行查询
            cur.execute("SELECT id, name, department FROM employees LIMIT 5;")
            print("\n查询结果:")
            for row in cur:
                print(f"ID: {row[0]}, Name: {row[1]}, Department: {row[2]}")
            # 执行插入
            insert_query = "INSERT INTO employees (name, department) VALUES (%s, %s);"
            new_employee = ("Charlie", "Sales")
            cur.execute(insert_query, new_employee)
            # 提交事务
            conn.commit()
            print(f"成功插入新员工: {new_employee[0]}")
        # 当 with 块执行完毕后，游标会自动关闭
    # 当 with 块执行完毕后，连接会自动关闭
    print("\n数据库连接已自动关闭。")
except psycopg2.Error as e:
    print(f"数据库错误: {e}")
    # conn 对象存在且发生错误，上下文管理器会自动执行回滚

第5步：使用 ORM (对象关系映射) - 更高级的选择

对于大型项目，直接写 SQL 语句可能会变得繁琐且难以维护，这时可以使用 ORM（如 SQLAlchemy）来让你用 Python 类和对象来操作数据库，ORM 会自动将它们转换为 SQL。

使用 SQLAlchemy 的简单示例

首先安装 SQLAlchemy： pip install SQLAlchemy

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import sessionmaker
from sqlalchemy.ext.declarative import declarative_base
# 1. 定义数据库连接 URL
# 格式: postgresql+psycopg2://用户名:密码@主机:端口/数据库名
DATABASE_URL = "postgresql+psycopg2://postgres:your_password@localhost/testdb"
# 2. 创建引擎
engine = create_engine(DATABASE_URL)
# 3. 创建会话工厂
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
# 4. 声明基类
Base = declarative_base()
# 5. 定义模型 (Python 类映射到数据库表)
class Employee(Base):
    __tablename__ = 'employees'  # 表名
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String)
    department = Column(String)
# 6. 创建表 (如果不存在)
Base.metadata.create_all(bind=engine)
# 7. 使用会话进行操作
try:
    db = SessionLocal()
    print("成功通过 SQLAlchemy 连接数据库！")
    # 创建新员工
    new_employee = Employee(name="David", department="HR")
    db.add(new_employee)
    db.commit()  # 提交事务
    print(f"成功通过 ORM 插入新员工: {new_employee.name}")
    # 查询员工
    employees = db.query(Employee).filter(Employee.department == "HR").all()
    print("\nHR 部门的员工:")
    for emp in employees:
        print(f"- ID: {emp.id}, Name: {emp.name}")
except Exception as e:
    print(f"错误: {e}")
    db.rollback() # 回滚
finally:
    db.close() # 关闭会话
    print("\n数据库会话已关闭。")

对于初学者，强烈建议从 psycopg2 开始，因为它能帮助你直接理解数据库操作，当你对数据库交互有了更深的理解后，再根据项目需求考虑是否使用 SQLAlchemy 等 ORM 工具。