The 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: exceptions.Exception

Error raised when a particular database backend is not available

within a test suite.

exception oslo_db.exception.CantStartEngineError

Bases: exceptions.Exception

Error raised when the enginefacade cannot start up correctly.

exception oslo_db.exception.ColumnError

Bases: exceptions.Exception

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

exception oslo_db.exception.ContextNotRequestedError

Bases: exceptions.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: oslo_db.exception.DBError

Wrapped connection specific exception.

Raised when database connection is failed.

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

Bases: oslo_db.exception.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: oslo_db.exception.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: oslo_db.exception.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: oslo_db.exception.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: oslo_utils.excutils.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: exceptions.Exception

Database unicode error.

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

message

exception oslo_db.exception.DBMigrationError(message)

Bases: oslo_db.exception.DbMigrationError

Wrapped migration specific exception.

Raised when migrations couldn’t be completed successfully.

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

Bases: oslo_db.exception.DBError

Constraint does not exist.

Parameters:

• table (str) – table name
• constraint – constraint name

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

Bases: oslo_db.exception.DBError

Table does not exist.

Parameters:table (str) – table name

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

Bases: oslo_db.exception.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.DbMigrationError(message=None)

Bases: oslo_db.exception.DBError

Wrapped migration specific exception.

Raised when migrations couldn’t be completed successfully.

exception oslo_db.exception.InvalidSortKey(key=None)

Bases: exceptions.Exception

A sort key destined for database query usage is invalid.

message

exception oslo_db.exception.NoEngineContextEstablished

Bases: exceptions.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.NotSupportedWarning

Bases: exceptions.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.exception.OsloDBDeprecationWarning

Bases: exceptions.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

exception oslo_db.exception.RetryRequest(inner_exc)

Bases: exceptions.Exception

Error raised when DB operation needs to be retried.

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