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.
sqlalchemy.ext.horizontal_shard.
ShardedSession
(shard_chooser, id_chooser, query_chooser, shards=None, query_cls=<class 'sqlalchemy.ext.horizontal_shard.ShardedQuery'>, **kwargs)¶Bases: sqlalchemy.orm.session.Session
__init__
(shard_chooser, id_chooser, query_chooser, shards=None, query_cls=<class 'sqlalchemy.ext.horizontal_shard.ShardedQuery'>, **kwargs)¶Construct a ShardedSession.
Parameters: |
|
---|
connection
(mapper=None, instance=None, shard_id=None, **kwargs)¶Return a Connection
object corresponding to this
Session
object’s transactional state.
If this Session
is configured with autocommit=False
,
either the Connection
corresponding to the current
transaction is returned, or if no transaction is in progress, a new
one is begun and the Connection
returned (note that no
transactional state is established with the DBAPI until the first
SQL statement is emitted).
Alternatively, if this Session
is configured with
autocommit=True
, an ad-hoc Connection
is returned
using Engine.contextual_connect()
on the underlying
Engine
.
Ambiguity in multi-bind or unbound Session
objects can be
resolved through any of the optional keyword arguments. This
ultimately makes usage of the get_bind()
method for resolution.
Parameters: |
|
---|
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 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:
Table
objects
found in the given clause present in session.binds.MetaData
ultimately
associated with the clause.MetaData
ultimately
associated with the Table
or other
selectable to which the mapper is mapped.UnboundExecutionError
is raised.Parameters: |
|
---|
sqlalchemy.ext.horizontal_shard.
ShardedQuery
(*args, **kwargs)¶Bases: sqlalchemy.orm.query.Query
get
(ident, **kwargs)¶Return an instance based on the given primary key identifier,
or None
if not found.
E.g.:
my_user = session.query(User).get(5)
some_object = session.query(VersionedFoo).get((5, 10))
get()
is special in that it provides direct
access to the identity map of the owning Session
.
If the given primary key identifier is present
in the local identity map, the object is returned
directly from this collection and no SQL is emitted,
unless the object has been marked fully expired.
If not present,
a SELECT is performed in order to locate the object.
get()
also will perform a check if
the object is present in the identity map and
marked as expired - a SELECT
is emitted to refresh the object as well as to
ensure that the row is still present.
If not, ObjectDeletedError
is raised.
get()
is only used to return a single
mapped instance, not multiple instances or
individual column constructs, and strictly
on a single primary key value. The originating
Query
must be constructed in this way,
i.e. against a single mapped entity,
with no additional filtering criterion. Loading
options via options()
may be applied
however, and will be used if the object is not
yet locally present.
A lazy-loading, many-to-one attribute configured
by relationship()
, using a simple
foreign-key-to-primary-key criterion, will also use an
operation equivalent to get()
in order to retrieve
the target value from the local identity map
before querying the database. See Relationship Loading Techniques
for further details on relationship loading.
Parameters: | ident¶ – A scalar or tuple value representing
the primary key. For a composite primary key,
the order of identifiers corresponds in most cases
to that of the mapped Table object’s
primary key columns. For a mapper() that
was given the primary key argument during
construction, the order of identifiers corresponds
to the elements present in this collection. |
---|---|
Returns: | The object instance, or None . |
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.