从零开始学习SQLAlchemy：Python ORM入门指南 – wiki基地

作者： /

从零开始学习SQLAlchemy：Python ORM入门指南

欢迎来到数据持久化的世界！在构建大多数现代应用程序时，与数据库的交互是不可或缺的一环。作为Python开发者，我们有多种方式来与数据库打交道，其中一种强大且优雅的选择就是使用对象关系映射（ORM）工具。而 SQLAlchemy，无疑是Python生态系统中最成熟、最灵活、功能最强大的ORM框架之一。

本篇文章旨在成为你从零开始学习SQLAlchemy的入门指南。我们将从最基础的概念出发，逐步深入，直到你能够使用SQLAlchemy进行基本的数据库操作。无论你之前是否接触过ORM，亦或是只写过原生SQL，这篇文章都将为你铺平通往SQLAlchemy世界道路。

为什么选择SQLAlchemy？为什么使用ORM？

在直接跳进SQLAlchemy的语法之前，我们先来理解为什么需要它，以及ORM解决了什么问题。

传统的数据库操作通常涉及编写原生SQL语句（例如 SELECT * FROM users WHERE id = 1，INSERT INTO products (name, price) VALUES ('Book', 20.0)）。这种方式直接、灵活，但随着项目规模的扩大和复杂度的增加，会带来一些挑战：

  1. 代码重复和繁琐： 大量的SQL语句充斥在代码中，且通常需要手动处理数据类型转换（从数据库类型到Python类型，反之亦然）。
  2. 可维护性差： SQL语句作为字符串嵌入在代码中，修改起来不够直观，也没有编译时检查。当数据库 schema 发生变化时，可能需要在代码中多处修改相关的SQL语句。
  3. 数据库兼容性： 不同数据库系统（MySQL, PostgreSQL, SQLite, Oracle等）的SQL语法、函数、数据类型可能存在差异。如果需要切换数据库，大量SQL代码可能需要重写。
  4. 对象与关系的不匹配： 应用程序是面向对象的，而数据库是面向关系的（表格）。ORM需要解决的就是这种“阻抗失配”（impedance mismatch），让你可以用操作Python对象的方式来操作数据库中的数据。

ORM（Object-Relational Mapping）工具正是为了解决这些问题而诞生的。它在你的应用程序代码和数据库之间建立了一层抽象，允许你使用面向对象的方式来定义、操作和查询数据库中的数据。

SQLAlchemy作为Python的ORM库，提供了以下主要优势：

  • 强大的抽象能力： 将数据库表格映射为Python类，将表格中的行映射为Python对象，将列映射为对象属性。
  • 数据库无关性： 支持多种数据库后端，通过配置连接字符串即可轻松切换数据库，无需修改大部分代码。
  • 灵活性： SQLAlchemy不仅仅是一个ORM，它还提供了强大的SQL表达式语言，允许你在需要时编写更接近原生的、灵活的SQL，而不仅仅局限于ORM的映射方式。这使得它既适合快速开发，也能应对复杂的查询需求。
  • 高性能： SQLAlchemy在设计时考虑了性能，提供了连接池、缓存等优化机制。
  • 成熟稳定： SQLAlchemy是一个经过多年发展、被广泛应用于生产环境的库，社区活跃，文档详尽。

总而言之，使用SQLAlchemy这样的ORM，可以提高开发效率、降低维护成本、增强代码的可读性和可移植性。

前期准备：安装与基础概念

开始之前，你需要确保已经安装了Python。然后，安装SQLAlchemy。通过pip是推荐的方式：

bash
pip install sqlalchemy

SQLAlchemy支持多种数据库后端。如果你想连接特定类型的数据库（如MySQL, PostgreSQL），还需要安装对应的数据库驱动：

  • MySQL: pip install pymysql 或 pip install mysql-connector-python
  • PostgreSQL: pip install psycopg2
  • SQLite: Python标准库自带，无需额外安装驱动。

