simdb.database.database module¶

class simdb.database.database.Database(db_type: DBMS, scopefunc=None, **kwargs)[source]¶

Bases: object

Class to wrap the database access.

class DBMS(value)[source]¶

Bases: Enum

DBMSs supported.

MSSQL = 3¶

POSTGRESQL = 2¶

SQLITE = 1¶

add_watcher(sim_ref: str, watcher: Watcher)[source]¶

close()[source]¶: Close the database session and dispose of the engine.

delete_simulation(sim_ref: str) → Simulation[source]¶

Delete the specified simulation from the database.

Parameters:¶

sim_ref: str¶: The simulation UUID or alias.

Returns:¶

None

engine : Engine¶

get_aliases(prefix: str | None) → list[str][source]¶

get_file(file_uuid_str: str) → File[source]¶

Get the specified file from the database.

Parameters:¶

file_uuid_str: str¶: The string representation of the file UUID.

Returns:¶

The File.

get_metadata(sim_ref: str, name: str) → list[str][source]¶

Get all the metadata for the given simulation with the given key.

Parameters:¶

sim_ref: str¶: the simulation identifier
name: str¶: the metadata key

Returns:¶

The matching metadata values.

get_simulation(sim_ref: str) → Simulation[source]¶

Get the specified simulation from the database.

Parameters:¶

sim_ref: str¶: The simulation UUID or alias.

Returns:¶

The Simulation.

get_simulation_children(simulation: Simulation) → list[dict][source]¶

get_simulation_children_ref(simulation: Simulation) → list[SimulationReference][source]¶

get_simulation_data(query)[source]¶

get_simulation_parents(simulation: Simulation) → list[dict][source]¶

get_simulation_parents_ref(simulation: Simulation) → list[SimulationReference][source]¶

insert_simulation(simulation: Simulation) → None[source]¶

Insert the given simulation into the database.

Parameters:¶

simulation: Simulation¶: The Simulation to insert.

Returns:¶

None

list_files() → list[File][source]¶

Return a list of all the files stored in the database.

Returns:¶: A list of Files.

list_metadata_keys() → list[dict][source]¶

list_metadata_values(name: str) → list[str][source]¶

list_simulation_data(meta_keys: list[str] | None = None, limit: int = 0, page: int = 1, sort_by: str = '', sort_asc: bool = False) → tuple[int, list[dict]][source]¶

Return a list of all the simulations stored in the database.

Returns:¶: A tuple of (total_count, list of simulation data dicts).

list_simulations(meta_keys: list[str] | None = None, limit: int = 0) → list[Simulation][source]¶

Return a list of all the simulations stored in the database.

Returns:¶: A list of Simulations.

list_watchers(sim_ref: str) → list[Watcher][source]¶

query_meta(constraints: list[tuple[str, str, QueryType]]) → list[Simulation][source]¶

Query the metadata and return matching simulations.

Returns:¶

query_meta_data(constraints: list[tuple[str, str, QueryType]], meta_keys: list[str], limit: int = 0, page: int = 1, sort_by: str = '', sort_asc: bool = False) → tuple[int, list[dict]][source]¶

Query the metadata and return matching simulations.

Returns:¶

remove()[source]¶: Remove the current session

remove_watcher(sim_ref: str, username: str)[source]¶

reset() → None[source]¶

Clear all the data out of the database.

Returns:¶: None

session : Session¶

exception simdb.database.database.DatabaseError[source]¶: Bases: RuntimeError

exception simdb.database.database.DatabaseOutdatedError[source]¶: Bases: DatabaseError

exception simdb.database.database.DatabaseUninitializedError[source]¶: Bases: DatabaseError

class simdb.database.database.Session(session_factory, scopefunc=None)[source]¶

Bases: scoped_session

add(obj: Base, *args, **kwargs)[source]¶

Place an object into this _orm.Session.

Proxied for the _orm.Session class on behalf of the _orm.scoping.scoped_session class.

Objects that are in the transient state when passed to the _orm.Session.add() method will move to the pending state, until the next flush, at which point they will move to the persistent state.

Objects that are in the detached state when passed to the _orm.Session.add() method will move to the persistent state directly.

If the transaction used by the _orm.Session is rolled back, objects which were transient when they were passed to _orm.Session.add() will be moved back to the transient state, and will no longer be present within this _orm.Session.

See also

_orm.Session.add_all()

session_adding - at session_basics

commit()[source]¶

Flush pending changes and commit the current transaction.

Proxied for the _orm.Session class on behalf of the _orm.scoping.scoped_session class.

