水平分片

水平分片支持。

定义一个基本的“水平分片”系统，允许会话将查询和持久化操作分布到多个数据库中。

有关使用示例，请参阅源代码发行版中包含的 水平分片 示例。

深层炼金术

水平分片扩展是一个高级功能，涉及复杂的语句 -> 数据库交互，以及在非平凡情况下使用半公开 API。在使用这种更复杂、测试程度较低的系统之前，应始终首先考虑更简单的方案，例如使用不同的 Session 来引用多个数据库“分片”。

API 文档

对象名称	描述
set_shard_id	语句的加载器选项，用于将特定分片 ID 应用于主查询以及其他关系和列加载器。
ShardedQuery	与 ShardedSession 一起使用的查询类。
ShardedSession

class sqlalchemy.ext.horizontal_shard.ShardedSession

成员

__init__(), connection_callable(), get_bind()

类签名

class sqlalchemy.ext.horizontal_shard.ShardedSession (sqlalchemy.orm.session.Session)

method sqlalchemy.ext.horizontal_shard.ShardedSession.__init__(shard_chooser: ShardChooser, identity_chooser: Optional[IdentityChooser] = None, execute_chooser: Optional[Callable[[ORMExecuteState], Iterable[Any]]] = None, shards: Optional[Dict[str, Any]] = None, query_cls: Type[Query[_T]] = <class 'sqlalchemy.ext.horizontal_shard.ShardedQuery'>, *, id_chooser: Optional[Callable[[Query[_T], Iterable[_T]], Iterable[Any]]] = None, query_chooser: Optional[Callable[[Executable], Iterable[Any]]] = None, **kwargs: Any) → None

构造一个 ShardedSession。

参数:

• shard_chooser – 一个可调用对象，传递一个 Mapper、一个映射实例，以及一个可选的 SQL 子句，返回一个分片 ID。此 ID 可以基于对象中存在的属性，或基于某种循环方案。如果该方案基于选择，它应该在实例上设置任何状态以将其标记为将来参与该分片。

• identity_chooser –

  一个可调用对象，传递一个 Mapper 和主键参数，它应该返回一个包含此主键可能存在的分片 ID 列表。

  更改版本 2.0: identity_chooser 参数取代了 id_chooser 参数。

• execute_chooser –

  对于给定的 ORMExecuteState，返回应该在其中发出查询的分片 ID 列表。来自所有返回分片的的结果将合并到一个列表中。

  更改版本 1.4: execute_chooser 参数取代了 query_chooser 参数。

• shards – 一个字符串分片名称到 Engine 对象的字典。

method sqlalchemy.ext.horizontal_shard.ShardedSession.connection_callable(mapper: Mapper[_T] | None = None, instance: Any | None = None, shard_id: ShardIdentifier | None = None, **kw: Any) → Connection

为工作单元刷新过程中提供一个要使用的 Connection。

方法 sqlalchemy.ext.horizontal_shard.ShardedSession.get_bind(mapper: _EntityBindKey[_O] | None = None, *, shard_id: ShardIdentifier | None = None, instance: Any | None = None, clause: ClauseElement | None = None, **kw: Any) → _SessionBind

返回此 Session 绑定的“绑定”。

“绑定”通常是 Engine 的实例，除非 Session 已明确绑定到 Connection。

对于多重绑定或未绑定 Session，mapper 或 clause 参数用于确定要返回的适当绑定。

请注意，“mapper”参数通常在通过 ORM 操作（如 Session.query()、Session.flush() 内的每个单独的 INSERT/UPDATE/DELETE 操作、调用等）调用 Session.get_bind() 时出现。

解析顺序为

1. 如果给定 mapper 且 Session.binds 存在，则首先根据正在使用的 mapper 定位绑定，然后根据正在使用的映射类定位绑定，然后根据 __mro__ 中存在的映射类的任何基类定位绑定，从更具体的超类到更一般的超类。

