Struct Database 

pub struct Database { /* private fields */ }

Wrapper around the SQLite connection pool.

Implementations

impl Database

pub fn pool(&self) -> &SqlitePool

Access the underlying connection pool (for tests and raw queries).

pub async fn init(koda_config_dir: &Path) -> Result<Self>

Initialize the database, run migrations, and enable WAL mode.

koda_config_dir is the koda configuration directory (e.g. ~/.config/koda). The database lives in <koda_config_dir>/db/koda.db.

Production callers should pass db::config_dir()?; tests pass a temp dir.

pub async fn open(db_path: &Path) -> Result<Self>

Open a database at a specific path (used by tests and init).

impl Database

pub async fn insert_owned_file( &self, session_id: &str, path: &Path, ) -> Result<()>

Record that Koda created a file in this session.

pub async fn delete_owned_file( &self, session_id: &str, path: &Path, ) -> Result<()>

Remove a file from the owned set.

pub async fn load_owned_files( &self, session_id: &str, ) -> Result<HashSet<PathBuf>>

Load all owned file paths for a session (used on session resume).

pub async fn load_messages_before( &self, session_id: &str, before_id: i64, limit: i64, ) -> Result<Vec<Message>>

Load a page of messages older than before_id (for virtual scroll).

Returns up to limit messages with id < before_id, ordered newest-first so the caller can reverse them for display. Only non-compacted messages are returned.

pub async fn seconds_since_last_assistant( &self, session_id: &str, ) -> Result<Option<i64>>

Seconds since the last assistant message in this session.

Returns None if there are no (non-compacted) assistant messages. Used by microcompact to decide whether the idle gap threshold is met.

impl Database

pub async fn kv_get(&self, key: &str) -> Result<Option<String>>

Get a value from the global KV store.

pub async fn kv_set(&self, key: &str, value: &str) -> Result<()>

Set a value in the global KV store (upsert).

pub async fn kv_delete(&self, key: &str) -> Result<()>

Delete a key from the global KV store.

pub async fn kv_list_prefix( &self, prefix: &str, ) -> Result<Vec<(String, String)>>

Get all KV entries matching a prefix (e.g. "apikey:").

impl Database

pub async fn history_push(&self, input: &str) -> Result<()>

Append an input to the history.

pub async fn history_load(&self) -> Result<Vec<String>>

Load all history entries, oldest first.

Trait Implementations

impl Clone for Database

fn clone(&self) -> Database

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Database

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Persistence for Database

fn create_session<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, agent_name: &'life1 str, project_root: &'life2 Path, ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Create a new session, returning the generated session ID.

