OpenStack Common DB Code
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

196 lines
6.6 KiB

# Copyright 2010 United States Government as represented by the
# Administrator of the National Aeronautics and Space Administration.
# All Rights Reserved.
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""Session Handling for SQLAlchemy backend.
Recommended ways to use sessions within this framework:
* Use the ``enginefacade`` system for connectivity, session and
transaction management:
.. code-block:: python
from oslo_db.sqlalchemy import enginefacade
def get_foo(context, foo):
return (model_query(models.Foo, context.session).
def update_foo(context, id, newfoo):
(model_query(models.Foo, context.session).
update({'foo': newfoo}))
def create_foo(context, values):
foo_ref = models.Foo()
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 ``:
.. code-block:: python
def create_many_foo(context, foos):
for foo in foos:
foo_ref = models.Foo()
def update_bar(context, foo_id, newbar):
foo_ref = (model_query(models.Foo, context.session).
(model_query(models.Bar, context.session).
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:
.. code-block:: python
def update_bar(context, foo_id, newbar):
subq = (model_query(, context.session).
(model_query(models.Bar, context.session).
update({'bar': newbar}))
For reference, this emits approximately the following SQL statement:
.. code-block:: sql
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:
.. code-block:: python
def create_duplicate_foo(context):
foo1 = models.Foo()
foo2 = models.Foo() = = 1
with context.session.begin_nested():
except exception.DBDuplicateEntry as 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.
.. code-block:: python
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
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:
.. code-block:: python
class NovaBase(models.SoftDeleteMixin, models.ModelBase):
Efficient use of soft deletes:
* While there is a ``model.soft_delete()`` method, prefer
``query.soft_delete()``. Some examples:
.. code-block:: python
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).\\
if count == 0:
raise Exception("0 entries were soft deleted")
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).
if count == 0:
raise Exception("0 entries were soft deleted")
from oslo_db.sqlalchemy import enginefacade
from oslo_db.sqlalchemy import engines
from oslo_db.sqlalchemy import orm
EngineFacade = enginefacade.LegacyEngineFacade
create_engine = engines.create_engine
get_maker = orm.get_maker
Query = orm.Query
Session = orm.Session
__all__ = ["EngineFacade", "create_engine", "get_maker", "Query", "Session"]