SQLite Persistence

Local file database persistence for development and single-instance applications

SQLite saves agent conversations to a local .db file — no external database required.

from praisonaiagents import Agent, db

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    db=db(database_url="sqlite:///conversations.db"),
    session_id="dev-session",
)
agent.start("Hello — saved to SQLite")

The user develops locally; SQLite writes conversations to a single file on disk.

Quick Start

1. Simple Usage

   from praisonaiagents import Agent, db
   
   agent = Agent(
       name="Assistant",
       db=db(database_url="sqlite:///conversations.db"),
       session_id="session-1",
   )
   agent.start("Remember my favourite colour is blue")
   
2. With Configuration

   Choose sync or async when using the factory directly:

   from praisonai.persistence.factory import create_conversation_store
   
   # Sync — scripts and multi-threaded agents
   store = create_conversation_store(
       "sqlite",
       path="./conversations.db",
       mode="sync",
   )
   
   # Async — FastAPI / asyncio apps
   store = create_conversation_store(
       "sqlite",
       path="./conversations.db",
       mode="async",
   )
   

Before PR #1763, AsyncSQLiteConversationStore exposed sync wrappers callable from regular functions. Those wrappers were removed — use mode="sync" (sync_sqlite backend) when calling from sync code.

---

How It Works

Table	Purpose
sessions	Session metadata
messages	User and agent messages
runs	Agent execution runs
tool_calls	Tool usage records

---

Sync vs Async

---

Configuration Options

Option	Type	Default	Description
mode	"sync" | "async" | "auto"	"auto"	Backend variant; invalid values raise ValueError
path	str	"praisonai_conversations.db"	SQLite file path (sync store)
table_prefix	str	"praison_"	Table name prefix (alphanumeric only)

URL formats

db(database_url="sqlite:///conversations.db")          # relative path
db(database_url="sqlite:////absolute/path/to/db.db") # absolute path
db(database_url="sqlite:///:memory:")                # in-memory (temporary)

---

Best Practices

Use sync mode for multi-agent scripts

The sync_sqlite backend (mode="sync") uses per-call connection locking for multi-threaded agents.

Use absolute paths in production

Set the database path via environment variables and use absolute paths for deployments.

Enable WAL for better concurrency

Run PRAGMA journal_mode=WAL when multiple readers share the same file.

Migrate to PostgreSQL at scale

SQLite handles thousands of conversations; move to PostgreSQL for multi-instance deployments.

---

Related

PostgreSQL Persistence

Scale up when you outgrow SQLite

Database Persistence

Compare all persistence backends