SqlAlchemy 2.0 中文文档（四）（2）-阿里云开发者社区

SqlAlchemy 2.0 中文文档（四）（1）https://developer.aliyun.com/article/1562994

创建引擎

Engine是一个能够为我们创建新数据库连接的工厂，它还将连接保留在连接池中以供快速重用。出于学习目的，我们通常使用 SQLite 内存数据库以方便起见：

>>> from sqlalchemy import create_engine
>>> engine = create_engine("sqlite://", echo=True)

提示

echo=True 参数表示连接发出的 SQL 将被记录到标准输出。

对Engine的全面介绍始于建立连接 - 引擎。

发出 CREATE TABLE DDL

使用我们的表元数据和引擎，我们可以一次性在目标 SQLite 数据库中生成我们的模式，使用一种叫做MetaData.create_all()的方法：

>>> Base.metadata.create_all(engine)
BEGIN  (implicit)
PRAGMA  main.table_...info("user_account")
...
PRAGMA  main.table_...info("address")
...
CREATE  TABLE  user_account  (
  id  INTEGER  NOT  NULL,
  name  VARCHAR(30)  NOT  NULL,
  fullname  VARCHAR,
  PRIMARY  KEY  (id)
)
...
CREATE  TABLE  address  (
  id  INTEGER  NOT  NULL,
  email_address  VARCHAR  NOT  NULL,
  user_id  INTEGER  NOT  NULL,
  PRIMARY  KEY  (id),
  FOREIGN  KEY(user_id)  REFERENCES  user_account  (id)
)
...
COMMIT

刚才我们编写的那段 Python 代码发生了很多事情。要完整了解表元数据的情况，请参阅使用数据库元数据中的教程。

创建对象并持久化

我们现在可以将数据插入到数据库中了。我们通过创建User和Address类的实例来实现这一点，这些类已经通过声明映射过程自动创建了__init__()方法。然后，我们使用一个称为 Session 的对象将它们传递给数据库，该对象使用Engine与数据库进行交互。这里使用Session.add_all()方法一次添加多个对象，并且将使用Session.commit()方法刷新数据库中的任何待处理更改，然后提交当前的数据库事务，该事务始终在使用Session时处于进行中：

>>> from sqlalchemy.orm import Session
>>> with Session(engine) as session:
...     spongebob = User(
...         name="spongebob",
...         fullname="Spongebob Squarepants",
...         addresses=[Address(email_address="spongebob@sqlalchemy.org")],
...     )
...     sandy = User(
...         name="sandy",
...         fullname="Sandy Cheeks",
...         addresses=[
...             Address(email_address="sandy@sqlalchemy.org"),
...             Address(email_address="sandy@squirrelpower.org"),
...         ],
...     )
...     patrick = User(name="patrick", fullname="Patrick Star")
...
...     session.add_all([spongebob, sandy, patrick])
...
...     session.commit()
BEGIN  (implicit)
INSERT  INTO  user_account  (name,  fullname)  VALUES  (?,  ?)  RETURNING  id
[...]  ('spongebob',  'Spongebob Squarepants')
INSERT  INTO  user_account  (name,  fullname)  VALUES  (?,  ?)  RETURNING  id
[...]  ('sandy',  'Sandy Cheeks')
INSERT  INTO  user_account  (name,  fullname)  VALUES  (?,  ?)  RETURNING  id
[...]  ('patrick',  'Patrick Star')
INSERT  INTO  address  (email_address,  user_id)  VALUES  (?,  ?)  RETURNING  id
[...]  ('spongebob@sqlalchemy.org',  1)
INSERT  INTO  address  (email_address,  user_id)  VALUES  (?,  ?)  RETURNING  id
[...]  ('sandy@sqlalchemy.org',  2)
INSERT  INTO  address  (email_address,  user_id)  VALUES  (?,  ?)  RETURNING  id
[...]  ('sandy@squirrelpower.org',  2)
COMMIT

