Horizontal sharding support.
Defines a rudimental ‘horizontal sharding’ system which allows a Session to distribute queries and persistence operations across multiple databases.
For a usage example, see the Horizontal Sharding example included in the source distribution.
Object Name | Description |
---|---|
Class signature
class sqlalchemy.ext.horizontal_shard.ShardedSession
(sqlalchemy.orm.session.Session
)
sqlalchemy.ext.horizontal_shard.ShardedSession.
__init__(shard_chooser, id_chooser, execute_chooser=None, shards=None, query_cls=<class 'sqlalchemy.ext.horizontal_shard.ShardedQuery'>, **kwargs)¶Construct a ShardedSession.
shard_chooser¶ – A callable which, passed a Mapper, a mapped instance, and possibly a SQL clause, returns a shard ID. This id may be based off of the attributes present within the object, or on some round-robin scheme. If the scheme is based on a selection, it should set whatever state on the instance to mark it in the future as participating in that shard.
id_chooser¶ – A callable, passed a query and a tuple of identity values, which should return a list of shard ids where the ID might reside. The databases will be queried in the order of this listing.
execute_chooser¶ –
For a given ORMExecuteState
,
returns the list of shard_ids
where the query should be issued. Results from all shards returned
will be combined together into a single listing.
Changed in version 1.4: The execute_chooser
parameter
supersedes the query_chooser
parameter.
shards¶ – A dictionary of string shard names
to Engine
objects.
sqlalchemy.ext.horizontal_shard.ShardedSession.
connection_callable(mapper=None, instance=None, shard_id=None, **kwargs)¶Provide a Connection
to use in the unit of work
flush process.
sqlalchemy.ext.horizontal_shard.ShardedSession.
get_bind(mapper=None, shard_id=None, instance=None, clause=None, **kw)¶Return a “bind” to which this Session
is bound.
The “bind” is usually an instance of Engine
,
except in the case where the Session
has been
explicitly bound directly to a Connection
.
For a multiply-bound or unbound Session
, the
mapper
or clause
arguments are used to determine the
appropriate bind to return.
Note that the “mapper” argument is usually present
when Session.get_bind()
is called via an ORM
operation such as a Session.query()
, each
individual INSERT/UPDATE/DELETE operation within a
Session.flush()
, call, etc.
The order of resolution is:
if mapper given and Session.binds
is present,
locate a bind based first on the mapper in use, then
on the mapped class in use, then on any base classes that are
present in the __mro__
of the mapped class, from more specific
superclasses to more general.
if clause given and Session.binds
is present,
locate a bind based on Table
objects
found in the given clause present in Session.binds
.
if Session.binds
is present, return that.
if clause given, attempt to return a bind
linked to the MetaData
ultimately
associated with the clause.
if mapper given, attempt to return a bind
linked to the MetaData
ultimately
associated with the Table
or other
selectable to which the mapper is mapped.
No bind can be found, UnboundExecutionError
is raised.
Note that the Session.get_bind()
method can be overridden on
a user-defined subclass of Session
to provide any kind
of bind resolution scheme. See the example at
Custom Vertical Partitioning.
mapper¶ – Optional mapper()
mapped class or instance of
Mapper
. The bind can be derived from a
Mapper
first by consulting the “binds” map associated with this
Session
, and secondly by consulting the
MetaData
associated with the Table
to which the
Mapper
is mapped for a bind.
clause¶ – A ClauseElement
(i.e.
select()
,
text()
,
etc.). If the mapper
argument is not present or could not
produce a bind, the given expression construct will be searched
for a bound element, typically a Table
associated with
bound MetaData
.
Class signature
class sqlalchemy.ext.horizontal_shard.ShardedQuery
(sqlalchemy.orm.Query
)
sqlalchemy.ext.horizontal_shard.ShardedQuery.
set_shard(shard_id)¶Return a new query, limited to a single shard ID.
All subsequent operations with the returned query will be against the single shard regardless of other state.
The shard_id can be passed for a 2.0 style execution to the
bind_arguments dictionary of Session.execute()
:
results = session.execute(
stmt,
bind_arguments={"shard_id": "my_shard"}
)
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 4.2.0.