Connection

connection

Defines the cached, process-scoped engine and session maker singletons that provide database connection

Every connection is tuned for faast read-only access through sqlite3 PRAGMAs

Read-Only

The database is opened in read-only mode (sqlite3's PRAGMA query_only=ON) , since the package never writes to it at runtime

Pre-Requisite

• The compiled database is a prerequisite, not a dependency

• It is built or pulled into the per-user cache directory by the Build Pipeline and only queried here

• Until it exists, every query fails with a DatabaseNotFoundError that points the caller at the build or pull CLI commands

AudioDatabaseNotFoundError

Bases: DatabaseNotFoundError

Raised when audio bytes are requested but the optional audio pack is not installed

DatabaseNotFoundError

Bases: RuntimeError

Raised when a query is attempted before the database exists

get_engine() cached

Returns the process-scoped, read-only SQLAlchemy Engine object

PRAGMAs Applied To Every Pooled Connection

• query_only=ON → Reject any write on the connection, since the package only reads the prebuilt database, which also makes lending a connection across threads safe

• mmap_size=268435456 → Memory map up to 256 MB of the file so hot pages are read from the mapping instead of a read syscall and an extra copy on every access

• cache_size=-64000 → Keep about 64 MB of pages cached per connection, where the minus sign sets the size in KiB rather than in page count

• temp_store=MEMORY → Hold the temporary b-trees used for sorts such as ORDER BY in memory rather than spilling them to a temp file

Returns:

Type	Description
Engine	An engine bound to the cached database with read-only PRAGMAs applied to every connection

Raises:

Type	Description
DatabaseNotFoundError	If the database file does not exist

get_sessionmaker() cached

Returns the process-scoped session factory

Returns:

Type	Description
sessionmaker[Session]	A session factory bound to the read only engine (also process-scoped)

session_scope()

Provide a read-only session as a context manager

Yields:

Type	Description
Session	A session that is closed when the context exits

Raises:

Type	Description
DatabaseNotFoundError	If the database file does not exist