arista.db

SQLite schema, seeds, queries, and connection helpers.

arista.db.build_schema(conn, *, progress=None)[source]

Apply the full schema to a database connection.

Idempotent: every CREATE uses IF NOT EXISTS so re-running against an already-populated database is a no-op. Foreign-key enforcement is enabled via PRAGMA.

Tables and the v_recordings view are applied in one executescript call (cheap regardless of corpus size). Indexes are applied one at a time so a tqdm progress bar can report which index is currently being built — at scale a single CREATE INDEX on a populated table can take seconds to minutes and going silent during that wait makes the run look hung.

Parameters:

conn (Connection) – An open SQLite connection (typically to arista.db or :memory: for tests).
progress (bool | None) – Controls the index-creation progress bar. None (default) auto-detects: shows when stdout is a TTY, hides otherwise (the typical pytest setup, so test fixtures don’t need to pass anything). True forces the bar on; False forces it off.

Return type:

None

arista.db.open_db(path, *, create_parents=True, timeout=30.0)[source]

Context manager around sqlite3.connect() with FK pragma.

Parameters:

path (str | Path) – Database file path. Created on first connect if absent.
create_parents (bool) – True (default) creates the parent directory tree if it does not exist — convenient for the /mnt/data/arista/arista.db case where the lab datadrive mount-point exists but the project subdirectory may not.
timeout (float) – SQLite lock-wait timeout in seconds.

Yields:

An open sqlite3.Connection with foreign-key enforcement on and the WAL journal mode active.

Return type:

Iterator[Connection]

arista.db.resolve_db_path(explicit=None)[source]

Return the canonical DB path per the documented resolution order.

Parameters:: explicit (str | Path | None) – A user-supplied path (e.g. from --db on the CLI). None means defer to the environment / default.
Returns:: Absolute Path to the target database file. The file itself need not exist yet — callers may open or build it.
Return type:: Path

arista.db.seed_dimensions(conn)[source]

Apply every dimension seed in dependency order and commit.

Parameters:: conn (Connection)
Return type:: None

Modules

`connection`	Open a SQLite connection with the project conventions enabled.
`schema`	SQLite schema for the arista calcium-imaging corpus.
`seeds`	Seed the controlled-vocabulary dimension tables.