fn insert_message<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'life6, 'async_trait>( &'life0 self, session_id: &'life1 str, role: &'life2 Role, content: Option<&'life3 str>, tool_calls: Option<&'life4 str>, tool_call_id: Option<&'life5 str>, usage: Option<&'life6 TokenUsage>, ) -> Pin<Box<dyn Future<Output = Result<i64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, 'life6: 'async_trait,

Insert a message into the conversation log.

fn insert_message_with_agent<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'life6, 'life7, 'async_trait>( &'life0 self, session_id: &'life1 str, role: &'life2 Role, content: Option<&'life3 str>, tool_calls: Option<&'life4 str>, tool_call_id: Option<&'life5 str>, usage: Option<&'life6 TokenUsage>, agent_name: Option<&'life7 str>, ) -> Pin<Box<dyn Future<Output = Result<i64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, 'life6: 'async_trait, 'life7: 'async_trait,

Insert a message with an optional agent name for cost tracking.

fn copy_messages_into_session<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, dst_session: &'life1 str, messages: &'life2 [Message], ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

#1022 B20: atomic batch copy of messages into a session.

Replaces the pre-fix per-row loop (insert_message x N times, each a separate UPDATE-last_accessed_at + optional mark_message_complete). All inserts run inside a single sqlx transaction — one fsync at COMMIT instead of N — with completed_at written inline for assistant rows so no follow-up UPDATE is needed.

Errors mid-loop bubble up via ?; the transaction is dropped without commit(), so the destination session sees no partial state. Sqlx rolls back on Drop.

fn update_message_thinking_content<'life0, 'life1, 'async_trait>( &'life0 self, message_id: i64, content: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Persist the accumulated thinking/reasoning text for an assistant message.

Called after insert_message so the INSERT signature stays lean — only assistant messages from Claude with extended thinking enabled will ever call this. All other callers of insert_message are unaffected.

fn load_context<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<Message>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load active (non-compacted) messages for a session.

Returns messages in chronological order. Compacted messages (archived by /compact) are excluded — their summary replaces them. Several sanitisation passes run before returning:

• Incomplete assistant messages (interrupted/network-error) are excluded (#875, #877)
• Mismatched tool_use / tool_result pairs are pruned (#428)
• Null-content assistant messages with no tool calls are dropped (#594)
• Whitespace-only assistant messages are dropped (#594)

fn load_all_messages<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<Message>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load ALL messages for a session (for RecallContext search). Returns messages in chronological order, no truncation.

fn recent_user_messages<'life0, 'async_trait>( &'life0 self, limit: i64, ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Load recent user messages across all sessions (for the startup banner). Returns up to limit messages, newest first.

fn session_token_usage<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<SessionUsage>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get token usage totals for a session.

fn session_usage_by_agent<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<(String, SessionUsage)>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get token usage broken down by agent name.

fn list_sessions<'life0, 'life1, 'async_trait>( &'life0 self, limit: i64, project_root: &'life1 Path, ) -> Pin<Box<dyn Future<Output = Result<Vec<SessionInfo>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

List recent sessions for a specific project.

fn last_assistant_message<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get the last assistant text response for a session (for headless JSON output).

fn last_user_message<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get the last user message in a session.

fn delete_session<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Delete a session and all its messages/metadata atomically.

fn compact_session<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, summary: &'life2 str, preserve_count: usize, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Compact a session: summarize old messages while preserving the most recent ones.

Keeps the last preserve_count messages intact, deletes the rest, and inserts a summary (as a system message) plus a continuation hint (as an assistant message) before the preserved tail.

Returns the number of messages that were deleted/replaced.

fn has_pending_tool_calls<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Check if the last message in a session is a tool call awaiting a response. Used to defer compaction during active tool execution.

fn compacted_stats<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<CompactedStats>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Stats about compacted (archived) messages across all sessions.

fn purge_compacted<'life0, 'async_trait>( &'life0 self, min_age_days: u32, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Permanently delete compacted messages older than min_age_days. Pass 0 to delete all compacted messages regardless of age.

fn get_metadata<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, key: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Get a session metadata value by key.

fn set_metadata<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, session_id: &'life1 str, key: &'life2 str, value: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Set a session metadata value (upsert).

fn get_todo<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get the todo list for a session (convenience wrapper).

fn set_todo<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, content: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Set the todo list for a session (convenience wrapper).

fn insert_tool_message_with_full<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, session_id: &'life1 str, content: &'life2 str, tool_call_id: &'life3 str, full_content: &'life4 str, ) -> Pin<Box<dyn Future<Output = Result<i64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

Insert a tool message with full (untruncated) output stored separately.

fn mark_message_complete<'life0, 'async_trait>( &'life0 self, message_id: i64, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Mark an assistant message as fully delivered.

fn set_session_title<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, title: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Set the auto-generated title for a session.

fn set_session_mode<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, mode: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Persist the current approval mode for a session (restored on resume).

fn get_session_mode<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get the stored approval mode for a session.

fn get_session_idle_secs<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<i64>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Seconds elapsed since the session was last accessed (last_accessed_at). Returns None if the column is NULL (session never had a context load).

fn clear_message_content<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, message_ids: &'life1 [i64], stub: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Replace message content for the given IDs with a stub string. Used by microcompact to clear old tool results without full compaction.