Horizontale Sharding

Unterstützung für horizontales Sharding.

Definiert ein rudimentäres System für „horizontales Sharding“, das es einer Session ermöglicht, Abfragen und Persistenzoperationen auf mehrere Datenbanken zu verteilen.

Ein Anwendungsbeispiel finden Sie im Beispiel Horizontales Sharding, das in der Quellcodeverteilung enthalten ist.

Deep Alchemy

Die Erweiterung für horizontales Sharding ist eine erweiterte Funktion, die eine komplexe Interaktion zwischen Anweisungen und Datenbanken sowie die Verwendung von semi-öffentlichen APIs für nicht-triviale Fälle beinhaltet. Einfachere Ansätze zum Verweisen auf mehrere Datenbank-„Shards“, meistens unter Verwendung einer separaten Session pro „Shard“, sollten immer zuerst in Betracht gezogen werden, bevor dieses komplexere und weniger produktionserprobte System verwendet wird.

API-Dokumentation

Objektname	Beschreibung
set_shard_id	Eine Loader-Option für Anweisungen, um eine spezifische Shard-ID für die primäre Abfrage sowie für zusätzliche Beziehungs- und Spaltenloader anzuwenden.
ShardedQuery	Abfrageklasse, die mit ShardedSession verwendet wird.
ShardedSession

class sqlalchemy.ext.horizontal_shard.ShardedSession

Mitglieder

__init__(), connection_callable(), get_bind()

Klassensignatur

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

Erstellt eine ShardedSession.

Parameter:

• shard_chooser – Ein aufrufbares Objekt, das einen Mapper, eine zugeordnete Instanz und möglicherweise eine SQL-Klausel erhält und eine Shard-ID zurückgibt. Diese ID kann auf den im Objekt vorhandenen Attributen oder auf einem Round-Robin-Verfahren basieren. Wenn das Verfahren auf einer Auswahl basiert, sollte es einen Zustand in der Instanz festlegen, um sie zukünftig als an diesem Shard teilnehmend zu markieren.

• identity_chooser –

  Ein aufrufbares Objekt, das einen Mapper und ein primäres Schlüsselargument erhält und eine Liste von Shard-IDs zurückgeben sollte, in denen sich dieser primäre Schlüssel befinden könnte.

  Geändert in Version 2.0: Der Parameter identity_chooser ersetzt den Parameter id_chooser.

• execute_chooser –

  Für einen gegebenen ORMExecuteState gibt es die Liste der Shard-IDs zurück, an die die Abfrage gesendet werden soll. Die Ergebnisse aller zurückgegebenen Shards werden zu einer einzigen Liste zusammengefasst.

  Geändert in Version 1.4: Der Parameter execute_chooser ersetzt den Parameter query_chooser.

• shards – Ein Wörterbuch von Zeichenketten-Shard-Namen zu Engine-Objekten.

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

Stellt eine Connection für den Flush-Prozess der Arbeitseinheit bereit.

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

Gibt ein „Bind“, an das diese Session gebunden ist, zurück.

Das „Bind“ ist normalerweise eine Instanz von Engine, außer wenn die Session explizit direkt an eine Connection gebunden wurde.

Für eine mehrfach gebundene oder ungebundene Session werden die Argumente mapper oder clause verwendet, um das entsprechende Bind zu bestimmen, das zurückgegeben werden soll.

Beachten Sie, dass das Argument „mapper“ normalerweise vorhanden ist, wenn Session.get_bind() über eine ORM-Operation wie Session.query(), jede einzelne INSERT/UPDATE/DELETE-Operation innerhalb eines Session.flush()-Aufrufs usw. aufgerufen wird.

Die Reihenfolge der Auflösung ist

1. Wenn ein Mapper angegeben ist und Session.binds vorhanden ist, wird ein Bind gesucht, basierend zuerst auf dem verwendeten Mapper, dann auf der verwendeten zugeordneten Klasse, dann auf beliebigen Basisklassen, die in der __mro__ der zugeordneten Klasse vorhanden sind, von spezifischeren Oberklassen zu allgemeineren.

2. Wenn eine Klausel angegeben ist und Session.binds vorhanden ist, wird ein Bind gesucht, basierend auf Table-Objekten, die in der angegebenen Klausel gefunden wurden und in Session.binds vorhanden sind.

3. Wenn Session.binds vorhanden ist, geben Sie diese zurück.

