The oslo_db.sqlalchemy.session Module

The oslo_db.sqlalchemy.session Module

Session Handling for SQLAlchemy backend.

Recommended ways to use sessions within this framework:

  • Use the enginefacade system for connectivity, session and transaction management:

    from oslo_db.sqlalchemy import enginefacade
    
    @enginefacade.reader
    def get_foo(context, foo):
        return (model_query(models.Foo, context.session).
                filter_by(foo=foo).
                first())
    
    @enginefacade.writer
    def update_foo(context, id, newfoo):
        (model_query(models.Foo, context.session).
                filter_by(id=id).
                update({'foo': newfoo}))
    
    @enginefacade.writer
    def create_foo(context, values):
        foo_ref = models.Foo()
        foo_ref.update(values)
        foo_ref.save(context.session)
        return foo_ref
    

    In the above system, transactions are committed automatically, and are shared among all dependent database methods. Ensure that methods which “write” data are enclosed within @writer blocks.

    Note

    Statements in the session scope will not be automatically retried.

  • If you create models within the session, they need to be added, but you do not need to call model.save():

    @enginefacade.writer
    def create_many_foo(context, foos):
        for foo in foos:
            foo_ref = models.Foo()
            foo_ref.update(foo)
            context.session.add(foo_ref)
    
    @enginefacade.writer
    def update_bar(context, foo_id, newbar):
        foo_ref = (model_query(models.Foo, context.session).
                    filter_by(id=foo_id).
                    first())
        (model_query(models.Bar, context.session).
                    filter_by(id=foo_ref['bar_id']).
                    update({'bar': newbar}))
    

    The two queries in update_bar can alternatively be expressed using a single query, which may be more efficient depending on scenario:

    @enginefacade.writer
    def update_bar(context, foo_id, newbar):
        subq = (model_query(models.Foo.id, context.session).
                filter_by(id=foo_id).
                limit(1).
                subquery())
        (model_query(models.Bar, context.session).
                filter_by(id=subq.as_scalar()).
                update({'bar': newbar}))
    

    For reference, this emits approximately the following SQL statement:

    UPDATE bar SET bar = '${newbar}'
        WHERE id=(SELECT bar_id FROM foo WHERE id = '${foo_id}' LIMIT 1);
    

    Note

    create_duplicate_foo is a trivially simple example of catching an exception while using a savepoint. Here we create two duplicate instances with same primary key, must catch the exception out of context managed by a single session:

    @enginefacade.writer
    def create_duplicate_foo(context):
        foo1 = models.Foo()
        foo2 = models.Foo()
        foo1.id = foo2.id = 1
        try:
            with context.session.begin_nested():
                session.add(foo1)
                session.add(foo2)
        except exception.DBDuplicateEntry as e:
            handle_error(e)
    
  • The enginefacade system eliminates the need to decide when sessions need to be passed between methods. All methods should instead share a common context object; the enginefacade system will maintain the transaction across method calls.

    @enginefacade.writer
    def myfunc(context, foo):
        # do some database things
        bar = _private_func(context, foo)
        return bar
    
    def _private_func(context, foo):
        with enginefacade.using_writer(context) as session:
            # do some other database things
            session.add(SomeObject())
        return bar
    
  • Avoid with_lockmode('UPDATE') when possible.

    FOR UPDATE is not compatible with MySQL/Galera. Instead, an “opportunistic” approach should be used, such that if an UPDATE fails, the entire transaction should be retried. The @wrap_db_retry decorator is one such system that can be used to achieve this.

Enabling soft deletes:

  • To use/enable soft-deletes, SoftDeleteMixin may be used. For example:

    class NovaBase(models.SoftDeleteMixin, models.ModelBase):
        pass
    

Efficient use of soft deletes:

  • While there is a model.soft_delete() method, prefer query.soft_delete(). Some examples:

    @enginefacade.writer
    def soft_delete_bar(context):
        # synchronize_session=False will prevent the ORM from attempting
        # to search the Session for instances matching the DELETE;
        # this is typically not necessary for small operations.
        count = model_query(BarModel, context.session).\
            find(some_condition).soft_delete(synchronize_session=False)
        if count == 0:
            raise Exception("0 entries were soft deleted")
    
    @enginefacade.writer
    def complex_soft_delete_with_synchronization_bar(context):
        # use synchronize_session='evaluate' when you'd like to attempt
        # to update the state of the Session to match that of the DELETE.
        # This is potentially helpful if the operation is complex and
        # continues to work with instances that were loaded, though
        # not usually needed.
        count = (model_query(BarModel, context.session).
                    find(some_condition).
                    soft_delete(synchronize_session='evaulate'))
        if count == 0:
            raise Exception("0 entries were soft deleted")
    
oslo_db.sqlalchemy.session.EngineFacade

alias of LegacyEngineFacade

oslo_db.sqlalchemy.session.create_engine(sql_connection, sqlite_fk=False, mysql_sql_mode=None, mysql_enable_ndb=False, idle_timeout=3600, connection_debug=0, max_pool_size=None, max_overflow=None, pool_timeout=None, sqlite_synchronous=True, connection_trace=False, max_retries=10, retry_interval=10, thread_checkin=True, logging_name=None, json_serializer=None, json_deserializer=None)

Return a new SQLAlchemy engine.

oslo_db.sqlalchemy.session.get_maker(engine, autocommit=True, expire_on_commit=False)

Return a SQLAlchemy sessionmaker using the given engine.

class oslo_db.sqlalchemy.session.Query(entities, session=None)

Bases: sqlalchemy.orm.query.Query

Subclass of sqlalchemy.query with soft_delete() method.

soft_delete(synchronize_session='evaluate')
update_on_match(specimen, surrogate_key, values, **kw)

Emit an UPDATE statement matching the given specimen.

This is a method-version of oslo_db.sqlalchemy.update_match.update_on_match(); see that function for usage details.

update_returning_pk(values, surrogate_key)

Perform an UPDATE, returning the primary key of the matched row.

This is a method-version of oslo_db.sqlalchemy.update_match.update_returning_pk(); see that function for usage details.

class oslo_db.sqlalchemy.session.Session(bind=None, autoflush=True, expire_on_commit=True, _enable_transaction_accounting=True, autocommit=False, twophase=False, weak_identity_map=True, binds=None, extension=None, info=None, query_cls=<class 'sqlalchemy.orm.query.Query'>)

Bases: sqlalchemy.orm.session.Session

oslo.db-specific Session subclass.

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.