- Status: Accepted
- Date: 2026-07 (retroactive record — decision dates from project inception; long-form rationale maintained in #372)
- Related: #372, #378, #381, VISION.md (Platform v-next cluster)
Open Notebook needs document storage (sources with metadata), graph relationships (notebooks ↔ sources ↔ notes), vector embeddings for semantic search, and background jobs — while staying easy to self-host for privacy-focused users. A traditional stack would be Postgres + Redis + Celery + a vector DB: four services to operate.
Use SurrealDB as the single database: documents, graph relationships, vector embeddings and (via surreal-commands) job queueing in one service. Stay with it and work through the challenges; reconsider only under the exit criteria listed in #372 (unworkable transaction conflicts, performance that tuning can't fix, unpatched critical security issue, or a mature alternative with the same consolidated benefits).
- PostgreSQL + pgvector — maturity and ecosystem, but loses graph queries and still needs Celery/Redis for jobs.
- SQLite + LiteFS — ultimate simplicity, but poor concurrency and no graph features.
- MongoDB + Redis + Celery — familiar tooling, but three services kills the self-hosting simplicity advantage.
- Hybrid (Postgres + Neo4j) — best of both worlds at an ops cost we don't want to impose on self-hosters.
- One container to run — the biggest infra advantage for self-hosted users.
- Younger ecosystem: we document more and contribute back; fewer established tuning practices.
- Transaction conflicts under concurrency turned out to be log verbosity, not failures (#362, #373) — handled with Tenacity retries.
- Major-version upgrades need deliberate migration work (v3: #378, part of the Platform v-next cluster).