为了简化入门过程，我们将使用SQLite数据库，因为它无需安装额外的服务器，数据可以存储在一个文件中，甚至直接在内存中。

在我们深入代码之前，了解SQLAlchemy的几个核心概念至关重要的：

  1. Engine（引擎）： 这是SQLAlchemy与数据库连接的起点。它负责管理数据库连接池和方言（Dialect，用于处理不同数据库的语法差异）。通过create_engine()函数创建。
  2. Metadata（元数据）： 这是一个容器，用于存储数据库 schema 的信息，比如有哪些表格、每个表格有哪些列等。通常通过MetaData对象来表示。
  3. Table（表格）： 表示数据库中的一个表格。它定义了表格的名称、列以及约束等信息。
  4. Column（列）： 表示表格中的一个列，定义了列名、数据类型、是否为主键、是否允许为空等属性。
  5. Declarative Base（声明式基类）： 这是SQLAlchemy ORM中常用的一种模型定义方式。通过继承一个声明式基类，你可以用Python类的属性来定义数据库表的列，并且类实例就代表表中的一行数据。这是将Python对象映射到数据库行的核心机制。
  6. Session（会话）： 这是你与数据库进行交互的主要接口。Session是一个“工作单元”（Unit of Work），它跟踪你对对象的修改，并负责将这些修改同步到数据库（通过提交 – commit）或撤销（通过回滚 – rollback）。查询操作也是通过Session进行的。

我们将主要使用声明式模型（Declarative）来讲解ORM部分，因为这是现代SQLAlchemy ORM开发中最常见和推荐的方式。

搭建第一个SQLAlchemy应用：连接数据库与定义模型

让我们从创建一个简单的数据库应用开始。我们将定义一个表示“用户”的表格。

首先，导入必要的模块并创建数据库引擎。我们将使用一个内存中的SQLite数据库，这意味着数据只存在于程序运行期间，程序结束后数据就会丢失。对于学习来说，这非常方便。

“`python
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

1. 创建数据库引擎

参数是数据库连接字符串：

‘sqlite:///:memory:’ 表示内存中的SQLite数据库

‘sqlite:///mydatabase.db’ 表示文件中的SQLite数据库

其他数据库如 MySQL: ‘mysql+pymysql://user:password@host/database’

engine = create_engine(‘sqlite:///:memory:’)
print(“数据库引擎创建成功！”)

2. 创建声明式基类

这个基类将作为我们所有ORM模型的父类

Base = declarative_base()
print(“声明式基类创建成功！”)

3. 定义ORM模型（映射到数据库表格的Python类）

class User(Base):
# 指定映射到哪个表格
tablename = ‘users’

# 定义表格的列，映射为类的属性
id = Column(Integer, primary_key=True) # 主键，整型
name = Column(String) # 字符串类型
age = Column(Integer) # 整型

# 可选：定义一个友好的 __repr__ 方法，方便打印对象信息
def __repr__(self):
    return f"<User(id={self.id}, name='{self.name}', age={self.age})>"

print(“User模型定义成功！”)

4. 根据模型创建数据库表格

Base.metadata 包含了所有继承自Base的模型的元数据信息

create_all 方法会检查数据库中是否存在对应的表格，如果不存在则创建

Base.metadata.create_all(engine)
print(“数据库表格创建完成！”)

5. 创建一个Session工厂

sessionmaker 用于创建一个 Session 类

bind 参数指定了 Session 要绑定到哪个数据库引擎

SessionLocal = sessionmaker(bind=engine)
print(“Session工厂创建成功！”)

现在我们有了：

– 一个连接到数据库的引擎 (engine)

– 一个定义数据库模型的基础类 (Base)

– 一个定义了 users 表格的 User 类

– 一个可以创建 Session 实例的工厂 (SessionLocal)

“`

