Use the enginefacade from oslo_db

Implement the new oslo.db enginefacade interface described here:

Problem description

The linked oslo.db spec contains the details of the proposal, including its general advantages to all projects. In summary, we transparently track database transactions using the cinder.RequestContext object. This means that if there is already a transaction in progress we will use it by default, only creating a separate transaction if explicitly requested.

Use Cases

These changes will only affect developers.

  • Allow a class of database races to be fixed

Cinder currently only exposes db transactions in cinder/db/sqlalchemy/, which means that every db api call is in its own transaction. Although this will remain the same initially, the new interface allows a caller to extend a transaction across several db api calls if they wish. This will enable callers who need these to be atomic to achieve this, which includes the save operation on several Cinder objects.

  • Reduce connection load on the database

Many database api calls currently create several separate database connections, which increases load on the database. By reducing these to a single connection, load on the db will be decreased.

  • Improve atomicity of API calls

By ensuring that database api calls use a single transaction, we fix a class of bug where failure can leave a partial result.

  • Make greater use of slave databases for read-only transactions

The new api marks sections of code as either readers or writers, and enforces this separation. This allows us to automatically use a slave database connection for all read-only transactions. It is currently only used when explicitly requested in code.

Proposed change

  • Decorate the cinder.RequestContext class

cinder.RequestContext is annotated with the @enginefacade.transaction_context_provider decorator. This adds several code hooks which provide access to the transaction context via the cinder.RequestContext object, including attributes ‘session’, ‘connection’, ‘transaction’.

  • Ensure that all database apis use context session

Use context session in cinder.db.sqlalchemy.api.model_query().

  • Update database apis incrementally

Individual calls will be annotated as either readers or writers. Existing transaction management will be replaced.

Database apis will be updated in batches, by function. For example, Volume apis, Snapshot apis, Quota apis. Calls into apis which have not been upgraded yet will continue to explicitly pass the session or connection object.


Alternatives were examined during the design of the oslo.db code. The goal of this change is to implement a solution which is common across OpenStack projects.

Data model impact


REST API impact


Security impact


Notifications impact


Other end user impact


Performance Impact

By reducing connection load on the database, the change is expected to provide a small performance improvement. However, the primary purpose is correctness.

Other deployer impact


Developer impact

The initial phase of this work will be to implement the new engine facade in cinder/db/sqlalchemy/ only. Callers will not have to consider transaction context if they do not currently do so, as it will be created and destroyed automatically.

This change will allow developers to explicitly extend database transaction context to cover several database calls. This allows the caller to make multiple database changes atomically.



Primary assignee:

Hanxi_Liu <>

Work Items

  • Enable use of the new api in Cinder

  • Migrate api bundles along functional lines:
    • Backup, BackupMetadata

    • Cluster

    • ConsistencyGroup, Cgsnapshot

    • DriverInitiatorData

    • Encryption

    • Group, GroupSnapshot, GroupTypes, GroupTypeSpecs, GroupTypeProjects, GroupVolumeTypeMapping

    • ImageVolumeCacheEntry

    • Message

    • QualityOfServiceSpecs

    • Quota, QuotaClass, QuotaUsage, Reservation

    • Service

    • Snapshot, SnapshotMetadata

    • Transfer

    • VolumeAttachment, AttachmentSpecs

    • Volume, VolumeMetadata, VolumeAdminMetadata, VolumeGlanceMetadata

    • VolumeTypes, VolumeTypeProjects, VolumeTypeExtraSpecs


A version of oslo.db including the new enginefacade api:


This change is intended to have no immediate functional impact. The current tests should continue to pass.

Documentation Impact



  • Implement the oslo.db enginefacade interface described here:

  • Use the new oslo_db enginefacade in Nova:

  • Use the new oslo_db enginefacade in Neutron: