Document ChromaDB SQLite limitation for multi-worker/multi-replica deployments

ChromaDB's default local PersistentClient uses SQLite which is not fork-safe.
When uvicorn forks multiple workers, concurrent writes crash workers instantly.
Added warnings and guidance across env config, HA/scaling, performance,
troubleshooting, Docker Swarm, Helm, Redis, RAG, and enterprise architecture docs.

https://claude.ai/code/session_01TPoquFdHG6dZxRrZ4Jormh
This commit is contained in:
Claude
2026-02-16 11:04:51 +00:00
parent 32378222c6
commit c270f4b934
8 changed files with 136 additions and 15 deletions

View File

@@ -419,6 +419,20 @@ If you set `UVICORN_WORKERS` to any value greater than 1, you **must** configure
:::
:::danger
**Critical: Default ChromaDB (SQLite) Not Compatible with Multiple Workers**
In addition to Redis, you must also address the **vector database**. The default ChromaDB uses a local SQLite-backed `PersistentClient` that is **not fork-safe**. When uvicorn forks multiple workers, concurrent writes to the same SQLite file will crash workers instantly during document uploads (`Child process died`).
You must either:
- Switch to a client-server vector database (`VECTOR_DB=pgvector`, `milvus`, or `qdrant`)
- Run ChromaDB as a separate HTTP server and set `CHROMA_HTTP_HOST` / `CHROMA_HTTP_PORT`
See the [Scaling & HA guide](/troubleshooting/multi-replica#6-worker-crashes-during-document-upload-chromadb--multi-worker) for details.
:::
## Verification
### Verify Redis Connection