fdbd928b1f
This module presents a replacement for the EngineFacade system. At the center is the oslo.db.sqlalchemy.enginefacade module, which when imported, provides decorators and context managers which perform all database and ORM connectivity functions transparently. The docstrings as well as the blueprint provide an introduction. The patch includes a refactoring of sqlalchemy/session.py into three dependent modules engines.py, orm.py and enginefacade.py. This is to maintain a non-cyclical import structure as well as to maintain the import behavior of oslo.db overall, as some projects such as glance currently have dependencies on this structure. There is also a slimming down and attempt at modernizing some very old documentation in session.py. The enginefacade system should be preferred moving forward. Implements: blueprint make-enginefacade-a-facade Change-Id: I9a3d0c26bb727eb2c0bd823b9a12fde57cc7c9c3
3.3 KiB
Usage
To use oslo.db in a project:
Session Handling
Session handling is achieved using the oslo_db.sqlalchemy.enginefacade system. This module
presents a function decorator as well as a context manager approach to
delivering .Session
as well as .Connection objects to a function or block.
Both calling styles require the use of a context object. This object may be of any class, though when used with the decorator form, requires special instrumentation.
The context manager form is as follows:
from oslo_db.sqlalchemy import enginefacade
class MyContext(object):
"User-defined context class."
def some_reader_api_function(context):
with enginefacade.reader.using(context) as session:
return session.query(SomeClass).all()
def some_writer_api_function(context, x, y):
with enginefacade.writer.using(context) as session:
session.add(SomeClass(x, y))
def run_some_database_calls():
context = MyContext()
results = some_reader_api_function(context)
some_writer_api_function(context, 5, 10)The decorator form accesses attributes off the user-defined context
directly; the context must be decorated with the oslo_db.sqlalchemy.enginefacade.transaction_context_provider
decorator. Each function must receive the context as the first
positional argument:
from oslo_db.sqlalchemy import enginefacade
@enginefacade.transaction_context_provider
class MyContext(object):
"User-defined context class."
@enginefacade.reader
def some_reader_api_function(context):
return context.session.query(SomeClass).all()
@enginefacade.writer
def some_writer_api_function(context, x, y):
context.session.add(SomeClass(x, y))
def run_some_database_calls():
context = MyContext()
results = some_reader_api_function(context)
some_writer_api_function(context, 5, 10)The scope of transaction and connectivity for both approaches is
managed transparently. The configuration for the connection comes from
the standard oslo_config.cfg.CONF collection. Additional
configurations can be established for the enginefacade using the oslo_db.sqlalchemy.enginefacade.configure function,
before any use of the database begins:
from oslo_db.sqlalchemy import enginefacade
enginefacade.configure(
sqlite_fk=True,
max_retries=5,
mysql_sql_mode='ANSI'
)Base class for models usage
from oslo.db import models
class ProjectSomething(models.TimestampMixin,
models.ModelBase):
id = Column(Integer, primary_key=True)
...DB API backend support
from oslo.config import cfg
from oslo.db import api as db_api
_BACKEND_MAPPING = {'sqlalchemy': 'project.db.sqlalchemy.api'}
IMPL = db_api.DBAPI.from_config(cfg.CONF, backend_mapping=_BACKEND_MAPPING)
def get_engine():
return IMPL.get_engine()
def get_session():
return IMPL.get_session()
# DB-API method
def do_something(somethind_id):
return IMPL.do_something(somethind_id)