The nova.openstack.common.db.sqlalchemy.session Module

Session Handling for SQLAlchemy backend.

Initializing:

• Call set_defaults with the minimal of the following kwargs:

  sql_connection, sqlite_db

  Example:

  session.set_defaults(sql_connection=”sqlite:///var/lib/nova/sqlite.db”,

  sqlite_db=”/var/lib/nova/sqlite.db”)

Recommended ways to use sessions within this framework:

• Don’t use them explicitly; this is like running with AUTOCOMMIT=1. model_query() will implicitly use a session when called without one supplied. This is the ideal situation because it will allow queries to be automatically retried if the database connection is interrupted.

  Note: Automatic retry will be enabled in a future patch.

  It is generally fine to issue several queries in a row like this. Even though they may be run in separate transactions and/or separate sessions, each one will see the data from the prior calls. If needed, undo- or rollback-like functionality should be handled at a logical level. For an example, look at the code around quotas and reservation_rollback().

  Examples:

  def get_foo(context, foo):

  return model_query(context, models.Foo). filter_by(foo=foo). first()

  def update_foo(context, id, newfoo):

  model_query(context, models.Foo). filter_by(id=id). update({‘foo’: newfoo})

  def create_foo(context, values):

  foo_ref = models.Foo() foo_ref.update(values) foo_ref.save() return foo_ref

• Within the scope of a single method, keeping all the reads and writes within the context managed by a single session. In this way, the session’s __exit__ handler will take care of calling flush() and commit() for you. If using this approach, you should not explicitly call flush() or commit(). Any error within the context of the session will cause the session to emit a ROLLBACK. If the connection is dropped before this is possible, the database will implicitly rollback the transaction.

  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()

  def create_many_foo(context, foos):

  session = get_session() with session.begin():

  for foo in foos:

  foo_ref = models.Foo() foo_ref.update(foo) session.add(foo_ref)

  def update_bar(context, foo_id, newbar):

  session = get_session() with session.begin():

  foo_ref = model_query(context, models.Foo, session). filter_by(id=foo_id). first() model_query(context, models.Bar, session). filter_by(id=foo_ref[‘bar_id’]). update({‘bar’: newbar})

  Note: update_bar is a trivially simple example of using “with session.begin”. Whereas create_many_foo is a good example of when a transaction is needed, it is always best to use as few queries as possible. The two queries in update_bar can be better expressed using a single query which avoids the need for an explicit transaction. It can be expressed like so:

  def update_bar(context, foo_id, newbar):

  subq = model_query(context, models.Foo.id). filter_by(id=foo_id). limit(1). subquery() model_query(context, models.Bar). filter_by(id=subq.as_scalar()). update({‘bar’: newbar})

  For reference, this emits approximagely the following SQL statement:

  UPDATE bar SET bar = ${newbar}

  WHERE id=(SELECT bar_id FROM foo WHERE id = ${foo_id} LIMIT 1);

• Passing an active session between methods. Sessions should only be passed to private methods. The private method must use a subtransaction; otherwise SQLAlchemy will throw an error when you call session.begin() on an existing transaction. Public methods should not accept a session parameter and should not be involved in sessions within the caller’s scope.

  Note that this incurs more overhead in SQLAlchemy than the above means due to nesting transactions, and it is not possible to implicitly retry failed database operations when using this approach.

  This also makes code somewhat more difficult to read and debug, because a single database transaction spans more than one method. Error handling becomes less clear in this situation. When this is needed for code clarity, it should be clearly documented.

  def myfunc(foo):

  session = get_session() with session.begin():

  # do some database things bar = _private_func(foo, session)

  return bar

  def _private_func(foo, session=None):

  if not session:

  session = get_session()

  with session.begin(subtransaction=True):

  # do some other database things

  return bar

There are some things which it is best to avoid:

• Don’t keep a transaction open any longer than necessary.

  This means that your “with session.begin()” block should be as short as possible, while still containing all the related calls for that transaction.

• Avoid “with_lockmode(‘UPDATE’)” when possible.

  In MySQL/InnoDB, when a “SELECT ... FOR UPDATE” query does not match any rows, it will take a gap-lock. This is a form of write-lock on the “gap” where no rows exist, and prevents any other writes to that space. This can effectively prevent any INSERT into a table by locking the gap at the end of the index. Similar problems will occur if the SELECT FOR UPDATE has an overly broad WHERE clause, or doesn’t properly use an index.

  One idea proposed at ODS Fall ‘12 was to use a normal SELECT to test the number of rows matching a query, and if only one row is returned, then issue the SELECT FOR UPDATE.

  The better long-term solution is to use INSERT .. ON DUPLICATE KEY UPDATE. However, this can not be done until the “deleted” columns are removed and proper UNIQUE constraints are added to the tables.

