SQLAlchemy 1.3 Documentation
SQLAlchemy ORM
- Object Relational Tutorial
- Mapper Configuration
- Relationship Configuration
- Loading Objects
- Using the Session
- Events and Internals
- ORM Extensions
- ORM Examples
Project Versions
Horizontal Sharding¶
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.
API Documentation¶
Object Name | Description |
---|---|
- class sqlalchemy.ext.horizontal_shard.ShardedSession(shard_chooser, id_chooser, query_chooser, shards=None, query_cls=<class 'sqlalchemy.ext.horizontal_shard.ShardedQuery'>, **kwargs)¶
Members
Class signature
class
sqlalchemy.ext.horizontal_shard.ShardedSession
(sqlalchemy.orm.session.Session
)-
method
sqlalchemy.ext.horizontal_shard.ShardedSession.
__init__(shard_chooser, id_chooser, query_chooser, shards=None, query_cls=<class 'sqlalchemy.ext.horizontal_shard.ShardedQuery'>, **kwargs)¶ Construct a ShardedSession.
- Parameters:
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.
query_chooser¶ – For a given Query, 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.
shards¶ – A dictionary of string shard names to
Engine
objects.
-
method
sqlalchemy.ext.horizontal_shard.ShardedSession.
connection(mapper=None, instance=None, shard_id=None, **kwargs)¶ Return a
Connection
object corresponding to thisSession
object’s transactional state.If this
Session
is configured withautocommit=False
, either theConnection
corresponding to the current transaction is returned, or if no transaction is in progress, a new one is begun and theConnection
returned (note that no transactional state is established with the DBAPI until the first SQL statement is emitted).Alternatively, if this
Session
is configured withautocommit=True
, an ad-hocConnection
is returned usingEngine.connect()
on the underlyingEngine
.Ambiguity in multi-bind or unbound
Session
objects can be resolved through any of the optional keyword arguments. This ultimately makes usage of theget_bind()
method for resolution.- Parameters:
bind¶ – Optional
Engine
to be used as the bind. If this engine is already involved in an ongoing transaction, that connection will be used. This argument takes precedence overmapper
,clause
.mapper¶ – Optional
mapper()
mapped class, used to identify the appropriate bind. This argument takes precedence overclause
.clause¶ – A
ClauseElement
(i.e.select()
,text()
, etc.) which will be used to locate a bind, if a bind cannot otherwise be identified.close_with_result¶ – Passed to
Engine.connect()
, indicating theConnection
should be considered “single use”, automatically closing when the first result set is closed. This flag only has an effect if thisSession
is configured withautocommit=True
and does not already have a transaction in progress.execution_options¶ –
a dictionary of execution options that will be passed to
Connection.execution_options()
, when the connection is first procured only. If the connection is already present within theSession
, a warning is emitted and the arguments are ignored.New in version 0.9.9.
**kw¶ – Additional keyword arguments are sent to
get_bind()
, allowing additional arguments to be passed to custom implementations ofget_bind()
.
-
method
sqlalchemy.ext.horizontal_shard.ShardedSession.
get_bind(mapper, 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 theSession
has been explicitly bound directly to aConnection
.For a multiply-bound or unbound
Session
, themapper
orclause
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 aSession.query()
, each individual INSERT/UPDATE/DELETE operation within aSession.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 onTable
objects found in the given clause present inSession.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 theTable
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 ofSession
to provide any kind of bind resolution scheme. See the example at Custom Vertical Partitioning.- Parameters:
mapper¶ – Optional
mapper()
mapped class or instance ofMapper
. The bind can be derived from aMapper
first by consulting the “binds” map associated with thisSession
, and secondly by consulting theMetaData
associated with theTable
to which theMapper
is mapped for a bind.clause¶ – A
ClauseElement
(i.e.select()
,text()
, etc.). If themapper
argument is not present or could not produce a bind, the given expression construct will be searched for a bound element, typically aTable
associated with boundMetaData
.
-
method
- class sqlalchemy.ext.horizontal_shard.ShardedQuery(*args, **kwargs)¶
Members
Class signature
class
sqlalchemy.ext.horizontal_shard.ShardedQuery
(sqlalchemy.orm.query.Query
)-
method
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.
-
method
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 7.2.6. Documentation last generated: Sat 06 Jan 2024 12:16:15 PM