SQLAlchemy 详细指南

1. 简介

SQLAlchemy 是 Python 中最强大、最成熟的对象关系映射(ORM)工具，由 Michael Bayer 于2005年创建。它提供了完整的SQL抽象层和ORM功能，使开发者能够用Python对象操作数据库，同时保留对原生SQL的访问能力。

2. 为什么选择 SQLAlchemy

2.1 与其他ORM框架对比

特性	SQLAlchemy	Django ORM	Peewee	SQLModel	Pony ORM
成熟度	★★★★★	★★★★★	★★★★☆	★★★☆☆	★★★☆☆
灵活性	★★★★★	★★★☆☆	★★★★☆	★★★★☆	★★★★☆
学习曲线	较陡	中等	平缓	平缓	平缓
数据库支持	全面	全面	主流	主流	主流
大型项目适用性	★★★★★	★★★★☆	★★★☆☆	★★★☆☆	★★☆☆☆
社区支持	★★★★★	★★★★★	★★★☆☆	★★★☆☆	★★☆☆☆

2.2 SQLAlchemy 的核心优势

1. 分层架构：提供Core和ORM两个独立但相互配合的层次
2. 数据库无关性：支持几乎所有主流关系型数据库
3. 灵活的模型设计：灵活定义表关系、继承等高级特性
4. Session管理：强大的事务和对象管理
5. 表达式语言：Python风格的SQL构建系统
6. 性能优化：延迟加载、即时查询编译等优化策略
7. 类型系统：丰富的类型处理和验证

3. 安装与配置

3.1 安装

pip install sqlalchemy

如需使用特定数据库：

# MySQL
pip install sqlalchemy mysqlclient

# PostgreSQL
pip install sqlalchemy psycopg2

# SQLite (内置于Python)

# Oracle
pip install sqlalchemy cx_oracle

3.2 基本配置

from sqlalchemy import create_engine, MetaData
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

# 创建引擎
# 格式：dialect+driver://username:password@host:port/database
engine = create_engine('postgresql://user:password@localhost/mydatabase', echo=True)

# 创建基类
Base = declarative_base()

# 创建会话工厂
Session = sessionmaker(bind=engine)

4. 核心概念

4.1 Engine

数据库连接的中心点，管理数据库连接池并处理与数据库的通信。

# 创建引擎时常用参数
engine = create_engine(
    'postgresql://user:password@localhost/mydatabase',
    echo=True,  # 启用SQL日志
    pool_size=5,  # 连接池大小
    max_overflow=10,  # 连接池最大溢出
    pool_timeout=30,  # 连接超时时间
    pool_recycle=3600  # 连接回收时间(秒)
)

4.2 MetaData

包含数据库模式信息的集合，记录表和列的定义。

metadata = MetaData()

4.3 Table 和 Column

定义数据库表结构。

from sqlalchemy import Table, Column, Integer, String, MetaData

metadata = MetaData()

users = Table('users', metadata,
    Column('id', Integer, primary_key=True),
    Column('name', String(50)),
    Column('email', String(120))
)

4.4 模型类 (ORM)

from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    
    id = Column(Integer, primary_key=True)
    name = Column(String(50), nullable=False)
    email = Column(String(120), unique=True)
    
    def __repr__(self):
        return f"<User(name='{self.name}', email='{self.email}')>"

4.5 会话 (Session)

管理对象的持久化和事务。

# 创建会话
session = Session()

# 使用会话
try:
    # 操作...
    session.commit()
except:
    session.rollback()
    raise
finally:
    session.close()

5. 常见用法

5.1 定义模型关系

一对多关系

from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.orm import relationship

class User(Base):
    __tablename__ = 'users'
    
    id = Column(Integer, primary_key=True)
    name = Column(String(50))
    posts = relationship("Post", back_populates="author")

class Post(Base):
    __tablename__ = 'posts'
    
    id = Column(Integer, primary_key=True)
    title = Column(String(100))
    content = Column(String)
    user_id = Column(Integer, ForeignKey('users.id'))
    author = relationship("User", back_populates="posts")