在这个例子中：

  • 我们使用 create_engine 创建了与数据库的连接。
  • declarative_base() 创建了所有ORM模型类都将继承的基类 Base。
  • 我们定义了一个 User 类，它继承自 Base。__tablename__ 属性指定了这个类映射到数据库中的哪个表格。类的属性 id, name, age 通过 Column 定义，分别对应表格的列。
  • Base.metadata.create_all(engine) 根据所有继承自 Base 的模型定义，在数据库中创建相应的表格。
  • sessionmaker(bind=engine) 创建了一个用于生成 Session 实例的工厂 SessionLocal。

至此，我们已经成功连接了数据库（虽然是内存中的），并定义了一个可以映射到数据库表格的Python类。接下来，我们将学习如何使用 Session 来进行实际的数据操作。

使用 Session 进行基本 CRUD 操作

Session 是与数据库进行交互的核心。通过 Session，我们可以添加新的数据、查询现有数据、修改数据以及删除数据。

首先，我们需要从 Session 工厂创建一个 Session 实例：

“`python
session = SessionLocal()
print(“Session实例创建成功！”)

try:
# — C (Create): 添加新数据 —
# 创建 User 对象
new_user = User(name=’Alice’, age=30)
another_user = User(name=’Bob’, age=25)

# 将对象添加到 Session 中
# add 方法会将对象标记为待插入状态
session.add(new_user)
session.add(another_user)

# 也可以使用 add_all 方法添加多个对象
# session.add_all([new_user, another_user])

print(f"已将用户 {new_user.name} 和 {another_user.name} 添加到 Session")

# 提交事务
# commit 方法会将 Session 中待处理的变更（添加、修改、删除）同步到数据库
session.commit()
print("Session 提交成功，数据已写入数据库！")

# 提交后，对象的 id 属性通常会被数据库填充（如果设置了自增主键）
print(f"新用户 Alice 的 ID: {new_user.id}")
print(f"新用户 Bob 的 ID: {another_user.id}")

# --- R (Read): 查询数据 ---
print("\n--- 查询数据 ---")

# 查询所有用户
users = session.query(User).all()
print("所有用户:")
for user in users:
    print(user)

# 按条件查询 (过滤)
# filter 方法接收布尔表达式
# 使用 .first() 获取第一个匹配的对象
user_alice = session.query(User).filter(User.name == 'Alice').first()
print(f"查询名字为 Alice 的用户: {user_alice}")

# 使用 .all() 获取所有匹配的对象
users_older_than_28 = session.query(User).filter(User.age > 28).all()
print("查询年龄大于 28 的用户:")
for user in users_older_than_28:
    print(user)

# 使用 filter_by 方法，更简洁的等值查询
user_bob = session.query(User).filter_by(name='Bob').first()
print(f"使用 filter_by 查询名字为 Bob 的用户: {user_bob}")

# 使用 .get() 根据主键查询 (最高效的方式，如果对象已加载在 Session 中会直接返回)
# 注意：如果主键不存在，get 返回 None
user_by_id = session.query(User).get(new_user.id) # 假设 new_user.id 是 Alice 的 ID
print(f"根据 ID {new_user.id} 查询用户: {user_by_id}")

# 结合多种过滤条件
# 使用 and_ 或 & 操作符 (需要导入 from sqlalchemy import and_)
# 使用 or_ 或 | 操作符 (需要导入 from sqlalchemy import or_)
from sqlalchemy import and_
alice_under_35 = session.query(User).filter(and_(User.name == 'Alice', User.age < 35)).first()
print(f"查询名字是 Alice 且年龄小于 35 的用户: {alice_under_35}")

# --- U (Update): 修改数据 ---
print("\n--- 修改数据 ---")
# 获取要修改的对象（通常通过查询获得）
user_to_update = session.query(User).filter_by(name='Alice').first()

if user_to_update:
    print(f"修改前: {user_to_update}")
    # 直接修改对象的属性
    user_to_update.age = 31
    print(f"修改后: {user_to_update}")
    # Session 会跟踪这个修改

    # 提交变更到数据库
    session.commit()
    print("用户 Alice 的年龄已更新！")
else:
    print("未找到用户 Alice 进行更新。")


# --- D (Delete): 删除数据 ---
print("\n--- 删除数据 ---")
# 获取要删除的对象
user_to_delete = session.query(User).filter_by(name='Bob').first()

if user_to_delete:
    print(f"准备删除用户: {user_to_delete}")
    # 将对象标记为待删除状态
    session.delete(user_to_delete)
    print("用户 Bob 已标记为待删除")

    # 提交变更
    session.commit()
    print("用户 Bob 已从数据库删除！")

    # 再次查询所有用户，验证删除是否成功
    remaining_users = session.query(User).all()
    print("删除后剩余用户:")
    for user in remaining_users:
        print(user)
else:
    print("未找到用户 Bob 进行删除。")

except Exception as e:
# 如果发生异常，回滚事务
session.rollback()
print(f”发生错误，已回滚事务: {e}”)

finally:
# 关闭 Session
# 无论是否发生异常，都应该关闭 Session 来释放连接等资源
session.close()
print(“\nSession 已关闭。”)

此时，由于使用的是内存数据库，程序结束后所有数据都会丢失。

“`

