Concurrent Write Contention on SQLite Metadata Store
warningChroma uses SQLite for metadata storage. SQLite has limited concurrent write capability due to database-level write locks. High concurrent upsert, update, or delete operations cause lock contention, resulting in 'database is locked' errors, timeout failures, and degraded write throughput. Read operations are not affected but may be delayed by long-running write transactions.
Write operation error rate increases with concurrent write load. 'Database is locked' errors appear in logs. Write throughput plateaus or decreases as concurrency increases beyond 1-2 concurrent writers. Write operation latency p95/p99 increases significantly under load. Read latency increases during heavy write periods.
1. Diagnose: Check logs for 'database is locked' or 'database timeout' errors. Measure concurrent write operations (should be 1-2 for SQLite). Profile write transaction duration. 2. Immediate mitigation: Implement write serialization/queueing at application layer. Use retry with exponential backoff for lock errors. Increase SQLite busy_timeout setting (default 5s). 3. Optimize writes: Batch multiple operations into single transactions to reduce lock contention. Use upsert operations efficiently. Avoid long-running transactions. 4. Architectural fix: For high write concurrency (>10 concurrent writers), migrate to client-server Chroma deployment which handles concurrency better than embedded SQLite. Consider alternative metadata backend if available. 5. Monitor: Track write concurrency, lock wait time, and error rates. Alert on lock errors or latency degradation.