autowisp.database.interface module

Class Inheritance Diagram

Connect to the database and provide a session scope for queries.

autowisp.database.interface.DB_URL_FNAME = 'autowisp_db.url'

Filename (relative to project home) where a non-SQLite connection URL is stored.

When a project is initialised with a centralised database (MySQL, MariaDB, etc.) the connection URL is written to this file so that subsequent calls to set_project_home() with only the directory path can reconnect without requiring the caller to supply the URL again.

autowisp.database.interface.apply_additive_migrations(engine)

Bring an existing project database up to the current schema.

A minimal, idempotent stand-in for a migration framework (the project has none), covering the additive changes that are safe to apply automatically on connect:

• New tables (e.g. error) are created via create_all, which leaves existing tables and their data untouched. This is how a table added after a project was initialized reaches that project.

• New nullable columns on existing tables are added with ALTER TABLE ... ADD COLUMN. Rows that predate a column keep NULL – e.g. pipeline_run rows from before code_version existed have no recorded code version, which is correct (it is genuinely unknown).

Freshly initialized databases get everything from create_all already, so this is effectively a no-op for them. When the pipeline runs, the main process opens the project first, so by the time workers connect every table exists and their create_all does no DDL.

Parameters:

engine – The SQLAlchemy engine for the project database.

Returns:

None

autowisp.database.interface.get_db_engine()

Return the database engine.

autowisp.database.interface.get_project_home()

Return the project home directory currently being used.

autowisp.database.interface.initialize_cmdline_database()

Initialize the current database HDF5 structure tables.

autowisp.database.interface.set_project_home(project_home, db_url=None)

Set the database engine and session for the given project home.

On first use with a non-SQLite db_url the URL is persisted to <project_home>/autowisp_db.url so that subsequent calls with only project_home reconnect to the same database automatically.

Parameters:

• project_home – Directory used as the project home. For SQLite (the default), the database file autowisp.db is created here. For centralised databases the directory is still used for other project files (HDF5 products, etc.). Pass None to use the platform-appropriate user data directory.

• db_url – SQLAlchemy connection URL. When omitted (or None) the function first checks for a previously saved URL in <project_home>/autowisp_db.url; if none is found it falls back to an SQLite database in project_home: sqlite:///<project_home>/autowisp.db?timeout=100&uri=true. To connect to a centralised server pass the full URL, e.g.: "mysql+pymysql://user:password@host:3306/dbname" "mariadb+pymysql://user:password@host:3306/dbname" Passing an explicit URL raises an error if a saved URL is found.

autowisp.database.interface.snapshot_row(orm_obj, *, exclude=())

Freeze all mapped columns of a live ORM instance into a FrozenRow.

Must be called while orm_obj is still attached/loaded (i.e. inside the start_db_session() block that produced it), otherwise touching an expired column would raise DetachedInstanceError.

Parameters:

• orm_obj – A SQLAlchemy ORM instance.

• exclude (Iterable[str]) – Column keys to omit (e.g. large or sensitive columns).

Returns:

Snapshot of the instance’s column values, detached

from the session and safe to pickle.

Return type:

FrozenRow

autowisp.database.interface.start_db_session()

Context manager to start a database session.