多对多关系

association_table = Table('post_tags', Base.metadata,
    Column('post_id', Integer, ForeignKey('posts.id')),
    Column('tag_id', Integer, ForeignKey('tags.id'))
)

class Post(Base):
    __tablename__ = 'posts'
    
    id = Column(Integer, primary_key=True)
    title = Column(String(100))
    tags = relationship("Tag", secondary=association_table, back_populates="posts")

class Tag(Base):
    __tablename__ = 'tags'
    
    id = Column(Integer, primary_key=True)
    name = Column(String(50), unique=True)
    posts = relationship("Post", secondary=association_table, back_populates="tags")

5.2 创建和修改数据

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

# 添加数据
user = User(name='Alice', email='alice@example.com')
session.add(user)
session.commit()

# 批量添加
users = [User(name='Bob', email='bob@example.com'),
         User(name='Charlie', email='charlie@example.com')]
session.add_all(users)
session.commit()

# 更新数据
user = session.query(User).filter_by(name='Alice').first()
user.email = 'alice.new@example.com'
session.commit()

5.3 查询数据

# 基本查询
user = session.query(User).filter_by(name='Alice').first()

# 条件查询
from sqlalchemy import and_, or_, not_

users = session.query(User).filter(
    and_(
        User.name.like('A%'),
        User.email.contains('example.com')
    )
).all()

# 排序
users = session.query(User).order_by(User.name.desc()).all()

# 分页
users = session.query(User).limit(10).offset(20).all()

# 连接查询
results = session.query(User, Post).join(Post).filter(Post.title == 'First Post').all()

# 聚合查询
from sqlalchemy import func
count = session.query(func.count(User.id)).scalar()

5.4 删除数据

# 删除记录
user = session.query(User).filter_by(name='Alice').first()
session.delete(user)
session.commit()

# 批量删除
session.query(User).filter(User.name.like('test%')).delete()
session.commit()

6. 高级特性

6.1 事务管理

# 显式事务
with session.begin():
    user1 = User(name='User1')
    user2 = User(name='User2')
    session.add_all([user1, user2])
    # 自动提交或回滚

# 嵌套事务
from sqlalchemy.orm import sessionmaker
from sqlalchemy import create_engine

engine = create_engine('postgresql://user:password@localhost/mydatabase')
Session = sessionmaker(bind=engine, future=True)

with Session.begin() as session:
    # 外层事务
    user = User(name='Main')
    session.add(user)
    
    with session.begin_nested():
        # 嵌套事务 (SAVEPOINT)
        nested_user = User(name='Nested')
        session.add(nested_user)
        # 如果发生异常，回滚到这个保存点，外层事务不受影响

6.2 反射和自动映射

# 反射现有数据库表
from sqlalchemy import MetaData, Table, create_engine

engine = create_engine('postgresql://user:password@localhost/mydatabase')
metadata = MetaData()
users = Table('users', metadata, autoload_with=engine)

# 自动映射
from sqlalchemy.ext.automap import automap_base

Base = automap_base()
Base.prepare(engine, reflect=True)

# 访问映射的类
User = Base.classes.users

6.3 混合属性

from sqlalchemy.ext.hybrid import hybrid_property, hybrid_method

class User(Base):
    __tablename__ = 'users'
    
    id = Column(Integer, primary_key=True)
    firstname = Column(String(50))
    lastname = Column(String(50))
    
    @hybrid_property
    def fullname(self):
        return self.firstname + ' ' + self.lastname
    
    @fullname.expression
    def fullname(cls):
        return cls.firstname + ' ' + cls.lastname

6.4 关联代理

from sqlalchemy.ext.associationproxy import association_proxy

class User(Base):
    __tablename__ = 'users'
    
    id = Column(Integer, primary_key=True)
    name = Column(String(50))
    addresses = relationship("Address", back_populates="user")
    
    # 直接访问地址的email
    address_emails = association_proxy('addresses', 'email')