4. Wenn eine Klausel angegeben ist, wird versucht, ein Bind zurückzugeben, das mit den MetaData verbunden ist, die letztendlich mit der Klausel verbunden sind.

5. Wenn ein Mapper angegeben ist, wird versucht, ein Bind zurückzugeben, das mit den MetaData verbunden ist, die letztendlich mit der Table oder einem anderen wählbaren Element verbunden sind, dem der Mapper zugeordnet ist.

6. Es kann kein Bind gefunden werden, es wird UnboundExecutionError ausgelöst.

Beachten Sie, dass die Methode Session.get_bind() in einer benutzerdefinierten Unterklasse von Session überschrieben werden kann, um jedes beliebige Bind-Auflösungsschema bereitzustellen. Siehe das Beispiel unter Benutzerdefiniertes vertikales Partitionieren.

Parameter:

• mapper – Optionale zugeordnete Klasse oder entsprechende Mapper-Instanz. Das Bind kann von einem Mapper abgeleitet werden, indem zuerst die Zuordnung „binds“ der Session konsultiert und dann die MetaData konsultiert wird, die der Table zugeordnet ist, der der Mapper zugeordnet ist, um ein Bind zu erhalten.

• clause – Ein ClauseElement (d. h. select(), text(), etc.). Wenn das Argument mapper nicht vorhanden ist oder kein Bind erzeugt werden konnte, wird der angegebene Ausdruckskonstrukt nach einem gebundenen Element durchsucht, typischerweise einer Table, die mit einer gebundenen MetaData verbunden ist.

Siehe auch

Partitionierungsstrategien (z. B. mehrere Datenbank-Backends pro Session)

Session.binds

Session.bind_mapper()

Session.bind_table()

class sqlalchemy.ext.horizontal_shard.set_shard_id

Eine Loader-Option für Anweisungen, um eine spezifische Shard-ID für die primäre Abfrage sowie für zusätzliche Beziehungs- und Spaltenloader anzuwenden.

Die Option set_shard_id kann mit der Methode Executable.options() jeder ausführbaren Anweisung angewendet werden

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

Oben wird die Anweisung bei der Ausführung auf den „shard1“-Shard-Identifikator für die primäre Abfrage sowie für alle Beziehungs- und Spaltenladestrategien beschränkt, einschließlich Eager-Loader wie selectinload(), Deferred-Spaltenloader wie defer() und den Lazy-Beziehungs-Loader lazyload().

Auf diese Weise hat die Option set_shard_id einen viel breiteren Geltungsbereich als die Verwendung des Arguments „shard_id“ im Wörterbuch Session.execute.bind_arguments.

Neu in Version 2.0.0.

Mitglieder

__init__(), propagate_to_loaders

Klassensignatur

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)

Erstellt eine Option set_shard_id.

Parameter:

• shard_id – Shard-Identifikator

• propagate_to_loaders – Wenn auf dem Standardwert True belassen, hat die Shard-Option Auswirkungen auf Lazy-Loader wie lazyload() und defer(); wenn False, wird die Option nicht auf geladene Objekte übertragen. Beachten Sie, dass defer() in jedem Fall immer auf die Shard-ID der übergeordneten Zeile beschränkt ist, sodass der Parameter nur Auswirkungen auf das Verhalten der lazyload()-Strategie hat.

attribute sqlalchemy.ext.horizontal_shard.set_shard_id.propagate_to_loaders

Wenn True, gibt an, dass diese Option für „sekundäre“ SELECT-Anweisungen, die für Beziehungs-Lazy-Loader sowie für Attribut-Lade-/Aktualisierungsoperationen auftreten, übernommen werden soll.

class sqlalchemy.ext.horizontal_shard.ShardedQuery

Abfrageklasse, die mit ShardedSession verwendet wird.

Legacy-Funktion

Die ShardedQuery ist eine Unterklasse der älteren Query-Klasse. Die ShardedSession unterstützt nun die Ausführung im 2.0-Stil über die Methode ShardedSession.execute().

Mitglieder

set_shard()

Klassensignatur

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

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

Gibt eine neue Abfrage zurück, die auf eine einzelne Shard-ID beschränkt ist.

Alle nachfolgenden Operationen mit der zurückgegebenen Abfrage erfolgen gegen den einzelnen Shard, unabhängig von anderem Zustand.

Die shard_id kann für eine Ausführung im 2.0-Stil an das Wörterbuch bind_arguments von Session.execute() übergeben werden

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