When the COMMIT operation is complete, all objects are fully expired, erasing their internal contents, which will be automatically re-loaded when the objects are next accessed. In the interim, these objects are in an expired state and will not function if they are detached from the Session. Additionally, this re-load operation is not supported when using asyncio-oriented APIs. The :paramref:`.Session.expire_on_commit` parameter may be used to disable this behavior.

When there is no transaction in place for the Session, indicating that no operations were invoked on this Session since the previous call to Session.commit(), the method will begin and commit an internal-only “logical” transaction, that does not normally affect the database unless pending flush changes were detected, but will still invoke event handlers and object expiration rules.

If 1.x-style use is in effect and there are currently SAVEPOINTs in progress via _orm.Session.begin_nested(), the operation will release the current SAVEPOINT but not commit the outermost database transaction.

If 2.0-style use is in effect via the :paramref:`_orm.Session.future` flag, the outermost database transaction is committed unconditionally, automatically releasing any SAVEPOINTs in effect.

When using legacy “autocommit” mode, this method is only valid to call if a transaction is actually in progress, else an error is raised. Similarly, when using legacy “subtransactions”, the method will instead close out the current “subtransaction”, rather than the actual database transaction, if a transaction is in progress.

See also

session_committing

unitofwork_transaction

asyncio_orm_avoid_lazyloads

delete(obj: Base)[source]¶

Mark an instance as deleted.

Proxied for the _orm.Session class on behalf of the _orm.scoping.scoped_session class.

The object is assumed to be either persistent or detached when passed; after the method is called, the object will remain in the persistent state until the next flush proceeds. During this time, the object will also be a member of the _orm.Session.deleted collection.

When the next flush proceeds, the object will move to the deleted state, indicating a DELETE statement was emitted for its row within the current transaction. When the transaction is successfully committed, the deleted object is moved to the detached state and is no longer present within this _orm.Session.

See also

session_deleting - at session_basics

execute(query: Any, *args, **kwargs) → Any[source]¶

Execute a SQL expression construct.

Proxied for the _orm.Session class on behalf of the _orm.scoping.scoped_session class.

Returns a _engine.Result object representing results of the statement execution.

E.g.:

from sqlalchemy import select
result = session.execute(
    select(User).where(User.id == 5)
)

The API contract of _orm.Session.execute() is similar to that of _future.Connection.execute(), the 2.0 style version of _future.Connection.

Changed in version 1.4: the _orm.Session.execute() method is now the primary point of ORM statement execution when using 2.0 style ORM usage.

Parameters:¶

statement: An executable statement (i.e. an Executable expression such as _expression.select()).
params: Optional dictionary, or list of dictionaries, containing bound parameter values. If a single dictionary, single-row execution occurs; if a list of dictionaries, an “executemany” will be invoked. The keys in each dictionary must correspond to parameter names present in the statement.
execution_options: optional dictionary of execution options, which will be associated with the statement execution. This dictionary can provide a subset of the options that are accepted by _engine.Connection.execution_options(), and may also provide additional options understood only in an ORM context.
bind_arguments: dictionary of additional arguments to determine the bind. May include “mapper”, “bind”, or other custom arguments. Contents of this dictionary are passed to the Session.get_bind() method.
mapper: deprecated; use the bind_arguments dictionary
bind: deprecated; use the bind_arguments dictionary
**kw: deprecated; use the bind_arguments dictionary

Returns:¶

a _engine.Result object.

query(obj: Base, *args, **kwargs) → Any[source]¶: Return a new _query.Query object corresponding to this _orm.Session.

Proxied for the _orm.Session class on behalf of the _orm.scoping.scoped_session class.

rollback()[source]¶

Rollback the current transaction in progress.

Proxied for the _orm.Session class on behalf of the _orm.scoping.scoped_session class.

If no transaction is in progress, this method is a pass-through.

In 1.x-style use, this method rolls back the topmost database transaction if no nested transactions are in effect, or to the current nested transaction if one is in effect.

When 2.0-style use is in effect via the :paramref:`_orm.Session.future` flag, the method always rolls back the topmost database transaction, discarding any nested transactions that may be in progress.

See also

session_rollback

unitofwork_transaction

simdb.database.database.backup_local_db(config: Config)[source]¶

simdb.database.database.check_migrations(engine) → str[source]¶

Check that the database is up-to-date with the latest Alembic migration.

Raises DatabaseUninitializedError if the database has not been initialised at all (i.e. the alembic_version table is absent), or DatabaseOutdatedError if the database schema is behind the head revision.

simdb.database.database.get_local_db(config: Config) → Database[source]¶

simdb.database.database.run_migrations(engine) → None[source]¶: Run the database migrations.