提示

建议像上面那样使用 Python 的 with: 语句，即使用上下文管理器样式使用Session。 Session 对象代表着活跃的数据库资源，所以当一系列操作完成时，确保关闭它是很好的。在下一节中，我们将保持Session处于打开状态，仅用于说明目的。

创建Session的基础知识请参考使用 ORM Session 执行，更多内容请参考使用 Session 的基础知识。

接下来，介绍了一些基本持久化操作的变体，请参阅使用 ORM 工作单元模式插入行。

简单的 SELECT

在数据库中有一些行时，这是发出 SELECT 语句以加载一些对象的最简单形式。要创建 SELECT 语句，我们使用select() 函数创建一个新的Select 对象，然后使用Session 调用它。查询 ORM 对象时经常有用的方法是Session.scalars() 方法，它将返回一个ScalarResult 对象，该对象将迭代我们选择的 ORM 对象：

>>> from sqlalchemy import select
>>> session = Session(engine)
>>> stmt = select(User).where(User.name.in_(["spongebob", "sandy"]))
>>> for user in session.scalars(stmt):
...     print(user)
BEGIN  (implicit)
SELECT  user_account.id,  user_account.name,  user_account.fullname
FROM  user_account
WHERE  user_account.name  IN  (?,  ?)
[...]  ('spongebob',  'sandy')
User(id=1, name='spongebob', fullname='Spongebob Squarepants')
User(id=2, name='sandy', fullname='Sandy Cheeks')

上述查询还使用了Select.where() 方法添加 WHERE 条件，并且还使用了所有 SQLAlchemy 列对象的一部分的ColumnOperators.in_() 方法来使用 SQL IN 操作符。

如何选择对象和单独列的更多详细信息请参阅选择 ORM 实体和列。

使用 JOIN 的 SELECT

在 SQL 中，一次查询多个表是非常常见的，而 JOIN 关键字是实现这一目的的主要方法。Select 构造函数使用Select.join() 方法创建连接：

>>> stmt = (
...     select(Address)
...     .join(Address.user)
...     .where(User.name == "sandy")
...     .where(Address.email_address == "sandy@sqlalchemy.org")
... )
>>> sandy_address = session.scalars(stmt).one()
SELECT  address.id,  address.email_address,  address.user_id
FROM  address  JOIN  user_account  ON  user_account.id  =  address.user_id
WHERE  user_account.name  =  ?  AND  address.email_address  =  ?
[...]  ('sandy',  'sandy@sqlalchemy.org')
>>> sandy_address
Address(id=2, email_address='sandy@sqlalchemy.org')

上述查询示例说明了多个 WHERE 条件如何自动使用 AND 连接，并且展示了如何使用 SQLAlchemy 列对象创建“相等性”比较，该比较使用了重载的 Python 方法ColumnOperators.__eq__()来生成 SQL 条件对象。

以上概念的更多背景可在 WHERE 子句和显式 FROM 子句和 JOIN 处找到。

进行更改

Session 对象与我们的 ORM 映射类 User 和 Address 一起，会自动跟踪对象的更改，这些更改会导致 SQL 语句在下次 Session 刷新时被发出。下面，我们更改了与“sandy”关联的一个电子邮件地址，并在发出 SELECT 以检索“patrick”的行之后，向“patrick”添加了一个新的电子邮件地址：

>>> stmt = select(User).where(User.name == "patrick")
>>> patrick = session.scalars(stmt).one()
SELECT  user_account.id,  user_account.name,  user_account.fullname
FROM  user_account
WHERE  user_account.name  =  ?
[...]  ('patrick',)
>>> patrick.addresses.append(Address(email_address="patrickstar@sqlalchemy.org"))
SELECT  address.id  AS  address_id,  address.email_address  AS  address_email_address,  address.user_id  AS  address_user_id
FROM  address
WHERE  ?  =  address.user_id
[...]  (3,)
>>> sandy_address.email_address = "sandy_cheeks@sqlalchemy.org"
>>> session.commit()
UPDATE  address  SET  email_address=?  WHERE  address.id  =  ?
[...]  ('sandy_cheeks@sqlalchemy.org',  2)
INSERT  INTO  address  (email_address,  user_id)  VALUES  (?,  ?)
[...]  ('patrickstar@sqlalchemy.org',  3)
COMMIT

