Skip to content

mnesis.store.pool

pool

Shared connection pool for ImmutableStore.

A single StorePool instance manages one aiosqlite.Connection per database path. All ImmutableStore objects pointing at the same path share that connection, so concurrent sub-agent sessions never fight over SQLite's single-writer lock.

When migrating to PostgreSQL (or another backend), replace this module with one that wraps asyncpg.create_pool / sqlalchemy.ext.asyncio — the ImmutableStore interface stays identical.

Usage::

pool = StorePool()

store_a = ImmutableStore(config, pool=pool)
store_b = ImmutableStore(config, pool=pool)   # same DB path → same connection

await store_a.initialize()   # opens the connection (idempotent on 2nd call)
await store_b.initialize()   # reuses existing connection

# … use stores …

await pool.close_all()       # close all managed connections once at shutdown

StorePool 

StorePool()

Process-scoped registry of open aiosqlite.Connection objects.

Thread-safety: only safe to use from a single asyncio event loop — do not share a StorePool across threads.

For each unique resolved database path the pool holds exactly one connection. Callers may call acquire() concurrently; only the first caller opens the connection, subsequent callers receive the same object.

The pool also manages a per-path asyncio.Lock that ImmutableStore uses to serialise write transactions. SQLite in WAL mode allows unlimited concurrent readers but only one writer; the lock prevents competing writes from getting database is locked errors on busy concurrent workloads.

acquire async 

acquire(
    db_path: str,
    *,
    wal_mode: bool = True,
    connection_timeout: float = 30.0,
) -> aiosqlite.Connection

Return the shared connection for db_path, opening it if needed.

Parameters:

Name Type Description Default
db_path str

Resolved (~ expanded) absolute path to the database file.

 required
wal_mode bool

Enable WAL journal mode on first open.

 True
connection_timeout float

SQLite busy timeout in seconds.

 30.0

Returns:

Type Description
Connection

The shared aiosqlite.Connection for this path.

write_lock 

write_lock(db_path: str) -> asyncio.Lock

Return the write-serialisation lock for db_path.

The lock must already exist (i.e. acquire() must have been called for this path). Raises KeyError if called before acquire().

close_path async 

close_path(db_path: str) -> None

Close and remove the connection for a single path.

close_all async 

close_all() -> None

Close every connection managed by this pool.

default staticmethod 

default() -> StorePool

Return the process-level default pool.

The default pool is created lazily on first access and lives for the lifetime of the process. It is suitable for production use; tests should create their own StorePool() instances to get full isolation.