oslo_db package

Subpackages

Submodules

oslo_db.api module

Multiple DB API backend support.

A DB backend module should implement a method named ‘get_backend’ which takes no arguments. The method can return any object that implements DB API methods.

class oslo_db.api.DBAPI(backend_name, backend_mapping=None, lazy=False, **kwargs)

Bases: object

Initialize the chosen DB API backend.

After initialization API methods is available as normal attributes of DBAPI subclass. Database API methods are supposed to be called as DBAPI instance methods.

Parameters:

  • backend_name (str) – name of the backend to load

  • backend_mapping (dict) – backend name -> module/class to load mapping

  • lazy (bool) – load the DB backend lazily on the first DB API method call

  • use_db_reconnect (bool) – retry DB transactions on disconnect or not

  • retry_interval (int) – seconds between transaction retries

  • inc_retry_interval (bool) – increase retry interval or not

  • max_retry_interval (int) – max interval value between retries

  • max_retries (int) – max number of retries before an error is raised

Default backend_mapping:

None

Default lazy:

False

classmethod from_config(conf, backend_mapping=None, lazy=False)

Initialize DBAPI instance given a config instance.

Parameters:

  • conf (oslo.config.cfg.ConfigOpts) – oslo.config config instance

  • backend_mapping (dict) – backend name -> module/class to load mapping

  • lazy (bool) – load the DB backend lazily on the first DB API method call

oslo_db.api.retry_on_deadlock(f)

Retry a DB API call if Deadlock was received.

wrap_db_entry will be applied to all db.api functions marked with this decorator.

oslo_db.api.retry_on_request(f)

Retry a DB API call if RetryRequest exception was received.

wrap_db_entry will be applied to all db.api functions marked with this decorator.

oslo_db.api.safe_for_db_retry(f)

Indicate api method as safe for re-connection to database.

Database connection retries will be enabled for the decorated api method. Database connection failure can have many causes, which can be temporary. In such cases retry may increase the likelihood of connection.

Usage:

@safe_for_db_retry
def api_method(self):
    self.engine.connect()
Parameters:

f (function.) – database api method.

class oslo_db.api.wrap_db_retry(retry_interval=1, max_retries=20, inc_retry_interval=True, max_retry_interval=10, retry_on_disconnect=False, retry_on_deadlock=False, exception_checker=<function wrap_db_retry.<lambda>>, jitter=False)

Bases: object

Retry db.api methods, if db_error raised

Retry decorated db.api methods. This decorator catches db_error and retries function in a loop until it succeeds, or until maximum retries count will be reached.

Keyword arguments:

Parameters:

  • retry_interval (int or float) – seconds between transaction retries

  • max_retries (int) – max number of retries before an error is raised

  • inc_retry_interval (bool) – determine increase retry interval or not

  • max_retry_interval (int or float) – max interval value between retries

  • exception_checker (callable) – checks if an exception should trigger a retry

  • jitter (bool) – determine increase retry interval use jitter or not, jitter is always interpreted as True for a DBDeadlockError

oslo_db.exception module

DB related custom exceptions.

Custom exceptions intended to determine the causes of specific database errors. This module provides more generic exceptions than the database-specific driver libraries, and so users of oslo.db can catch these no matter which database the application is using. Most of the exceptions are wrappers. Wrapper exceptions take an original exception as positional argument and keep it for purposes of deeper debug.

Example:

try:
    statement(arg)
except sqlalchemy.exc.OperationalError as e:
    raise DBDuplicateEntry(e)

This is useful to determine more specific error cases further at execution, when you need to add some extra information to an error message. Wrapper exceptions takes care about original error message displaying to not to loose low level cause of an error. All the database api exceptions wrapped into the specific exceptions provided belove.

Please use only database related custom exceptions with database manipulations with try/except statement. This is required for consistent handling of database errors.

exception oslo_db.exception.BackendNotAvailable

Bases: Exception

Error raised when a particular database backend is not available

within a test suite.

exception oslo_db.exception.CantStartEngineError

Bases: Exception

Error raised when the enginefacade cannot start up correctly.

exception oslo_db.exception.ColumnError

Bases: Exception

Error raised when no column or an invalid column is found.

exception oslo_db.exception.ContextNotRequestedError

Bases: AttributeError

Error raised when requesting a not-setup enginefacade attribute.

This applies to the session and connection attributes of a user-defined context and/or RequestContext object, when they are accessed within the scope of an enginefacade decorator or context manager, but the context has not requested that attribute (e.g. like “with enginefacade.connection.using(context)” and “context.session” is requested).

exception oslo_db.exception.DBConnectionError(inner_exception=None, cause=None)

Bases: DBError

Wrapped connection specific exception.

Raised when database connection is failed.

exception oslo_db.exception.DBConstraintError(table, check_name, inner_exception=None)

Bases: DBError

Check constraint fails for column error.

Raised when made an attempt to write to a column a value that does not satisfy a CHECK constraint.

Parameters:

  • table (str) – the table name for which the check fails

  • check_name (str) – the table of the check that failed to be satisfied

exception oslo_db.exception.DBDataError(inner_exception=None, cause=None)

Bases: DBError

Raised for errors that are due to problems with the processed data.

E.g. division by zero, numeric value out of range, incorrect data type, etc

exception oslo_db.exception.DBDeadlock(inner_exception=None)

Bases: DBError

Database dead lock error.

Deadlock is a situation that occurs when two or more different database sessions have some data locked, and each database session requests a lock on the data that another, different, session has already locked.