注意当我们访问patrick.addresses时，会发出一个 SELECT。这被称为延迟加载。有关使用更多或更少的 SQL 访问相关项目的不同方法的背景介绍，请参阅加载器策略。

有关使用 ORM 进行数据操作的详细说明，请参阅 ORM 数据操作。

一些删除操作

万物都有尽头，就像我们的一些数据库行一样 - 这里快速演示了两种不同形式的删除，根据特定用例的重要性而定。

首先，我们将从sandy用户中删除一个Address对象。当Session下次刷新时，这将导致该行被删除。这种行为是我们在映射中配置的，称为级联删除。我们可以使用 Session.get() 按主键获取到sandy对象，然后操作该对象：

>>> sandy = session.get(User, 2)
BEGIN  (implicit)
SELECT  user_account.id  AS  user_account_id,  user_account.name  AS  user_account_name,  user_account.fullname  AS  user_account_fullname
FROM  user_account
WHERE  user_account.id  =  ?
[...]  (2,)
>>> sandy.addresses.remove(sandy_address)
SELECT  address.id  AS  address_id,  address.email_address  AS  address_email_address,  address.user_id  AS  address_user_id
FROM  address
WHERE  ?  =  address.user_id
[...]  (2,)

上面的最后一个 SELECT 是为了进行延迟加载操作，以便加载sandy.addresses集合，以便我们可以删除sandy_address成员。还有其他方法可以执行这一系列操作，不会发出太多的 SQL。

我们可以选择发出针对到目前为止被更改的 DELETE SQL，而不提交事务，使用 Session.flush() 方法：

>>> session.flush()
DELETE  FROM  address  WHERE  address.id  =  ?
[...]  (2,)

接下来，我们将完全删除“patrick”用户。对于对象的顶级删除，我们使用Session.delete()方法；这个方法实际上并不执行删除操作，而是设置对象在下一次刷新时将被删除。该操作还会根据我们配置的级联选项级联到相关对象，本例中是关联的Address对象：

>>> session.delete(patrick)
SELECT  user_account.id  AS  user_account_id,  user_account.name  AS  user_account_name,  user_account.fullname  AS  user_account_fullname
FROM  user_account
WHERE  user_account.id  =  ?
[...]  (3,)
SELECT  address.id  AS  address_id,  address.email_address  AS  address_email_address,  address.user_id  AS  address_user_id
FROM  address
WHERE  ?  =  address.user_id
[...]  (3,)

在这种特殊情况下，Session.delete()方法发出了两个 SELECT 语句，即使它没有发出 DELETE，这可能看起来令人惊讶。这是因为当方法检查对象时，发现patrick对象已经过期，这是在我们上次调用Session.commit()时发生的，发出的 SQL 是为了从新事务重新加载行。这种过期是可选的，在正常使用中，我们通常会在不适用的情况下关闭它。

要说明被删除的行，请看这个提交：

>>> session.commit()
DELETE  FROM  address  WHERE  address.id  =  ?
[...]  (4,)
DELETE  FROM  user_account  WHERE  user_account.id  =  ?
[...]  (3,)
COMMIT

本教程讨论了 ORM 删除操作，详情请见使用工作单元模式删除 ORM 对象。关于对象过期的背景信息请参考过期/刷新；级联操作在 Cascades 中有详细讨论。

深入学习上述概念

对于新用户来说，上述部分可能是一场令人眼花缭乱的旅程。每个步骤中都有许多重要概念没有涵盖。快速了解事物的外观后，建议通过 SQLAlchemy 统一教程来深入了解上述内容。祝好运！

