sqlalchemy.orm.session.Session

Return True if the instance is associated with this session.

The instance may be pending or persistent within the Session for a result of True.

Undocumented

Undocumented

Construct a new Session.

See also the .sessionmaker function which is used to generate a .Session-producing callable with a given set of arguments.

Session = sessionmaker(binds={
    SomeMappedClass: create_engine('postgresql://engine1'),
    SomeDeclarativeBase: create_engine('postgresql://engine2'),
    some_mapper: create_engine('postgresql://engine3'),
    some_table: create_engine('postgresql://engine4'),
    })

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Locate an object in the identity map.

Given a primary key identity, constructs an identity key and then looks in the session's identity map. If present, the object may be run through unexpiration rules (e.g. load unloaded attributes, check if was deleted).

e.g.:

obj = session._identity_lookup(inspect(SomeClass), (1, ))

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Register all persistent objects from a flush.

This is used both for pending objects moving to the persistent state as well as already persistent objects.

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Place an object in the Session.

Its state will be persisted to the database on the next flush operation.

Repeated calls to add() will be ignored. The opposite of add() is expunge().

Begin a transaction, or nested transaction, on this .Session, if one is not already begun.

The _orm.Session object features autobegin behavior, so that normally it is not necessary to call the _orm.Session.begin method explicitly. However, it may be used in order to control the scope of when the transactional state is begun.

When used to begin the outermost transaction, an error is raised if this .Session is already inside of a transaction.

Begin a "nested" transaction on this Session, e.g. SAVEPOINT.

The target database(s) and associated drivers must support SQL SAVEPOINT for this method to function correctly.

For documentation on SAVEPOINT transactions, please see :ref:`session_begin_nested`.

Associate a _orm.Mapper or arbitrary Python class with a "bind", e.g. an _engine.Engine or _engine.Connection.

The given entity is added to a lookup used by the .Session.get_bind method.

Associate a _schema.Table with a "bind", e.g. an _engine.Engine or _engine.Connection.

The given _schema.Table is added to a lookup used by the .Session.get_bind method.

Perform a bulk insert of the given list of mapping dictionaries.

The bulk insert feature allows plain Python dictionaries to be used as the source of simple INSERT operations which can be more easily grouped together into higher performing "executemany" operations. Using dictionaries, there is no "history" or session state management features in use, reducing latency when inserting large numbers of simple rows.

The values within the dictionaries as given are typically passed without modification into Core _expression.Insert constructs, after organizing the values within them across the tables to which the given mapper is mapped.

Perform a bulk save of the given list of objects.

The bulk save feature allows mapped objects to be used as the source of simple INSERT and UPDATE operations which can be more easily grouped together into higher performing "executemany" operations; the extraction of data from the objects is also performed using a lower-latency process that ignores whether or not attributes have actually been modified in the case of UPDATEs, and also ignores SQL expressions.

The objects as given are not added to the session and no additional state is established on them. If the :paramref:`_orm.Session.bulk_save_objects.return_defaults` flag is set, then server-generated primary key values will be assigned to the returned objects, but not server side defaults; this is a limitation in the implementation. If stateful objects are desired, please use the standard _orm.Session.add_all approach or as an alternative newer mass-insert features such as :ref:`orm_dml_returning_objects`.

Perform a bulk update of the given list of mapping dictionaries.

The bulk update feature allows plain Python dictionaries to be used as the source of simple UPDATE operations which can be more easily grouped together into higher performing "executemany" operations. Using dictionaries, there is no "history" or session state management features in use, reducing latency when updating large numbers of simple rows.

Close out the transactional resources and ORM objects used by this _orm.Session.

This expunges all ORM objects associated with this _orm.Session, ends any transaction in progress and :term:`releases` any _engine.Connection objects which this _orm.Session itself has checked out from associated _engine.Engine objects. The operation then leaves the _orm.Session in a state which it may be used again.

Flush pending changes and commit the current transaction.

If no transaction is in progress, the method will first "autobegin" a new transaction and commit.

If :term:`1.x-style` use is in effect and there are currently SAVEPOINTs in progress via _orm.Session.begin_nested, the operation will release the current SAVEPOINT but not commit the outermost database transaction.

If :term:`2.0-style` use is in effect via the :paramref:`_orm.Session.future` flag, the outermost database transaction is committed unconditionally, automatically releasing any SAVEPOINTs in effect.

When using legacy "autocommit" mode, this method is only valid to call if a transaction is actually in progress, else an error is raised. Similarly, when using legacy "subtransactions", the method will instead close out the current "subtransaction", rather than the actual database transaction, if a transaction is in progress.

