水平分片

水平分片支持。

定义了一个基本的“水平分片”系统，允许 Session 在多个数据库之间分发查询和持久化操作。

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

深度炼金术

水平分片扩展是一个高级功能，涉及到复杂的语句 -> 数据库交互，以及在非平凡的情况下使用半公开 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。

method 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 绑定的“bind”。

“bind”通常是 Engine 的实例，除非 Session 已显式直接绑定到 Connection 的情况。

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

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

解析顺序为

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

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

  3. 如果存在 Session.binds，则返回它。

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

  5. 如果给定 mapper，则尝试返回链接到最终与 Table 或 mapper 映射到的其他 selectable 关联的 MetaData 的 bind。

  6. 如果找不到 bind，则引发 UnboundExecutionError。

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

参数:

  • mapper – 可选的映射类或相应的 Mapper 实例。可以通过以下方式从 Mapper 派生 bind：首先查阅与此 Session 关联的“binds”映射，其次查阅与 Table 关联的 MetaData，Mapper 映射到该表以获取 bind。

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

另请参阅

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

Session.binds

Session.bind_mapper()

Session.bind_table()

class 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

类签名

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

method 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() 策略的行为产生净影响。

attribute sqlalchemy.ext.horizontal_shard.set_shard_id.propagate_to_loaders

如果为 True，则指示此选项应延续到为关系惰性加载器以及属性加载/刷新操作而发生的“辅助”SELECT 语句。

class sqlalchemy.ext.horizontal_shard.ShardedQuery

与 ShardedSession 一起使用的查询类。

遗留功能

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

成员

set_shard()

类签名

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

method 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"})