ORM 映射类配置

原文：docs.sqlalchemy.org/en/20/orm/mapper_config.html

ORM 配置的详细参考，不包括关系，关系详细说明在关系配置。

要快速查看典型的 ORM 配置，请从 ORM 快速入门开始。

要了解 SQLAlchemy 实现的对象关系映射概念，请先查看 SQLAlchemy 统一教程，在使用 ORM 声明形式定义表元数据中介绍。

ORM 映射类概述

ORM 映射风格

声明性映射
命令式映射

映射类基本组件

待映射的类
表或其他来自子句对象
属性字典
其他映射器配置参数

映射类行为

默认构造函数
跨加载保持非映射状态
映射类、实例和映射器的运行时内省

映射器对象的检查
映射实例的检查

使用声明性映射类

声明性映射风格

使用声明性基类
使用装饰器的声明性映射（无声明性基类）

使用声明性配置表

带有 mapped_column() 的声明性表

使用带注释的声明性表（mapped_column()的类型注释形式）
访问表和元数据
声明性表配置
使用声明性表的显式模式名称
为声明式映射的列设置加载和持久化选项
显式命名声明式映射列
将额外列添加到现有的声明式映射类

使用命令式表进行声明式（即混合声明式）

映射表列的替代属性名
为命令式表列应用加载、持久化和映射选项

使用反射表进行声明式映射

使用延迟反射
使用自动映射
从反射表自动化列命名方案
映射到显式主键列集合
映射表列的子集

声明式映射器配置

使用声明式定义映射属性
声明式的映射器配置选项

动态构建映射器参数

其他声明式映射指令

__declare_last__()
__declare_first__()
metadata
__abstract__
__table_cls__

使用混合组合映射层次结构

增强基类
混合使用列
混合使用关系
在 _orm.column_property() 和其他 _orm.MapperProperty 类中混合使用
使用混合和基类进行映射继承模式

使用 _orm.declared_attr() 与继承 Table 和 Mapper 参数
使用 _orm.declared_attr() 生成表特定的继承列

从多个混合类组合表/映射器参数
使用命名约定在混合类上创建索引和约束

与 dataclasses 和 attrs 集成

声明式数据类映射

类级别功能配置
属性配置

列默认值
与 Annotated 集成

使用混合类和抽象超类
关系配置
使用未映射的数据类字段
与 Pydantic 等替代数据类提供者集成

将 ORM 映射应用于现有的数据类（传统数据类使用）

使用声明式与命令式表映射映射预先存在的数据类
使用声明式样式字段映射预先存在的数据类

使用预先存在的数据类的声明式混合类

使用命令式映射映射预先存在的数据类

将 ORM 映射应用于现有的 attrs 类

使用声明式“命令式表”映射映射属性
使用命令式映射映射属性

SQL 表达式作为映射属性

使用混合类
使用 column_property

将 column_property() 添加到现有的声明式映射类
在映射时从列属性组合
使用 column_property() 进行列推迟

使用普通描述符
查询时将 SQL 表达式作为映射属性

更改属性行为

简单验证器

validates()

在核心级别使用自定义数据类型
使用描述符和混合物
同义词

synonym()

操作符定制

复合列类型

使用映射的复合列类型
复合体的其他映射形式

直接映射列，然后传递给复合体
直接映射列，将属性名称传递给复合体
命令映射和命令表

使用传统非数据类
跟踪复合体上的原位变化
重新定义复合体的比较操作
嵌套复合体
复合体 API

composite()

映射类继承层次结构

联接表继承

与联接继承相关的关系
加载联接继承映射

单表继承

使用 use_existing_column 解决列冲突
与单表继承相关的关系
使用 polymorphic_abstract 构建更深层次的层次结构
加载单表继承映射

具体表继承