上面的代码演示了基本的 CRUD 操作：

  • Create: 创建 User 类的实例，然后使用 session.add() 方法将其添加到 Session 中。session.commit() 将这些新行插入到数据库。
  • Read: 使用 session.query(User) 创建一个查询对象。.all() 获取所有结果，.first() 获取第一个结果，.filter() 添加过滤条件，.filter_by() 添加简单的等值过滤条件，.get() 根据主键查询。
  • Update: 先查询到需要修改的对象，然后直接修改对象的属性。Session 会自动检测到这些修改。session.commit() 将修改同步到数据库。
  • Delete: 查询到需要删除的对象，然后使用 session.delete() 方法将其添加到 Session 的删除列表中。session.commit() 执行删除操作。

事务管理： 注意 session.commit() 和 session.rollback() 的重要性。Session 对象代表一个数据库事务。add, delete, 修改属性等操作只是在 Session 中进行的“暂存”操作，它们还没有真正影响数据库。只有调用 commit() 时，所有在当前 Session 中暂存的修改才会被作为一个原子操作（要么全部成功，要么全部失败）发送到数据库。如果在 commit() 之前发生错误，或者你主动调用 rollback()，Session 中的所有暂存修改都会被撤销，数据库保持修改前的状态。在实际应用中，通常会将一组相关的数据库操作放在一个事务中，并在操作完成后调用 commit()，如果过程中出现问题则调用 rollback()。使用 try...except...finally 块并确保在 finally 中关闭 Session 是一个好的实践。

Session 的生命周期： 一个 Session 对象不应该长时间存活。通常，为每个请求（在Web应用中）或每个独立的工作单元创建一个新的 Session 是推荐的做法。完成操作后，应该及时关闭 Session 以释放资源。

进阶概念：关系（Relationships）

实际的数据库通常包含多个表格，并且这些表格之间存在关系（例如，一个用户可以有多篇文章，一篇文章属于一个用户；一个订单包含多个商品）。ORM的一个强大功能就是能够优雅地处理这些关系。

SQLAlchemy 支持三种主要的关系类型：

  • One-to-Many (一对多): 一个对象关联多个其他对象（例如，一个用户 -> 多篇文章）。这是最常见的关系类型。
  • Many-to-One (多对一): 这是 One-to-Many 的反向关系（例如，多篇文章 -> 一个用户）。在数据库层面，通常通过在外键（Foreign Key）列实现。
  • Many-to-Many (多对多): 多个对象关联多个其他对象（例如，多个学生 -> 多门课程，多门课程 -> 多个学生）。通常需要一个中间的关联表来实现。

