Skip to main content

​
marvin.database

This module provides utilities for managing database sessions and migrations.

​
Classes

​
Base

Base class for all database models.

​
DBLLMCall

Methods:
  • create
    Create a new LLM call record. Args: thread_id: ID of the thread this call belongs to usage: RunUsage information from the model session: Optional database session. If not provided, a new one will be created. Returns: The created DBLLMCall instance

​
DBLLMCallMessage

Mapping table between LLM calls and messages.

​
DBMessage

Methods:
  • from_message
  • to_message

​
DBThread

Methods:
  • create
    Create a new thread record. Args: session: Database session to use id: Optional ID to use for the thread. If not provided, a UUID will be generated. parent_thread_id: Optional ID of the parent thread Returns: The created DBThread instance

​
UsageType

Custom type for RunUsage objects that stores them as JSON in the database. Methods:
  • process_bind_param
    Convert RunUsage to JSON before storing in DB.
  • process_result_value
    Convert JSON back to RunUsage when loading from DB.

​
Functions

​
create_db_and_tables

Create all database tables. Args: force: If True, drops all existing tables before creating new ones. dispose_engine: If True, dispose the engine after creating tables. This is useful when called from asyncio.run() to ensure the aiosqlite worker thread is cleaned up and doesn’t prevent Python from exiting.

​
ensure_db_tables_exist

Ensure database tables exist, creating them if necessary. This function creates all database tables directly without using migrations, which is more reliable than using Alembic migrations.

​
get_async_engine

Get the SQLAlchemy engine for async operations. For SQLite databases, this uses aiosqlite. For other databases (e.g. PostgreSQL), this uses the provided URL directly. The engine is cached by asyncio event loop to maintain compatibility with run_sync.

​
get_async_session

Get an async database session. This uses the async_sessionmaker pattern for more consistent session management. If a session is provided, it is returned as-is. Args: session: An optional existing session to use. If provided, this function will yield it directly instead of creating a new one. Yields: An async SQLAlchemy session

​
init_database_if_necessary

Initialize the database file if necessary. This function only handles creating the database file and parent directories, it does not create tables. Tables are created by ensure_db_tables_exist().

​
is_sqlite

Check if the configured database is SQLite.

​
serialize_message

The ctx field in the RetryPromptPart is optionally dict[str, Any], which is not always serializable.

​
set_async_engine

Set the SQLAlchemy engine for async operations.

​
utc_now

Get the current UTC timestamp.
Parent Module: marvin