具体多态加载配置
抽象具体类
经典和半经典具体多态配置
具体继承关系的关系
加载具体继承映射

非传统映射

将类映射到多个表
将类映射到任意子查询
一个类的多个映射器

配置版本计数器

简单版本计数
自定义版本计数器/类型
服务器端版本计数器
编程或条件版本计数器

类映射 API

registry

registry.__init__()
registry.as_declarative_base()
registry.configure()
registry.dispose()
registry.generate_base()
registry.map_declaratively()
registry.map_imperatively()
registry.mapped()
registry.mapped_as_dataclass()
registry.mappers
registry.update_type_annotation_map()

add_mapped_attribute()
column_property()
declarative_base()
declarative_mixin()
as_declarative()
mapped_column()
declared_attr

declared_attr.cascading
declared_attr.directive

DeclarativeBase

DeclarativeBase.__mapper__
DeclarativeBase.__mapper_args__
DeclarativeBase.__table__
DeclarativeBase.__table_args__
DeclarativeBase.__tablename__
DeclarativeBase.metadata
DeclarativeBase.registry

DeclarativeBaseNoMeta

DeclarativeBaseNoMeta.__mapper__
DeclarativeBaseNoMeta.__mapper_args__
DeclarativeBaseNoMeta.__table__
DeclarativeBaseNoMeta.__table_args__
DeclarativeBaseNoMeta.__tablename__
DeclarativeBaseNoMeta.metadata
DeclarativeBaseNoMeta.registry

has_inherited_table()
synonym_for()
object_mapper()
class_mapper()
configure_mappers()
clear_mappers()
identity_key()
polymorphic_union()
orm_insert_sentinel()
reconstructor()
Mapper

Mapper.__init__()
Mapper.add_properties()
Mapper.add_property()
Mapper.all_orm_descriptors
Mapper.attrs
Mapper.base_mapper
Mapper.c
Mapper.cascade_iterator()
Mapper.class_
Mapper.class_manager
Mapper.column_attrs
Mapper.columns
Mapper.common_parent()
Mapper.composites
Mapper.concrete
Mapper.configured
Mapper.entity
Mapper.get_property()
Mapper.get_property_by_column()
Mapper.identity_key_from_instance()
Mapper.identity_key_from_primary_key()
Mapper.identity_key_from_row()
Mapper.inherits
Mapper.is_mapper
Mapper.is_sibling()
Mapper.isa()
Mapper.iterate_properties
Mapper.local_table
Mapper.mapped_table
Mapper.mapper
Mapper.non_primary
Mapper.persist_selectable
Mapper.polymorphic_identity
Mapper.polymorphic_iterator()
Mapper.polymorphic_map
Mapper.polymorphic_on
Mapper.primary_key
Mapper.primary_key_from_instance()
Mapper.primary_mapper()
Mapper.relationships
Mapper.selectable
Mapper.self_and_descendants
Mapper.single
Mapper.synonyms
Mapper.tables
Mapper.validators
Mapper.with_polymorphic_mappers

MappedAsDataclass
MappedClassProtocol

SqlAlchemy 2.0 中文文档（四）（3）https://developer.aliyun.com/article/1562996

SqlAlchemy 2.0 中文文档（四）（2）

创建引擎

发出 CREATE TABLE DDL

创建对象并持久化

简单的 SELECT

使用 JOIN 的 SELECT

进行更改

一些删除操作

深入学习上述概念

ORM 映射类配置

热门文章

最新文章

相关电子书

热门

活动广场

任务中心

开发者评测

高校计划

乘风者计划

训练营

阿里云MVP

话题

直播

下载

镜像站

技术资料

插件

SqlAlchemy 2.0 中文文档（四）（2）

创建引擎

发出 CREATE TABLE DDL

创建对象并持久化

简单的 SELECT

使用 JOIN 的 SELECT

进行更改

一些删除操作

深入学习上述概念

ORM 映射类配置

热门文章

最新文章

相关电子书