SQLite Driver
Run Compozy with an embedded SQLite database for local development, edge deployments, and lightweight environments.
Why SQLite
- Single-file deployment without external dependencies.
- Ideal for CI pipelines and ephemeral preview environments.
- Zero network latency; great for edge devices with limited resources.
- Works with in-memory mode (
:memory:) for short-lived execution.
Configuration
database:
driver: sqlite
path: ./data/compozy.db
busy_timeout: 5000 # optional, milliseconds
journal_mode: wal # optional, WAL recommended for concurrent writes
synchronous: normal # optional, balance durability vs speed
knowledge:
vector_dbs:
- id: main
provider: qdrant
url: http://localhost:6333
dimension: 1536Supported Fields
| Field | Required | Description |
|---|---|---|
path | Yes | Filesystem path to the SQLite database (:memory: for ephemeral usage). |
busy_timeout | No | Milliseconds to wait before emitting database is locked errors. |
journal_mode | No | Recommended wal for write-concurrent scenarios; defaults to SQLite's driver configuration. |
synchronous | No | Adjust durability guarantees (full, normal, off). |
Environment variables mirror the configuration fields (COMPOZY_DB_PATH, COMPOZY_DB_BUSY_TIMEOUT, etc.).
⚠️ Vector Database Requirement
SQLite does not ship with vector search. Configure an external provider whenever you use the SQLite driver.
knowledge:
vector_dbs:
- id: main
provider: qdrant
url: http://localhost:6333
dimension: 1536Concurrency Limitations
SQLite uses database-level locks and serializes writes. Plan capacity accordingly:
- ✅ Recommended: 5-10 concurrent workflows.
- ⚠️ Borderline: 10-25 workflows with generous backoff and
busy_timeout. - 🔴 Not supported: 25+ workflows or multi-tenant loads — migrate to PostgreSQL.
runtime:
max_concurrent_workflows: 5Backup & Data Portability
- Hot backups
Use the
sqlite3command (.backup) or copy the.dbfile while the server is idle. - Snapshots
Store database files in persistent volumes or object storage for rollback.
- Migration to PostgreSQL
Export data as JSON (
.dump) and import via repository tooling before switching drivers.
Operational Tips
CLI Reference
# File-backed database
compozy start --db-driver=sqlite --db-path=./data/compozy.db
# In-memory database (data reset on restart)
compozy start --db-driver=sqlite --db-path=:memory:# Run migrations (auto-detects driver)
compozy migrate upTroubleshooting
| Error | Cause | Fix |
|---|---|---|
database is locked | Too many concurrent writes | Reduce runtime.max_concurrent_workflows, increase busy_timeout, enable WAL mode. |
pgvector provider is incompatible with SQLite driver | Vector DB configured as pgvector | Switch to Qdrant, Redis, or filesystem provider. |
no such table | Migrations not applied | Run compozy migrate up after changing drivers or deleting database file. |
permission denied | Filesystem permissions on .db file | Adjust ownership or run Compozy with proper user/group permissions. |