exception oslo_db.exception.DBDuplicateEntry(columns=None, inner_exception=None, value=None)

Bases: DBError

Duplicate entry at unique column error.

Raised when made an attempt to write to a unique column the same entry as existing one. :attr: columns available on an instance of the exception and could be used at error handling:

try:
    instance_type_ref.save()
except DBDuplicateEntry as e:
    if 'colname' in e.columns:
        # Handle error.
Parameters:

  • columns (list) – a list of unique columns have been attempted to write a duplicate entry.

  • value – a value which has been attempted to write. The value will be None, if we can’t extract it for a particular database backend. Only MySQL and PostgreSQL 9.x are supported right now.

exception oslo_db.exception.DBError(inner_exception=None, cause=None)

Bases: CausedByException

Base exception for all custom database exceptions.

Parameters:

inner_exception – an original exception which was wrapped with DBError or its subclasses.

exception oslo_db.exception.DBInvalidUnicodeParameter

Bases: Exception

Database unicode error.

Raised when unicode parameter is passed to a database without encoding directive.

exception oslo_db.exception.DBMigrationError(message)

Bases: DBError

Wrapped migration specific exception.

Raised when migrations couldn’t be completed successfully.

exception oslo_db.exception.DBNonExistentConstraint(table, constraint, inner_exception=None)

Bases: DBError

Constraint does not exist.

Parameters:

  • table (str) – table name

  • constraint – constraint name

exception oslo_db.exception.DBNonExistentDatabase(database, inner_exception=None)

Bases: DBError

Database does not exist.

Parameters:

database (str) – database name

exception oslo_db.exception.DBNonExistentTable(table, inner_exception=None)

Bases: DBError

Table does not exist.

Parameters:

table (str) – table name

exception oslo_db.exception.DBNotSupportedError(inner_exception=None, cause=None)

Bases: DBError

Raised when a database backend has raised sqla.exc.NotSupportedError

exception oslo_db.exception.DBReferenceError(table, constraint, key, key_table, inner_exception=None)

Bases: DBError

Foreign key violation error.

Parameters:

  • table (str) – a table name in which the reference is directed.

  • constraint (str) – a problematic constraint name.

  • key (str) – a broken reference key name.

  • key_table (str) – a table name which contains the key.

exception oslo_db.exception.InvalidSortKey(key=None)

Bases: Exception

A sort key destined for database query usage is invalid.

exception oslo_db.exception.NoEngineContextEstablished

Bases: AttributeError

Error raised for enginefacade attribute access with no context.

This applies to the session and connection attributes of a user-defined context and/or RequestContext object, when they are accessed outside of the scope of an enginefacade decorator or context manager.

The exception is a subclass of AttributeError so that normal Python missing attribute behaviors are maintained, such as support for getattr(context, 'session', None).

exception oslo_db.exception.RetryRequest(inner_exc)

Bases: Exception

Error raised when DB operation needs to be retried.

That could be intentionally raised by the code without any real DB errors.

oslo_db.options module

oslo_db.options.list_opts()

Returns a list of oslo.config options available in the library.

The returned list includes all oslo.config options which may be registered at runtime by the library.

Each element of the list is a tuple. The first element is the name of the group under which the list of elements in the second element will be registered. A group name of None corresponds to the [DEFAULT] group in config files.

The purpose of this is to allow tools like the Oslo sample config file generator to discover the options exposed to users by this library.

Returns:

a list of (group_name, opts) tuples

oslo_db.options.set_defaults(conf, connection=None, max_pool_size=None, max_overflow=None, pool_timeout=None)

Set defaults for configuration variables.

Overrides default options values.

Parameters:

  • conf (oslo.config.cfg.ConfigOpts instance.) – Config instance specified to set default options in it. Using of instances instead of a global config object prevents conflicts between options declaration.

  • connection (str) – SQL connection string. Valid SQLite URL forms are: * sqlite:///:memory: (or, sqlite://) * sqlite:///relative/path/to/file.db * sqlite:////absolute/path/to/file.db

  • max_pool_size (int) – maximum connections pool size. The size of the pool to be maintained, defaults to 5. This is the largest number of connections that will be kept persistently in the pool. Note that the pool begins with no connections; once this number of connections is requested, that number of connections will remain.

  • max_overflow (int) – The maximum overflow size of the pool. When the number of checked-out connections reaches the size set in pool_size, additional connections will be returned up to this limit. When those additional connections are returned to the pool, they are disconnected and discarded. It follows then that the total number of simultaneous connections the pool will allow is pool_size + max_overflow, and the total number of “sleeping” connections the pool will allow is pool_size. max_overflow can be set to -1 to indicate no overflow limit; no limit will be placed on the total number of concurrent connections. Defaults to 10, will be used if value of the parameter in None.

  • pool_timeout (int) – The number of seconds to wait before giving up on returning a connection. Defaults to 30, will be used if value of the parameter is None.

Default max_pool_size:

5

Default max_overflow:

None

Default pool_timeout:

None

oslo_db.warning module

Custom warnings.

exception oslo_db.warning.NotSupportedWarning

Bases: Warning

Warn that an argument or call that was passed is not supported.

This subclasses Warning so that it can be filtered as a distinct category.

See also

https://docs.python.org/2/library/warnings.html

exception oslo_db.warning.OsloDBDeprecationWarning

Bases: DeprecationWarning

Issued per usage of a deprecated API.

This subclasses DeprecationWarning so that it can be filtered as a distinct category.

See also

https://docs.python.org/2/library/warnings.html

Module contents