让我们以 One-to-Many 关系为例，扩展上面的用户模型，添加一个“文章”模型。一个用户可以写多篇文章，一篇文章属于一个用户。

“`python
from sqlalchemy import create_engine, Column, Integer, String, ForeignKey
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, relationship # 导入 relationship 函数

重新定义 Base，以确保包含新的 Article 模型

Base = declarative_base()

定义 User 模型（与之前类似）

class User(Base):
tablename = ‘users’

id = Column(Integer, primary_key=True)
name = Column(String)
age = Column(Integer)

# 定义与 Article 模型的一对多关系
# 'articles' 是在 User 对象上访问相关 Article 对象的属性名
# Article 是关系的目标模型类名
# backref='author' 在 Article 模型上创建了一个反向属性 'author'，通过它可以在 Article 对象上访问关联的 User 对象
articles = relationship("Article", backref="author")

def __repr__(self):
    return f"<User(id={self.id}, name='{self.name}', age={self.age})>"

定义 Article 模型

class Article(Base):
tablename = ‘articles’

id = Column(Integer, primary_key=True)
title = Column(String, nullable=False) # 文章标题，不允许为空
content = Column(String) # 文章内容

# 定义外键列，建立与 users 表的关联
# user_id 列存储了关联用户的 id
# ForeignKey('users.id') 指明这是一个外键，引用 users 表的 id 列
user_id = Column(Integer, ForeignKey('users.id'))

# 'author' 是 backref 在 User 模型上创建的反向属性名，这里不需要再次定义 relationship

def __repr__(self):
    return f"<Article(id={self.id}, title='{self.title}', user_id={self.user_id})>"

创建新的引擎（或使用之前的内存引擎）

engine = create_engine(‘sqlite:///:memory:’)

根据新的模型定义创建表格

此时 Base.metadata 包含了 User 和 Article 两个模型的元数据

Base.metadata.create_all(engine)
print(“User 和 Article 数据库表格创建完成！”)

创建 Session 工厂

SessionLocal = sessionmaker(bind=engine)

使用 Session 进行操作

session = SessionLocal()

try:
# 创建用户和文章
user1 = User(name=’Alice’, age=30)
user2 = User(name=’Bob’, age=25)

article1 = Article(title='First Post by Alice', content='...')
article2 = Article(title='Second Post by Alice', content='...')
article3 = Article(title='Post by Bob', content='...')

# 建立关系：将文章关联到用户
# 方法1: 直接设置外键属性 (user_id)
# article1.user_id = user1.id # 注意：如果 user1 还没 commit，id可能是None

# 方法2: 通过 relationship 属性添加对象 (推荐方式)
# 将 Article 对象添加到 User 对象的 articles 列表中
user1.articles.append(article1)
user1.articles.append(article2)
user2.articles.append(article3)

# 添加用户到 Session (文章也会被级联添加，因为它们是关系对象)
session.add(user1)
session.add(user2)

# 或者单独添加所有对象
# session.add_all([user1, user2, article1, article2, article3])

session.commit()
print("\n用户和文章数据添加完成！")

# --- 通过关系进行查询 ---
print("\n--- 通过关系查询 ---")

# 查询 Alice，然后访问她的文章
alice = session.query(User).filter_by(name='Alice').first()
if alice:
    print(f"用户 {alice.name} 的文章:")
    # 通过 user.articles 属性访问关联的文章列表
    for article in alice.articles:
        print(f"- {article.title}")

# 查询某篇文章，然后访问其作者 (使用 backref 定义的属性)
first_article = session.query(Article).filter_by(title='First Post by Alice').first()
if first_article:
     # 通过 article.author 属性访问关联的用户对象
    print(f"文章 '{first_article.title}' 的作者是: {first_article.author.name}")

# 查询写了至少一篇文章的用户
# join User 表和 Article 表，然后去重
users_with_articles = session.query(User).join(Article).distinct().all()
print("\n写过文章的用户:")
for user in users_with_articles:
    print(user.name)

except Exception as e:
session.rollback()
print(f”发生错误，已回滚事务: {e}”)

finally:
session.close()
print(“\nSession 已关闭。”)

“`