Enabling soft deletes:

• To use/enable soft-deletes, the SoftDeleteMixin must be added to your model class. For example:

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

  pass

Efficient use of soft deletes:

• There are two possible ways to mark a record as deleted:

  model.soft_delete() and query.soft_delete().

  model.soft_delete() method works with single already fetched entry. query.soft_delete() makes only one db request for all entries that correspond to query.

• In almost all cases you should use query.soft_delete(). Some examples:

  def soft_delete_bar():

  count = model_query(BarModel).find(some_condition).soft_delete() if count == 0:

  raise Exception(“0 entries were soft deleted”)

  def complex_soft_delete_with_synchronization_bar(session=None):

  if session is None:

  session = get_session()

  with session.begin(subtransactions=True):

  count = model_query(BarModel). find(some_condition). soft_delete(synchronize_session=True)

  # Here synchronize_session is required, because we # don’t know what is going on in outer session.

  if count == 0:

  raise Exception(“0 entries were soft deleted”)

• There is only one situation where model.soft_delete() is appropriate: when you fetch a single record, work with it, and mark it as deleted in the same transaction.

  def soft_delete_bar_model():

  session = get_session() with session.begin():

  bar_ref = model_query(BarModel).find(some_condition).first() # Work with bar_ref bar_ref.soft_delete(session=session)

  However, if you need to work with all entries that correspond to query and then soft delete them you should use query.soft_delete() method:

  def soft_delete_multi_models():

  session = get_session() with session.begin():

  query = model_query(BarModel, session=session). find(some_condition) model_refs = query.all() # Work with model_refs query.soft_delete(synchronize_session=False) # synchronize_session=False should be set if there is no outer # session and these entries are not used after this.

  When working with many rows, it is very important to use query.soft_delete, which issues a single query. Using model.soft_delete(), as in the following example, is very inefficient.

  for bar_ref in bar_refs:

  bar_ref.soft_delete(session=session)

  # This will produce count(bar_refs) db requests.

class Query(entities, session=None)

Bases: sqlalchemy.orm.query.Query

Subclass of sqlalchemy.query with soft_delete() method.

soft_delete(synchronize_session='evaluate')

class 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, query_cls=<class 'sqlalchemy.orm.query.Query'>)

Bases: sqlalchemy.orm.session.Session

Custom Session class to avoid SqlAlchemy Session monkey patching.

execute(*args, **kwargs)

flush(*args, **kwargs)

query(*args, **kwargs)

add_regexp_listener(dbapi_con, con_record)

Add REGEXP function to sqlite connections.

create_engine(sql_connection)

Return a new SQLAlchemy engine.

get_engine()

Return a SQLAlchemy engine.

get_maker(engine, autocommit=True, expire_on_commit=False)

Return a SQLAlchemy sessionmaker using the given engine.

get_session(autocommit=True, expire_on_commit=False)

Return a SQLAlchemy session.

greenthread_yield(dbapi_con, con_record)

Ensure other greenthreads get a chance to execute by forcing a context switch. With common database backends (eg MySQLdb and sqlite), there is no implicit yield caused by network I/O since they are implemented by C libraries that eventlet cannot monkey patch.

is_db_connection_error(args)

Return True if error in connecting to db.

patch_mysqldb_with_stacktrace_comments()

Adds current stack trace as a comment in queries by patching MySQLdb.cursors.BaseCursor._do_query.

ping_listener(dbapi_conn, connection_rec, connection_proxy)

Ensures that MySQL connections checked out of the pool are alive.

Borrowed from: http://groups.google.com/group/sqlalchemy/msg/a4ce563d802c929f

raise_if_deadlock_error(operational_error, engine_name)

Raise DBDeadlock exception if OperationalError contains a Deadlock condition.

raise_if_duplicate_entry_error(integrity_error, engine_name)

In this function will be raised DBDuplicateEntry exception if integrity error wrap unique constraint violation.

set_defaults(sql_connection, sqlite_db)

Set defaults for configuration variables.

synchronous_switch_listener(dbapi_conn, connection_rec)

Switch sqlite connections to non-synchronous mode.

wrap_db_error(f)