2. 如果给定 clause 且 Session.binds 存在，则根据 Session.binds 中存在的给定 clause 中找到的 Table 对象定位绑定。

3. 如果 Session.binds 存在，则返回该绑定。

4. 如果给定 clause，则尝试返回与 clause 最终关联的 MetaData 链接的绑定。

5. 如果给定 mapper，则尝试返回与 mapper 映射到的 Table 或其他可选择对象最终关联的 MetaData 链接的绑定。

6. 找不到绑定，将引发 UnboundExecutionError。

请注意，可以在 Session 的用户定义子类上覆盖 Session.get_bind() 方法以提供任何类型的绑定解析方案。有关示例，请参阅 自定义垂直分区。

参数:

• mapper – 可选的映射类或相应的 Mapper 实例。绑定可以通过首先查询与此 Session 关联的“绑定”映射，然后查询与 Mapper 映射到的 Table 关联的 MetaData 来从 Mapper 中派生。

• clause – ClauseElement（即 select()、text() 等）。如果 mapper 参数不存在或无法生成绑定，则将搜索给定的表达式构造以找到绑定元素，通常是与绑定 MetaData 关联的 Table。

另请参阅

分区策略（例如，每个 Session 多个数据库后端）

Session.binds

Session.bind_mapper()

Session.bind_table()

类 sqlalchemy.ext.horizontal_shard.set_shard_id

语句的加载器选项，用于将特定分片 ID 应用于主查询以及其他关系和列加载器。

set_shard_id 选项可以使用任何可执行语句的 Executable.options() 方法应用

stmt = (
    select(MyObject).
    where(MyObject.name == 'some name').
    options(set_shard_id("shard1"))
)

上面，当调用该语句时，它将限制为主查询的“shard1”分片标识符，以及所有关系和列加载策略，包括像 selectinload() 这样的预加载器、像 defer() 这样的延迟列加载器以及延迟关系加载器 lazyload()。

通过这种方式，set_shard_id 选项的范围远大于在 Session.execute.bind_arguments 字典中使用“shard_id”参数。

2.0.0 版中的新功能。

成员

__init__(), propagate_to_loaders

类签名

类 sqlalchemy.ext.horizontal_shard.set_shard_id (sqlalchemy.orm.ORMOption)

方法 sqlalchemy.ext.horizontal_shard.set_shard_id.__init__(shard_id: str, propagate_to_loaders: bool = True)

构造一个 set_shard_id 选项。

参数:

• shard_id – 分片标识符

• propagate_to_loaders – 如果保留其默认值 True，分片选项将应用于延迟加载器，例如 lazyload() 和 defer(); 如果为 False，该选项将不会传播到已加载的对象。请注意，defer() 在任何情况下都始终限制为父行的 shard_id，因此该参数仅对 lazyload() 策略的行为产生影响。

属性 sqlalchemy.ext.horizontal_shard.set_shard_id.propagate_to_loaders

如果为 True，则表示该选项应传递给关系延迟加载器以及属性加载/刷新操作发生的“次要” SELECT 语句。

类 sqlalchemy.ext.horizontal_shard.ShardedQuery

与 ShardedSession 一起使用的查询类。

遗留功能

该 ShardedQuery 是遗留 Query 类的子类。该 ShardedSession 现在通过 ShardedSession.execute() 方法支持 2.0 风格的执行。

成员

set_shard()

类签名

类 sqlalchemy.ext.horizontal_shard.ShardedQuery (sqlalchemy.orm.Query)

方法 sqlalchemy.ext.horizontal_shard.ShardedQuery.set_shard(shard_id: str) → Self

返回一个新的查询，限制为单个分片 ID。

返回的查询的所有后续操作都将针对单个分片，而不管其他状态如何。

该 shard_id 可以传递给 Session.execute() 的 bind_arguments 字典以进行 2.0 风格的执行。

results = session.execute(
    stmt,
    bind_arguments={"shard_id": "my_shard"}
)