class Address(Base):
    __tablename__ = 'addresses'
    
    id = Column(Integer, primary_key=True)
    email = Column(String(50))
    user_id = Column(Integer, ForeignKey('users.id'))
    user = relationship("User", back_populates="addresses")

7. 性能优化

7.1 查询优化

1. 选择性加载列：只加载需要的列

session.query(User.id, User.name).all()

1. 延迟加载：按需加载关联对象

# 定义关系时
posts = relationship("Post", lazy='dynamic')

1. 预加载：减少N+1查询问题

users = session.query(User).options(joinedload(User.posts)).all()

1. 查询缓存：重用相同查询

query = session.query(User).filter(User.active == True)
active_users = query.all()
count = query.count()  # 重用相同查询

7.2 会话管理

1. 使用上下文管理器：确保资源释放

with Session() as session:
    users = session.query(User).all()
    # 自动关闭session

1. 批量操作：减少数据库交互

# 批量插入
session.bulk_save_objects([User(name=f'user{i}') for i in range(1000)])
session.commit()

1. 合理使用刷新：控制对数据库的写入频率

# 添加多条记录但只在最后提交
for i in range(1000):
    session.add(User(name=f'user{i}'))
    if i % 100 == 0:
        session.flush()  # 周期性刷新
session.commit()  # 最后提交

8. 常见问题与注意事项

8.1 会话管理陷阱

1. 未关闭会话：导致连接泄漏

# 错误方式
session = Session()
user = session.query(User).first()
# 忘记关闭session

# 正确方式
with Session() as session:
    user = session.query(User).first()

1. 分离对象：跨会话使用对象

# 错误方式
session1 = Session()
user = session1.query(User).first()
session1.close()

session2 = Session()
user.name = 'New Name'  # 对象已分离，无法更新
session2.commit()

# 正确方式
session1 = Session()
user = session1.query(User).first()
user_id = user.id
session1.close()

session2 = Session()
user = session2.query(User).get(user_id)
user.name = 'New Name'  # 使用会话2中的对象
session2.commit()

8.2 N+1 查询问题

# 问题代码
users = session.query(User).all()
for user in users:
    print(user.posts)  # 每个用户都会触发一次额外查询

# 解决方案
users = session.query(User).options(joinedload(User.posts)).all()
for user in users:
    print(user.posts)  # 无额外查询

8.3 连接池配置

engine = create_engine(
    'postgresql://user:password@localhost/mydatabase',
    pool_size=10,  # 连接池中维护的连接数
    max_overflow=20,  # 允许超出pool_size的连接数
    pool_timeout=30,  # 等待连接的秒数
    pool_recycle=3600,  # 回收连接的秒数(防止连接失效)
    pool_pre_ping=True  # 使用前测试连接是否有效
)

8.4 模型定义最佳实践

1. 使用明确的类型：不要依赖默认类型
2. 设置nullable=False：对必填字段
3. 使用适当的索引：优化查询
4. 设置级联删除：处理关联对象

class User(Base):
    __tablename__ = 'users'
    
    id = Column(Integer, primary_key=True)
    name = Column(String(50), nullable=False, index=True)
    created_at = Column(DateTime, default=datetime.utcnow)
    
    # 级联删除
    posts = relationship("Post", cascade="all, delete-orphan")

9. 迁移管理

SQLAlchemy本身不提供迁移工具，但可与Alembic搭配使用：

# 安装Alembic
pip install alembic

# 初始化Alembic
alembic init migrations

# 创建迁移脚本
alembic revision --autogenerate -m "Initial migration"

# 运行迁移
alembic upgrade head

10. 总结

SQLAlchemy是一个功能丰富、灵活且强大的ORM框架，适合各种规模的项目。它的核心优势在于：

1. 提供了从低级SQL到高级ORM的全方位支持
2. 灵活的模型定义和关系映射
3. 强大的查询构建系统
4. 完善的事务和会话管理
5. 广泛的数据库支持
6. 成熟的社区和文档

虽然学习曲线较陡，但投入时间学习将获得长期回报，尤其是在复杂项目中。合理使用SQLAlchemy的各项功能，可以构建出高效、安全且易维护的数据访问层。