5.1.2. Database API¶

Contains documentation for database, which contains all the model classes for allowing the API to interact with the database

5.1.2.1. Database Models

5.1.2.1.1. Projects

5.1.2.1.2. Users

5.1.2.2. Database Management API¶

Contains API documentation for the database schema, session management, and database version management

5.1.2.2.1. ContextManagedSession¶

Contains classes related to session management with the DB.

class database.sessions.ContextManagedSession(bind=None, autoflush=True, expire_on_commit=True, _enable_transaction_accounting=True, autocommit=False, twophase=False, weak_identity_map=True, binds=None, extension=None, info=None, query_cls=<class 'sqlalchemy.orm.query.Query'>)[source]¶

An extension to sqlalchemy.orm.Session that allows the session to be run using a with statement, committing all changes on an error-free exit from the context manager.

This class also allows deep copies of itself to be injected dynamically into function arguments, when employed as a decorator.

Note

In order to make the best use of ContextManagedSession, it is recommended that this class is first instantiated in a module-level scope, with its bind (i.e. the SQLAlchemy engine or connection to which the session is bound), declared in as global a scope as possible. In particular, engines should be declared as globally as possible in order to maximize the efficiency of SQLAlchemy’s connection pooling features.

The module-level instantiation is then used as a master from which copies are created as needed.

** Example **

The following example shows how to use the session as both a context manager and a decorator

import engine # import the DB engine from somewhere else if needed

session = ContextManagedSession(bind=engine)

@session()
def do_something(session):
    session.query(something)

def do_something_context_managed():

    with session() as new_session:
        new_session.query(something)

__call__(f=None)[source]¶

Returns itself, provided that the argument f is not a callable function. (i.e., it does not have a __call__ method defined)

Parameters:	f (function or None) – The function to be decorated. If no function is provided, then f is `None`.
Returns:	A deep copy of this session, or a decorator function that can then inject arguments dynamically into the function to be decorated.
Return type:	`ContextManagedSession` or a function

__enter__()[source]¶

Magic method that opens a new context for the session, returning a deep copy of the session to use in the new context.

Returns:	A deep copy of `self`
Return type:	`ContextManagedSession`

__exit__(exc_type, exc_val, _)[source]¶

Magic method that is responsible for exiting the context created in ContextManagedSession.__enter__(); running the required clean-up logic in order to flush changes made in the session to the database.

If there are no exceptions thrown in the ContextManagedSession‘s context, it is assumed that the code inside the context completed successfully. In this case, the changes made to the database in this session will be committed.

If an exception was thrown in this context, then the database will be rolled back to the state before any logic inside the context manager will be executed.

The arguments taken into this method are the standard arguments taken into an __exit__ method.

The last argument _ is used as a placeholder for the stack trace of the exception thrown in the context. This parameter is currently not used in this method, as re-throwing an exception prepends the stack trace of the exception prior to re-throw into the exception. Python is awesome this way :)!

Parameters:	exc_type (type) – The class of exception that was thrown in the context. This is `None` if no exception was thrown exc_val (exc_type) – The particular instance of the exception that was thrown during execution in the context. After the session is rolled back, this exception is re-thrown.

__repr__()[source]¶

Returns a string representation of an instance of ContextManagedSession useful for debugging.

Returns:	A string representing useful data about an instance of this class
Return type:	str

_decorator(f)[source]¶

This method decorates a function f with the session to be run. This is done by invoking the ContextManagedSession‘s context manager to open and clean up a new session, and running the decorated function in this context. The session is then appended to the decorated function’s argument list, and the function is then run.

For reconciling method names and docstring for documentation purposes, and to avoid namespace collisions in the server’s routing table, the __name__ and __doc__ properties of the decorated function are assigned to the decorator.

Parameters:	f (function) – The function to decorate
Returns:	A function that decorates the function to be decorated
Return type:	function

copy()[source]¶: Returns a new ContextManagedSession with the same namespace as self

5.1.2.2.2. Versioning¶

Contains tools for versioning databases, and for managing database upgrades. This code is currently not implemented in the dev version of OmicronServer, but will eventually be used as part of the server’s command line interface.

This code was adapted from Miguel Grinberg’s Flask mega-tutorial.

class database.versioning.DatabaseManager(metadata=MetaData(bind=None), database_url=None, migrate_repo='/home/docs/checkouts/readthedocs.org/user_builds/omicron-server/checkouts/latest/db_versioning_repo', api=<module 'migrate.versioning.api' from '/home/docs/checkouts/readthedocs.org/user_builds/omicron-server/envs/latest/local/lib/python2.7/site-packages/migrate/versioning/api.pyc'>, engine=Engine(sqlite:////home/docs/checkouts/readthedocs.org/user_builds/omicron-server/checkouts/latest/test_db.sqlite3))[source]¶

Wraps methods for managing database versions. The constructor requires the following

Variables:

metadata – An object of type sqlalchemy.MetaData, containing information about the database schema. Defaults to the metadata object located in database.models.schema.
database_url – The URL [RFC 3986] of the database to be upgraded or downgraded. Defaults to the database URL given in config, or read from command line environment variables.
migrate_repo – An absolute path to the directory in which database migration scripts are stored. Defaults to the value given in config.
api – The sqlalchemy-migrate API that will be used to perform the migration operations. This is overwritten for testability. Defaults to the API in migrate.versioning. See the Flask mega-tutorial for more details

__init__(metadata=MetaData(bind=None), database_url=None, migrate_repo='/home/docs/checkouts/readthedocs.org/user_builds/omicron-server/checkouts/latest/db_versioning_repo', api=<module 'migrate.versioning.api' from '/home/docs/checkouts/readthedocs.org/user_builds/omicron-server/envs/latest/local/lib/python2.7/site-packages/migrate/versioning/api.pyc'>, engine=Engine(sqlite:////home/docs/checkouts/readthedocs.org/user_builds/omicron-server/checkouts/latest/test_db.sqlite3))[source]¶: Instantiates the variables listed above :raises: DatabaseNotReferencedError if the DatabaseManager is created

without a database url or a database engine

__repr__()[source]¶: Returns a representation of the Database Manager useful for debugging :return:

__weakref__¶: list of weak references to the object (if defined)

create_db(engine=None)[source]¶

Create a database at self.database_url

Parameters:	engine – The SQLAlchemy engine which will be used to create the database

create_migration_script()[source]¶

Creates a new migration script for the database. The migration script is a python script located at self.migrate_repo. The target version of the script is listed on the file name. Each migration script must contain the following two functions.

upgrade describes how to move from the previous version to the version written in the file name.

downgrade describes how to downgrade the database from the version written on the file name to the previous version.

Warning

It is recommended that each migration script is reviewed prior to use, ESPECIALLY IN PRODUCTION. Automatically-generated migration scripts have known issues with migrations, particularly with queries involving ALTER COLUMN queries. In such situations, the migration script can easily DROP the old column and create a new one. Care should be taken when running migrations.

downgrade_db()[source]¶: Downgrade the DB from the current version to the decremented previous version.

upgrade_db()[source]¶: Upgrade the database to the most current version in the migrate repository, by running upgrade in all the migration scripts from the database’s version up to the current version.

version¶: Return the version of the database using the SQLAlchemy-migrate API

exception database.versioning.DatabaseNotReferencedError[source]¶

Thrown if :class:database.versioning.DatabaseManager` is instantiated without an engine or a database url.

__weakref__¶: list of weak references to the object (if defined)

5.1.2.2.3. Schema¶

Contains the database schema to be implemented or queried, from which models in database.models will be populated. This describes the database to be built on server initialization. This is the most current version of the database schema.