在上面的例子中：

  • 我们在 Article 模型中添加了一个 user_id 列，并将其定义为 ForeignKey('users.id')，这在数据库层面建立了外键约束。
  • 在 User 模型中，我们使用 relationship("Article", backref="author") 定义了一个 articles 属性。这告诉 SQLAlchemy：当你在 User 对象上访问 articles 属性时，你应该去查询所有 user_id 与当前用户 id 相等的 Article 对象。backref="author" 则在 Article 对象上创建了一个名为 author 的属性，通过它可以在 Article 实例上方便地访问关联的 User 实例。
  • 建立关系可以通过设置外键列（如 article1.user_id = user1.id）或者直接操作关系属性（如 user1.articles.append(article1)）。通常推荐后一种方式，因为它更加面向对象，SQLAlchemy 会自动处理外键的设置。
  • 查询时，你可以像访问普通属性一样访问关系属性 (alice.articles 或 first_article.author)，SQLAlchemy 会根据需要在背后执行相应的查询来加载关联的对象（这涉及到惰性加载 – Lazy Loading，一个重要的性能优化概念，值得进一步学习）。
  • 你也可以使用 join() 方法在查询中明确地连接相关的表格，以便在一次数据库查询中获取需要的所有数据，避免 N+1 查询问题（即查询 N 个主对象后，又为每个对象执行额外的查询来加载其关联对象，共执行 N+1 次查询）。

总结与进一步学习

至此，你已经掌握了SQLAlchemy ORM的入门核心知识：连接数据库、定义模型、使用 Session 进行基本的 CRUD 操作，以及处理一对多关系。这为你打开了使用SQLAlchemy进行高效、优雅数据库开发的大门。

当然，SQLAlchemy的功能远不止这些。这是一个非常强大的库，还有许多高级特性等待你去探索，例如：

  • 查询进阶： 排序 (order_by())、限制结果数量 (limit())、跳过结果 (offset())、分组 (group_by())、聚合函数 (func.count(), func.sum())、子查询、联接选项（join, outerjoin）等等。
  • 会话管理： 更优雅的 Session 生命周期管理，比如使用 Session 的上下文管理器。
  • 数据类型： 更多复杂的数据类型映射（如日期、时间、JSON等）。
  • 模型继承： 如何使用ORM模型来表示数据库中的继承关系（如单一表继承、具体表继承等）。
  • 事件系统： 在对象生命周期的特定时刻（如加载前、提交前）触发自定义逻辑。
  • SQL表达式语言： 在需要时绕过ORM，直接使用SQL表达式语言构造更灵活的SQL语句。
  • 连接池和性能调优： 配置连接池，理解加载策略（Lazy, Eager, Joined, Subquery loading）以优化查询性能。
  • 数据库迁移工具： 使用 Alembic 等工具来管理数据库 schema 的变化。

掌握了本指南中的基础知识后，强烈建议你查阅SQLAlchemy的官方文档。它的文档非常详细和权威，虽然有时对初学者来说可能显得庞大，但它绝对是你深入学习的最佳资源。通过实践和阅读官方文档，你将能够充分发挥SQLAlchemy的强大能力，构建出更加健壮和高效的数据库应用。

从现在开始，尝试将SQLAlchemy应用到你自己的项目中吧！从一个简单的任务列表应用，到一个博客系统，再到一个更复杂的业务系统，不断练习和探索，你会发现SQLAlchemy能够极大地提升你的开发体验和效率。

祝你在学习SQLAlchemy的旅程中一切顺利！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部