2d4fdbed56
There's no oslo_db.migration module. It's an entrypoint group name. Therefore it should not be using :mod:. Change-Id: I14f26c1a9ae1bd6b5b1154b3f49eb9e1518cafc3
147 lines
3.7 KiB
ReStructuredText
147 lines
3.7 KiB
ReStructuredText
=======
|
|
Usage
|
|
=======
|
|
|
|
To use oslo.db in a project:
|
|
|
|
Session Handling
|
|
================
|
|
|
|
Session handling is achieved using the :mod:`oslo_db.sqlalchemy.enginefacade`
|
|
system. This module presents a function decorator as well as a
|
|
context manager approach to delivering :class:`.Session` as well as
|
|
:class:`.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:
|
|
|
|
.. code:: python
|
|
|
|
|
|
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
|
|
:func:`oslo_db.sqlalchemy.enginefacade.transaction_context_provider`
|
|
decorator. Each function must receive the context as the first
|
|
positional argument:
|
|
|
|
.. code:: python
|
|
|
|
|
|
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)
|
|
|
|
.. note:: The ``context.session`` and ``context.connection`` attributes
|
|
must be accessed within the scope of an appropriate writer/reader block
|
|
(either the decorator or contextmanager approach). An AttributeError is
|
|
raised otherwise.
|
|
|
|
|
|
The scope of transaction and connectivity for both approaches is managed
|
|
transparently. The configuration for the connection comes from the standard
|
|
:obj:`oslo_config.cfg.CONF` collection. Additional configurations can be
|
|
established for the enginefacade using the
|
|
:func:`oslo_db.sqlalchemy.enginefacade.configure` function, before any use of
|
|
the database begins:
|
|
|
|
.. code:: python
|
|
|
|
from oslo_db.sqlalchemy import enginefacade
|
|
|
|
enginefacade.configure(
|
|
sqlite_fk=True,
|
|
max_retries=5,
|
|
mysql_sql_mode='ANSI'
|
|
)
|
|
|
|
|
|
Base class for models usage
|
|
===========================
|
|
|
|
.. code:: python
|
|
|
|
from oslo.db import models
|
|
|
|
|
|
class ProjectSomething(models.TimestampMixin,
|
|
models.ModelBase):
|
|
id = Column(Integer, primary_key=True)
|
|
...
|
|
|
|
|
|
DB API backend support
|
|
======================
|
|
|
|
.. code:: python
|
|
|
|
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)
|
|
|
|
DB migration extensions
|
|
=======================
|
|
|
|
Available extensions for `oslo_db.migration`.
|
|
|
|
.. list-plugins:: oslo.db.migration
|
|
:detailed:
|