Return a _engine.Connection object corresponding to this .Session object's transactional state.

If this .Session is configured with autocommit=False, either the _engine.Connection corresponding to the current transaction is returned, or if no transaction is in progress, a new one is begun and the _engine.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 _engine.Connection is returned using _engine.Engine.connect on the underlying _engine.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.

Mark an instance as deleted.

The database delete operation occurs upon flush().

Associate an object with this .Session for related object loading.

Accesses of attributes mapped with _orm.relationship will attempt to load a value from the database using this .Session as the source of connectivity. The values will be loaded based on foreign key and primary key values present on this object - if not present, then those relationships will be unavailable.

The object will be attached to this session, but will not participate in any persistence operations; its state for almost all purposes will remain either "transient" or "detached", except for the case of relationship loading.

Also note that backrefs will often not work as expected. Altering a relationship-bound attribute on the target object may not fire off a backref event, if the effective value is what was already loaded from a foreign-key-holding value.

The .Session.enable_relationship_loading method is similar to the load_on_pending flag on _orm.relationship. Unlike that flag, .Session.enable_relationship_loading allows an object to remain transient while still being able to load related items.

To make a transient object associated with a .Session via .Session.enable_relationship_loading pending, add it to the .Session using .Session.add normally. If the object instead represents an existing identity in the database, it should be merged using .Session.merge.

.Session.enable_relationship_loading does not improve behavior when the ORM is used normally - object references should be constructed at the object level, not at the foreign key level, so that they are present in an ordinary way before flush() proceeds. This method is not intended for general use.

Execute a SQL expression construct.

Returns a _engine.Result object representing results of the statement execution.

E.g.:

from sqlalchemy import select
result = session.execute(
    select(User).where(User.id == 5)
)

The API contract of _orm.Session.execute is similar to that of _future.Connection.execute, the :term:`2.0 style` version of _future.Connection.

Expire the attributes on an instance.

Marks the attributes of an instance as out of date. When an expired attribute is next accessed, a query will be issued to the .Session object's current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction.

To expire all objects in the .Session simultaneously, use Session.expire_all.

The .Session object's default behavior is to expire all state whenever the Session.rollback or Session.commit methods are called, so that new state can be loaded for the new transaction. For this reason, calling Session.expire only makes sense for the specific case that a non-ORM SQL statement was emitted in the current transaction.

Expires all persistent instances within this Session.

When any attributes on a persistent instance is next accessed, a query will be issued using the .Session object's current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction.

To expire individual objects and individual attributes on those objects, use Session.expire.

The .Session object's default behavior is to expire all state whenever the Session.rollback or Session.commit methods are called, so that new state can be loaded for the new transaction. For this reason, calling Session.expire_all should not be needed when autocommit is False, assuming the transaction is isolated.

Remove the instance from this Session.

This will free all internal references to the instance. Cascading will be applied according to the expunge cascade rule.

Remove all object instances from this Session.

This is equivalent to calling expunge(obj) on all objects in this Session.

Flush all the object changes to the database.

Writes out all pending object creations, deletions and modifications to the database as INSERTs, DELETEs, UPDATEs, etc. Operations are automatically ordered by the Session's unit of work dependency solver.

Database operations will be issued in the current transactional context and do not affect the state of the transaction, unless an error occurs, in which case the entire transaction is rolled back. You may flush() as often as you like within a transaction to move changes from Python to the database's transaction buffer.

For autocommit Sessions with no active manual transaction, flush() will create a transaction on the fly that surrounds the entire set of operations into the flush.

Return an instance based on the given primary key identifier, or None if not found.

E.g.:

my_user = session.get(User, 5)

some_object = session.get(VersionedFoo, (5, 10))

some_object = session.get(
    VersionedFoo,
    {"id": 5, "version_id": 10}
)

_orm.Session.get is special in that it provides direct access to the identity map of the .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.

_orm.Session.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, ~sqlalchemy.orm.exc.ObjectDeletedError is raised.

my_object = session.get(SomeClass, 5)

my_object = session.get(SomeClass, (5, 10))

my_object = session.get(SomeClass, {"id": 5, "version_id": 10})

Return a "bind" to which this .Session is bound.

The "bind" is usually an instance of _engine.Engine, except in the case where the .Session has been explicitly bound directly to a _engine.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:

