A brief overview of what EngineFacade is and why consuming projects in OpenStack should care.

1. Switching to the new EngineFacade
by Roman Podoliaka
@rpodoliaka
irc: rpodolyaka
rpodolyaka@mirantis.com
slides: http://podoliaka.org/talks/

2. The new EngineFacade
spec: https://specs.openstack.org/openstack/oslo­
specs/specs/kilo/make­enginefacade­a­facade.html
implemented by zzzeek (Mike Bayer) in Liberty (oslo.db >=
1.12.0)
a new clean API for using of oslo.db
thread­safe initialization
declarative management of session / connection scope
easier offloading of read­only transactions to
asynchronous replicas

3. "old" EngineFacade: thread­safe initialization is left up
to users
_ENGINE_FACADE = None
_LOCK = threading.Lock()
def _create_facade_lazily():
global _LOCK, _ENGINE_FACADE
if _ENGINE_FACADE is None:
with _LOCK:
if _ENGINE_FACADE is None:
_ENGINE_FACADE = db_session.EngineFacade.from_
return _ENGINE_FACADE

4. "new" EngineFacade: lazy thread­safe initialization
from oslo.db import enginefacade as sql
@sql.reader
def some_api_method(context):
# work with context.session
@sql.writer
def some_other_api_method(context):
# work with context.session

5. "new" EngineFacade: multiple instances of
EngineFacade
main_context_manager = sql.transaction_context()
api_context_manager = sql.transaction_context()

6. "new" EngineFacade: project specific configuration
context_manager = enginefacade.transaction_context()
context_manager.configure(sqlite_fk=True)
context_manager.append_on_engine_create(set_hook)

7. "old" EngineFacade: get_session() boilerplate
@require_context
@handle_db_data_error
def snapshot_create(context, values):
values['snapshot_metadata'] =
_metadata_refs(values.get('metadata'),
models.SnapshotMetadata)
if not values.get('id'):
values['id'] = str(uuid.uuid4())
session = get_session()
with session.begin():
snapshot_ref = models.Snapshot()
snapshot_ref.update(values)
session.add(snapshot_ref)
return _snapshot_get(context, values['id'],
session=session)

8. "old" EngineFacade: private DB API functions
@require_context
def _snapshot_metadata_get(context, snapshot_id,
session=None):
rows = _snapshot_metadata_get_query(
context,snapshot_id, session).all()
result = {}
for row in rows:
result[row['key']] = row['value']
return result

9. "new" EngineFacade: session scope is managed
declaratively
@main_context_manager.writer
def quota_destroy_all_by_project_and_user(context,
project_id,
user_id):
model_query(context, models.ProjectUserQuota,
read_deleted="no").
filter_by(project_id=project_id).
filter_by(user_id=user_id).
soft_delete(synchronize_session=False)

10. What projects are already using the
new EngineFacade?
Nova
Neutron
Ironic
Keystone
...

11. Need help?
Slides: http://podoliaka.org/talks/
Bugs: https://bugs.launchpad.net/oslo.db
Questions:
IRC
#openstack­oslo at freenode
zzzeek (Mike Bayer)
rpodolyaka (Roman Podoliaka)
ML
http://lists.openstack.org/cgi­
bin/mailman/listinfo/openstack­dev
tag with [oslo][db]