Horizontal Sharding
- API Documentation

Horizontal Sharding

Horizontal sharding support.

Defines a rudimental ‘horizontal sharding’ system which allows a Session todistribute queries and persistence operations across multiple databases.

For a usage example, see the Horizontal Sharding example included inthe source distribution.

API Documentation

class sqlalchemy.ext.horizontalshard.ShardedSession(_shard_chooser, id_chooser, query_chooser, shards=None, query_cls=, **kwargs)
Bases: sqlalchemy.orm.session.Session
- init(shard_chooser, id_chooser, query_chooser, shards=None, query_cls=, **kwargs)
- Construct a ShardedSession.
  - Parameters
  - - shard_chooser – A callable which, passed a Mapper, a mappedinstance, and possibly a SQL clause, returns a shard ID. This idmay be based off of the attributes present within the object, or onsome round-robin scheme. If the scheme is based on a selection, itshould set whatever state on the instance to mark it in the future asparticipating in that shard.
    - id_chooser – A callable, passed a query and a tuple of identityvalues, which should return a list of shard ids where the ID mightreside. The databases will be queried in the order of this listing.
    - query_chooser – For a given Query, returns the list of shard_idswhere the query should be issued. Results from all shards returnedwill be combined together into a single listing.
    - shards – A dictionary of string shard namesto Engine objects.
- 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 with autocommit=False,either the Connection corresponding to the currenttransaction is returned, or if no transaction is in progress, a newone is begun and the Connection returned (note that notransactional state is established with the DBAPI until the firstSQL statement is emitted).

Alternatively, if this Session is configured withautocommit=True, an ad-hoc Connection is returnedusing Engine.connect() on the underlyingEngine.

Ambiguity in multi-bind or unbound Session objects can beresolved through any of the optional keyword arguments. Thisultimately makes usage of the get_bind() method for resolution.

- Parameters
- 
  -

bind – Optional Engine to be used as the bind. Ifthis engine is already involved in an ongoing transaction,that connection will be used. This argument takes precedenceover mapper, clause.

mapper – Optional mapper() mapped class, used to identifythe 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 bindcannot otherwise be identified.

close_with_result – Passed to Engine.connect(),indicating the Connection should be considered“single use”, automatically closing when the first result set isclosed. This flag only has an effect if this Session isconfigured with autocommit=True and does not already have atransaction in progress.

execution_options –

a dictionary of execution options that willbe passed to Connection.execution_options(), when theconnection is first procured only. If the connection is alreadypresent within the Session, a warning is emitted andthe arguments are ignored.

New in version 0.9.9.

See also

Setting Transaction Isolation Levels

**kw – Additional keyword arguments are sent to get_bind(),allowing additional arguments to be passed to customimplementations of get_bind().

getbind(_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 beenexplicitly bound directly to a Connection.

For a multiply-bound or unbound Session, themapper or clause arguments are used to determine theappropriate bind to return.

Note that the “mapper” argument is usually presentwhen Session.get_bind() is called via an ORMoperation such as a Session.query(), eachindividual 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, thenon the mapped class in use, then on any base classes that arepresent in the mro of the mapped class, from more specificsuperclasses to more general.

if clause given and session.binds is present,locate a bind based on Table objectsfound in the given clause present in session.binds.

if session.bind is present, return that.

if clause given, attempt to return a bindlinked to the MetaData ultimatelyassociated with the clause.

if mapper given, attempt to return a bindlinked to the MetaData ultimatelyassociated with the Table or otherselectable to which the mapper is mapped.

No bind can be found, UnboundExecutionErroris raised.

Note that the Session.get_bind() method can be overridden ona user-defined subclass of Session to provide any kindof bind resolution scheme. See the example atCustom Vertical Partitioning.

- Parameters
- 
  -

mapper – Optional mapper() mapped class or instance ofMapper. The bind can be derived from a Mapperfirst by consulting the “binds” map associated with thisSession, and secondly by consulting the MetaDataassociated with the Table to which the Mapperis mapped for a bind.

clause – A ClauseElement (i.e. select(),text(),etc.). If the mapper argument is not present or could notproduce a bind, the given expression construct will be searchedfor a bound element, typically a Table associated withbound MetaData.