1. if mapper given and :paramref:`.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.
2. if clause given and Session.binds is present, locate a bind based on _schema.Table objects found in the given clause present in Session.binds.
3. if Session.binds is present, return that.
4. if clause given, attempt to return a bind linked to the _schema.MetaData ultimately associated with the clause.
5. if mapper given, attempt to return a bind linked to the _schema.MetaData ultimately associated with the _schema.Table or other selectable to which the mapper is mapped.
6. No bind can be found, ~sqlalchemy.exc.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 :ref:`session_custom_partitioning`.

Return the current nested transaction in progress, if any.

Return the current root transaction in progress, if any.

Return True if this _orm.Session has begun a nested transaction, e.g. SAVEPOINT.

Return True if this _orm.Session has begun a transaction.

Close this Session, using connection invalidation.

This is a variant of .Session.close that will additionally ensure that the _engine.Connection.invalidate method will be called on each _engine.Connection object that is currently in use for a transaction (typically there is only one connection unless the _orm.Session is used with multiple engines).

This can be called when the database is known to be in a state where the connections are no longer safe to be used.

Below illustrates a scenario when using gevent, which can produce Timeout exceptions that may mean the underlying connection should be discarded:

import gevent

try:
    sess = Session()
    sess.add(User())
    sess.commit()
except gevent.Timeout:
    sess.invalidate()
    raise
except:
    sess.rollback()
    raise

The method additionally does everything that _orm.Session.close does, including that all ORM objects are expunged.

Return True if the given instance has locally modified attributes.

This method retrieves the history for each instrumented attribute on the instance and performs a comparison of the current value to its previously committed value, if any.

It is in effect a more expensive and accurate version of checking for the given instance in the .Session.dirty collection; a full test for each attribute's net "dirty" status is performed.

E.g.:

return session.is_modified(someobject)

A few caveats to this method apply:

• Instances present in the .Session.dirty collection may report False when tested with this method. This is because the object may have received change events via attribute mutation, thus placing it in .Session.dirty, but ultimately the state is the same as that loaded from the database, resulting in no net change here.

• Scalar attributes may not have recorded the previously set value when a new value was applied, if the attribute was not loaded, or was expired, at the time the new value was received - in these cases, the attribute is assumed to have a change, even if there is ultimately no net change against its database value. SQLAlchemy in most cases does not need the "old" value when a set event occurs, so it skips the expense of a SQL call if the old value isn't present, based on the assumption that an UPDATE of the scalar value is usually needed, and in those few cases where it isn't, is less expensive on average than issuing a defensive SELECT.

  The "old" value is fetched unconditionally upon set only if the attribute container has the active_history flag set to True. This flag is set typically for primary key attributes and scalar object references that are not a simple many-to-one. To set this flag for any arbitrary mapped column, use the active_history argument with .column_property.

Copy the state of a given instance into a corresponding instance within this .Session.

.Session.merge examines the primary key attributes of the source instance, and attempts to reconcile it with an instance of the same primary key in the session. If not found locally, it attempts to load the object from the database based on primary key, and if none can be located, creates a new instance. The state of each attribute on the source instance is then copied to the target instance. The resulting target instance is then returned by the method; the original source instance is left unmodified, and un-associated with the .Session if not already.

This operation cascades to associated instances if the association is mapped with cascade="merge".

See :ref:`unitofwork_merging` for a detailed discussion of merging.

Prepare the current transaction in progress for two phase commit.

If no transaction is in progress, this method raises an ~sqlalchemy.exc.InvalidRequestError.

Only root transactions of two phase sessions can be prepared. If the current transaction is not such, an ~sqlalchemy.exc.InvalidRequestError is raised.

Expire and refresh attributes on the given instance.

The selected attributes will first be expired as they would when using _orm.Session.expire; then a SELECT statement will be issued to the database to refresh column-oriented attributes with the current value available in the current transaction.

_orm.relationship oriented attributes will also be immediately loaded if they were already eagerly loaded on the object, using the same eager loading strategy that they were loaded with originally. Unloaded relationship attributes will remain unloaded, as will relationship attributes that were originally lazy loaded.

Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. Refreshing attributes usually only makes sense at the start of a transaction where database rows have not yet been accessed.

Rollback the current transaction in progress.

If no transaction is in progress, this method is a pass-through.

In :term:`1.x-style` use, this method rolls back the topmost database transaction if no nested transactions are in effect, or to the current nested transaction if one is in effect.

When :term:`2.0-style` use is in effect via the :paramref:`_orm.Session.future` flag, the method always rolls back the topmost database transaction, discarding any nested transactions that may be in progress.

Execute a statement and return a scalar result.

Usage and parameters are the same as that of _orm.Session.execute; the return result is a scalar Python value.

Execute a statement and return the results as scalars.

Usage and parameters are the same as that of _orm.Session.execute; the return result is a _result.ScalarResult filtering object which will return single elements rather than _row.Row objects.