SqliteProvider: Reference Guide

What is SqliteProvider?

SqliteProvider is the default storage backend that CrewAI Flows use to persist state whenever a Flow class is decorated with @persist. Under the hood it opens a SQLite database file (defaults to ~/.crewai/flows/<flow_name>.db unless you pass db_path to SqliteProvider) and writes one row per checkpoint, keyed by the Flow's state_id. The shape on disk is intentionally boring: a single state table with id, payload (JSON), and updated_at columns — which makes inspection with the sqlite3 CLI trivial and rules out vendor lock-in.

Why SQLite as a default? It gives you ACID semantics, file-level durability, and concurrent reader support without forcing a database dependency on first-time users. Connections are opened in WAL mode so multiple Flow runs on the same machine can read state while one writer commits, which is enough to handle the burst-y write pattern of @persist (one write per @start / @listen completion). Writes are serialized — SQLite uses a single writer at a time — but the @persist call path is small enough that this is rarely a bottleneck below a few hundred flows per second.

The boundaries to know: SqliteProvider is single-host. The database file lives on local disk, so two machines cannot share the same SqliteProvider instance via NFS or EFS without risking corruption (network filesystems do not honor SQLite's locking primitives reliably). For multi-pod Kubernetes deployments or any horizontally scaled worker pool, swap in a custom StorageBackend backed by Postgres, Redis, or your existing state store via CheckpointConfig(storage=...). For single-host production — a long-running container, a VM, a Cloud Run job with persistent volume — SqliteProvider is the right answer and the one the CrewAI team has tuned the default behavior for.

When to Use

Single-host production flows, long-running CrewAI Flows that survive process restarts, and any @persist usage where you don't want to stand up a separate database.

Use Cases

• • Single-host production CrewAI Flow deployments
• • Long-running flows that span hours or days
• • Local development with persisted checkpoints between runs
• • Cron-driven flows that resume from the last completed step
• • Cloud Run / ECS tasks with a persistent volume

Key Features

• ✓ ACID guarantees (atomic checkpoint writes)
• ✓ Embedded — zero external dependencies
• ✓ WAL mode for concurrent readers
• ✓ Inspectable with the standard sqlite3 CLI
• ✓ Configurable db_path
• ✓ Restore-by-state-id semantics for resumable flows

When NOT to Use

Notes

Import

from crewai.state import SqliteProvider

Key Parameters

Code Examples

from crewai.flow.flow import Flow, start, listen
from crewai.state.checkpoint_config import CheckpointConfig, persist
from crewai.state import SqliteProvider

@persist(config=CheckpointConfig(storage=SqliteProvider()))
class ResearchFlow(Flow):
    @start()
    def gather(self):
        return fetch_sources()

    @listen(gather)
    def summarize(self, sources):
        return summarize_sources(sources)

from pathlib import Path
from crewai.state import SqliteProvider
from crewai.state.checkpoint_config import CheckpointConfig

storage = SqliteProvider(db_path=Path('/data/flow_state.db'))
config = CheckpointConfig(storage=storage)

flow = ResearchFlow()
result = flow.kickoff(inputs={'topic': 'observability'})
print('state_id =', flow.state.id)

restored = ResearchFlow()
restored.restore_from_id(flow.state.id)
restored.kickoff()

$ sqlite3 ~/.crewai/flows/ResearchFlow.db
sqlite> .schema state
CREATE TABLE state (id TEXT PRIMARY KEY, payload TEXT, updated_at REAL);
sqlite> SELECT id, updated_at FROM state ORDER BY updated_at DESC LIMIT 5;

Common Mistakes

SqliteProvider FAQ