The oslo_db.sqlalchemy.enginefacade Module

class oslo_db.sqlalchemy.enginefacade.LegacyEngineFacade(sql_connection, slave_connection=None, sqlite_fk=False, autocommit=True, expire_on_commit=False, _conf=None, _factory=None, **kwargs)

Bases: object

A helper class for removing of global engine instances from oslo.db.

Deprecated since version 1.12.0: Please use oslo_db.sqlalchemy.enginefacade for new development.

As a library, oslo.db can’t decide where to store/when to create engine and sessionmaker instances, so this must be left for a target application.

On the other hand, in order to simplify the adoption of oslo.db changes, we’ll provide a helper class, which creates engine and sessionmaker on its instantiation and provides get_engine()/get_session() methods that are compatible with corresponding utility functions that currently exist in target projects, e.g. in Nova.

engine/sessionmaker instances will still be global (and they are meant to be global), but they will be stored in the app context, rather that in the oslo.db context.

Two important things to remember:

  1. An Engine instance is effectively a pool of DB connections, so it’s meant to be shared (and it’s thread-safe).
  2. A Session instance is not meant to be shared and represents a DB transactional context (i.e. it’s not thread-safe). sessionmaker is a factory of sessions.
Parameters:
  • sql_connection (string) – the connection string for the database to use
  • slave_connection (string) – the connection string for the ‘slave’ database to use. If not provided, the master database will be used for all operations. Note: this is meant to be used for offloading of read operations to asynchronously replicated slaves to reduce the load on the master database.
  • sqlite_fk (bool) – enable foreign keys in SQLite
  • autocommit (bool) – use autocommit mode for created Session instances
  • expire_on_commit (bool) – expire session objects on commit

Keyword arguments:

Parameters:
  • mysql_sql_mode – the SQL mode to be used for MySQL sessions. (defaults to TRADITIONAL)
  • idle_timeout – timeout before idle sql connections are reaped (defaults to 3600)
  • connection_debug – verbosity of SQL debugging information. -1=Off, 0=None, 100=Everything (defaults to 0)
  • max_pool_size – maximum number of SQL connections to keep open in a pool (defaults to SQLAlchemy settings)
  • max_overflow – if set, use this value for max_overflow with sqlalchemy (defaults to SQLAlchemy settings)
  • pool_timeout – if set, use this value for pool_timeout with sqlalchemy (defaults to SQLAlchemy settings)
  • sqlite_synchronous – if True, SQLite uses synchronous mode (defaults to True)
  • connection_trace – add python stack traces to SQL as comment strings (defaults to False)
  • max_retries – maximum db connection retries during startup. (setting -1 implies an infinite retry count) (defaults to 10)
  • retry_interval – interval between retries of opening a sql connection (defaults to 10)
  • thread_checkin – boolean that indicates that between each engine checkin event a sleep(0) will occur to allow other greenthreads to run (defaults to True)
classmethod from_config(conf, sqlite_fk=False, autocommit=True, expire_on_commit=False)

Initialize EngineFacade using oslo.config config instance options.

Parameters:
  • conf (oslo_config.cfg.ConfigOpts) – oslo.config config instance
  • sqlite_fk (bool) – enable foreign keys in SQLite
  • autocommit (bool) – use autocommit mode for created Session instances
  • expire_on_commit (bool) – expire session objects on commit
get_engine(use_slave=False)

Get the engine instance (note, that it’s shared).

Parameters:use_slave (bool) – if possible, use ‘slave’ database for this engine. If the connection string for the slave database wasn’t provided, ‘master’ engine will be returned. (defaults to False)
get_session(use_slave=False, **kwargs)

Get a Session instance.

Parameters:use_slave (bool) – if possible, use ‘slave’ database connection for this session. If the connection string for the slave database wasn’t provided, a session bound to the ‘master’ engine will be returned. (defaults to False)

Keyword arguments will be passed to a sessionmaker instance as is (if passed, they will override the ones used when the sessionmaker instance was created). See SQLAlchemy Session docs for details.

get_sessionmaker(use_slave=False)

Get the sessionmaker instance used to create a Session.

This can be called for those cases where the sessionmaker() is to be temporarily injected with some state such as a specific connection.

oslo_db.sqlalchemy.enginefacade.configure(**kw)

Apply configurational options to the global factory.

This method can only be called before any specific transaction-beginning methods have been called.

See also

_TransactionFactory.configure()

oslo_db.sqlalchemy.enginefacade.get_legacy_facade()

Return a LegacyEngineFacade for the global factory.

This facade will make use of the same engine and sessionmaker as this factory, however will not share the same transaction context; the legacy facade continues to work the old way of returning a new Session each time get_session() is called.

oslo_db.sqlalchemy.enginefacade.reader = <oslo_db.sqlalchemy.enginefacade._TransactionContextManager object>

The global ‘reader’ starting point.

oslo_db.sqlalchemy.enginefacade.transaction_context()

Construct a local transaction context.

oslo_db.sqlalchemy.enginefacade.transaction_context_provider(klass)

Decorate a class with session and connection attributes.

oslo_db.sqlalchemy.enginefacade.writer = <oslo_db.sqlalchemy.enginefacade._TransactionContextManager object>

The global ‘writer’ starting point.