magpie.db
=========

.. py:module:: magpie.db


Attributes
----------

.. autoapisummary::

   magpie.db.LOGGER


Functions
---------

.. autoapisummary::

   magpie.db.get_db_url
   magpie.db.get_engine
   magpie.db.get_session_factory
   magpie.db.get_tm_session
   magpie.db.get_session_from_other
   magpie.db.get_db_session_from_settings
   magpie.db.get_db_session_from_config_ini
   magpie.db.get_connected_session
   magpie.db.run_database_migration
   magpie.db.get_database_revision
   magpie.db.is_database_ready
   magpie.db.run_database_migration_when_ready
   magpie.db.set_sqlalchemy_log_level
   magpie.db.includeme


Module Contents
---------------

.. py:data:: LOGGER

.. py:function:: get_db_url(username: Optional[magpie.typedefs.Str] = None, password: Optional[magpie.typedefs.Str] = None, db_host: Optional[magpie.typedefs.Str] = None, db_port: Optional[Union[magpie.typedefs.Str, int]] = None, db_name: Optional[magpie.typedefs.Str] = None, settings: magpie.typedefs.AnySettingsContainer = None) -> magpie.typedefs.Str

   Retrieve the database connection URL with provided settings.


.. py:function:: get_engine(container: Optional[magpie.typedefs.AnySettingsContainer] = None, prefix: magpie.typedefs.Str = 'sqlalchemy.', **kwargs: Any) -> sqlalchemy.engine.base.Engine

.. py:function:: get_session_factory(engine)

   Create a new session with integrated thread-local scope for safe handling across application workers.


.. py:function:: get_tm_session(session_factory, transaction_manager)

   Get a ``sqlalchemy.orm.Session`` instance backed by a transaction.

   This function will hook the session to the transaction manager which
   will take care of committing any changes.

   - When using pyramid_tm it will automatically be committed or aborted
     depending on whether an exception is raised.

   - When using scripts you should wrap the session in a manager yourself.
     For example::

         import transaction

         engine = get_engine(settings)
         session_factory = get_session_factory(engine)
         with transaction.manager:
             db_session = get_tm_session(session_factory, transaction.manager)


.. py:function:: get_session_from_other(db_session)

.. py:function:: get_db_session_from_settings(settings: Optional[magpie.typedefs.AnySettingsContainer] = None, **kwargs: Any) -> sqlalchemy.orm.session.Session

.. py:function:: get_db_session_from_config_ini(config_ini_path, ini_main_section_name='app:magpie_app', settings_override=None)

.. py:function:: get_connected_session(request: pyramid.request.Request) -> sqlalchemy.orm.session.Session

   Retrieve the session attached to the request or recreated it to ensure it is open and within scoped transaction.


.. py:function:: run_database_migration(container: Optional[magpie.typedefs.AnySettingsContainer] = None, db_session: Optional[sqlalchemy.orm.session.Session] = None) -> None

   Runs database migration operations with :mod:`alembic`, using the provided session or a new engine connection.


.. py:function:: get_database_revision(db_session: sqlalchemy.orm.session.Session) -> magpie.typedefs.Str

   Obtains the database revision number employed by :mod:`alembic` for schema migration.


.. py:function:: is_database_ready(db_session: Optional[sqlalchemy.orm.session.Session] = None, container: Optional[magpie.typedefs.AnySettingsContainer] = None) -> bool

   Obtains the database status against expected table names to ensure it is ready for use.


.. py:function:: run_database_migration_when_ready(settings: magpie.typedefs.SettingsType, db_session: Optional[sqlalchemy.orm.session.Session] = None) -> None

   Runs db migration if requested by config and need from revisions.


.. py:function:: set_sqlalchemy_log_level(magpie_log_level: Union[magpie.typedefs.Str, int]) -> magpie.typedefs.SettingsType

   Suppresses :py:mod:`sqlalchemy` verbose logging if not in ``logging.DEBUG`` for Magpie.


.. py:function:: includeme(config)