Event Store Lifecycle and Async Context Managers
All built-in event stores (InMemoryEventStore, SQLiteEventStore, PostgreSQLEventStore) and snapshot stores (InMemorySnapshotStore, SQLiteSnapshotStore, PostgreSQLSnapshotStore) implement the SupportsAsyncContextManager and SupportsClose protocols from eventsource.ports.lifecycle.
Using async with store: guarantees that owned database connections and background worker threads are deterministically closed when exiting the block.
For choosing a backend and configuring schemas, see Choose an Event Store Backend and Database Schema.
Managing store lifecycle with `async with store:`
Connection-owning adapters such as SQLiteEventStore and SQLiteSnapshotStore open an aiosqlite.Connection lazily on first use. Wrap the store in async with so await store.close() runs automatically on scope exit:
from uuid import uuid4
from eventsource import (
AggregateRepository,
ExpectedVersion,
SQLiteEventStore,
StreamId,
)
from eventsource.adapters.sqlite import SQLiteSnapshotStore
async def run_with_sqlite() -> None:
async with (
SQLiteEventStore(":memory:") as event_store,
SQLiteSnapshotStore(":memory:") as snapshot_store,
):
repo = AggregateRepository(
event_store=event_store,
aggregate_factory=OrderAggregate,
snapshot_store=snapshot_store,
snapshot_threshold=50,
)
order_id = uuid4()
order = repo.create_new(order_id)
order.create(customer_id=uuid4())
await repo.save(order)
# Both aiosqlite connections and their worker threads are closed here.
You can also call await store.close() directly in application shutdown hooks (such as FastAPI lifespan handlers or pytest fixture finalizers). close() is idempotent: calling it multiple times or on a store that was never opened is a safe no-op.
Ownership semantics across backends
SupportsClose and SupportsAsyncContextManager follow a strict ownership contract: close() only tears down resources that the store itself created or was explicitly given ownership of.
| Store Adapter | Default Ownership | What close() / async with Does |
|---|---|---|
SQLiteEventStore |
Owns its lazy aiosqlite.Connection |
Closes the aiosqlite connection and stops its worker thread |
SQLiteSnapshotStore |
Owns its lazy aiosqlite.Connection |
Closes the aiosqlite connection and stops its worker thread |
PostgreSQLEventStore |
Caller owns AsyncEngine (owns_engine=False) |
No-op by default; disposes engine only when constructed with owns_engine=True |
PostgreSQLSnapshotStore |
Caller owns AsyncEngine (owns_engine=False) |
No-op by default; disposes engine only when constructed with owns_engine=True |
InMemoryEventStore |
Pure Python memory | No-op (SupportsAsyncContextManager supported for uniform wiring) |
InMemorySnapshotStore |
Pure Python memory | No-op (SupportsAsyncContextManager supported for uniform wiring) |
When a PostgreSQLEventStore or PostgreSQLSnapshotStore is the sole user of an AsyncEngine and should dispose the connection pool on exit, pass owns_engine=True:
from sqlalchemy.ext.asyncio import create_async_engine
from eventsource import PostgreSQLEventStore
engine = create_async_engine("postgresql+asyncpg://localhost/app")
async with PostgreSQLEventStore(engine, owns_engine=True) as store:
...
# engine.dispose() has been awaited on exit
Runtime capability checks with `SupportsAsyncContextManager`
Generic infrastructure code that accepts any FullEventStore or SnapshotStore can check SupportsAsyncContextManager or SupportsClose structurally at runtime without importing concrete adapter classes:
from eventsource.ports.lifecycle import SupportsAsyncContextManager, SupportsClose
assert isinstance(store, SupportsClose)
assert isinstance(store, SupportsAsyncContextManager)
Unclosed store diagnostics (`ResourceWarning`)
If a SQLiteEventStore or SQLiteSnapshotStore opens its underlying aiosqlite connection and is later garbage-collected without await store.close() or async with store: having completed, its __del__ finalizer emits a ResourceWarning identifying the leaked store and database path:
ResourceWarning: Unclosed SQLiteEventStore (':memory:') <SQLiteEventStore object at 0x...>;
call 'await store.close()' or use 'async with'
To surface leaked store connections immediately as test failures during development, configure pytest to treat ResourceWarning as an error or run Python with -W error::ResourceWarning:
uv run pytest -W error::ResourceWarning
Append signatures by store
Each store declares its own append. The expected argument differs:
# InMemoryEventStore: a single event or a sequence; expected is required.
async def append(
self,
stream: StreamId,
events: DomainEvent | Sequence[DomainEvent],
expected: ExpectedVersion,
) -> AppendResult: ...
# PostgreSQLEventStore and SQLiteEventStore: a sequence only; expected is required.
async def append(
self,
stream: StreamId,
events: Sequence[DomainEvent],
expected: ExpectedVersion,
) -> AppendResult: ...
Pass expected on every append to PostgreSQL and SQLite. Wrap a single event in a list ([event]) for those stores. The synchronous adapter has its own signature. See the sync adapter reference.
`InMemoryEventStore` Ergonomics
In addition to implementing FullEventStore and SupportsAsyncContextManager, InMemoryEventStore provides convenience helpers for tests, fixtures, and in-process workflows:
- $O(1)$ membership check (
event_id in storeorevent in store):InMemoryEventStore.__contains__checks the internal_event_idsset in $O(1)$ time. Pass either aUUID(event_id in store) or aDomainEventinstance (event in store, which checksevent.event_id); any other type returnsFalse. - Stream existence check (
await store.stream_exists(stream) -> bool): ReturnsTrueifstreamhas at least one appended event, orFalsewhen the stream does not exist. - Single-event
append:InMemoryEventStore.appendaccepts either a singleDomainEventor aSequence[DomainEvent]forevents. Like every store, it requiresexpected. Omitting it raisesTypeError. See the append signatures section below.
from uuid import uuid4
from eventsource import ExpectedVersion, InMemoryEventStore, StreamId
async with InMemoryEventStore() as store:
stream = StreamId(aggregate_id=uuid4(), category="Order")
assert await store.stream_exists(stream) is False
# Append a single DomainEvent. ExpectedVersion.any_() skips the version check.
created = OrderCreated(aggregate_id=stream.aggregate_id, customer_id=uuid4())
await store.append(stream, created, ExpectedVersion.any_())
# Append a sequence with an explicit ExpectedVersion
shipped = OrderShipped(aggregate_id=stream.aggregate_id, tracking_number="TRACK-1")
await store.append(stream, [shipped], ExpectedVersion.exact(1))
assert await store.stream_exists(stream) is True
assert created.event_id in store
assert created in store
assert shipped in store