httk.data.db.engine

Database engine lifecycle: Database wraps a SQLAlchemy engine behind an httk-facing API.

A Database names where data lives — an SQLite file, an in-memory SQLite database, a DuckDB file — and owns the connection pool that reaches it. It deliberately exposes no SQL surface of its own: the store layer (SqlStore) asks it for connections internally, and user code only constructs one (usually via Database.sqlite() or Database.duckdb()) and passes it on. There is no global engine registry and no interpreter-exit hook; dispose of a database explicitly with Database.dispose() or use it as a context manager.

Classes

Database

A relational database reachable through a wrapped SQLAlchemy engine.

Module Contents

class httk.data.db.engine.Database(engine: sqlalchemy.Engine)

A relational database reachable through a wrapped SQLAlchemy engine.

Construct one with sqlite() or duckdb() (or, for other SQLAlchemy-supported backends, by passing a preconfigured engine directly). The instance is a context manager; leaving the with block disposes the engine’s connection pool.

classmethod sqlite(path: str | os.PathLike[str] | None = None) → Self

An SQLite database stored in the file at path, or in memory when path is None.

The in-memory variant is configured (via a static connection pool with a shared, thread-unrestricted connection) so that every connection drawn from the engine sees the one and same database; file-backed databases use SQLAlchemy’s default pooling.

classmethod duckdb(path: str | os.PathLike[str] | None = None) → Self

A DuckDB database stored in the file at path, or in memory when path is None.

Raises:

ImportError – If the duckdb_engine SQLAlchemy dialect is not installed; install the httk-data[duckdb] extra to get it.

property engine: sqlalchemy.Engine

The underlying SQLAlchemy engine (for use by the storage layer itself).

dispose() → None

Close the engine’s connection pool; the database can no longer be used after this.