docs: expand README and documentation for production release

- Update README.md status from 'educational proof-of-concept' to 'production-ready' - Fix binary size: 286KB -> 3.3MB - Update test count: 162/35 -> 262/56 - Add sections: benchmarks, Docker, clients, security, config, monitoring, backup, cross-modal queries, troubleshooting - Expand project structure with all 49 modules and ~14,100 LOC - Add 10 new docs: performance, deployment, configuration, clients, security, monitoring, backup, crossmodal, troubleshooting, changelog - Expand docs/en: architecture, baraql, installation, protocol - Update docs/bg: architecture, installation - Update docs/index.md with new links - Update .gitignore for __pycache__, rust/target, nim binaries
2026-05-06 17:19:16 +03:00
parent e1bae0c7a0
commit 8993cdc6f3
20 changed files with 4162 additions and 277 deletions
@@ -0,0 +1,408 @@
+# Troubleshooting Guide
+
+## Installation Issues
+
+### Nim Not Found
+
+```
+im: command not found
+```
+
+**Solution:**
+
+```bash
+# Linux/macOS
+curl https://nim-lang.org/choosenim/init.sh -sSf | sh
+
+# Add to PATH
+echo 'export PATH=$HOME/.nimble/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### SSL Compilation Error
+
+```
+Error: BaraDB requires SSL support. Compile with -d:ssl
+```
+
+**Solution:** Always compile with `-d:ssl`:
+
+```bash
+nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim
+```
+
+### Missing Dependencies
+
+```
+Error: cannot open file: hunos
+```
+
+**Solution:**
+
+```bash
+nimble install -d -y
+```
+
+## Runtime Issues
+
+### Port Already in Use
+
+```
+Error: unhandled exception: Address already in use [OSError]
+```
+
+**Solution 1:** Change port:
+
+```bash
+BARADB_PORT=5433 ./build/baradadb
+```
+
+**Solution 2:** Kill existing process:
+
+```bash
+lsof -ti:5432 | xargs kill -9
+# or
+fuser -k 5432/tcp
+```
+
+### Permission Denied on Data Directory
+
+```
+Error: cannot create directory: Permission denied
+```
+
+**Solution:**
+
+```bash
+mkdir -p ./data
+chmod 755 ./data
+# Or use a different directory
+BARADB_DATA_DIR=/tmp/baradb_data ./build/baradadb
+```
+
+### Out of Memory
+
+```
+Error: out of memory
+```
+
+**Solution:** Reduce memory usage:
+
+```bash
+BARADB_MEMTABLE_SIZE_MB=32 \
+BARADB_CACHE_SIZE_MB=128 \
+BARADB_VECTOR_EF_CONSTRUCTION=100 \
+./build/baradadb
+```
+
+### Disk Full
+
+```
+Error: No space left on device
+```
+
+**Solution:**
+
+```bash
+# Check disk usage
+df -h
+
+# Trigger compaction to reclaim space
+curl -X POST http://localhost:8080/api/admin/compact
+
+# Or manually
+./build/baradadb --compact
+```
+
+## Query Issues
+
+### Syntax Error
+
+```
+Error: Syntax error at position 15: unexpected token
+```
+
+**Solution:** Check query syntax:
+
+```sql
+-- Correct
+SELECT name, age FROM users WHERE age > 18;
+
+-- Incorrect (missing comma)
+SELECT name age FROM users WHERE age > 18;
+```
+
+### Table Not Found
+
+```
+Error: Table 'users' does not exist
+```
+
+**Solution:** Create the schema first:
+
+```sql
+CREATE TYPE User {
+  name: str,
+  age: int32
+};
+```
+
+### Type Mismatch
+
+```
+Error: Cannot compare int32 with str
+```
+
+**Solution:** Use correct types:
+
+```sql
+-- Correct
+SELECT * FROM users WHERE age > 18;
+
+-- Incorrect
+SELECT * FROM users WHERE age > '18';
+```
+
+### Timeout
+
+```
+Error: Query execution timeout
+```
+
+**Solution:** Add LIMIT or optimize:
+
+```sql
+-- Add limit
+SELECT * FROM large_table LIMIT 1000;
+
+-- Use index
+SELECT * FROM users WHERE id = 123;
+```
+
+## Connection Issues
+
+### Connection Refused
+
+```
+Connection refused: localhost:5432
+```
+
+**Solution:**
+
+```bash
+# Check if server is running
+ps aux | grep baradadb
+
+# Start server
+./build/baradadb
+
+# Check firewall
+sudo ufw status
+sudo ufw allow 5432
+```
+
+### Authentication Failed
+
+```
+Error: Authentication failed
+```
+
+**Solution:**
+
+```bash
+# Check JWT secret matches
+BARADB_AUTH_ENABLED=true \
+BARADB_JWT_SECRET="correct-secret" \
+./build/baradadb
+```
+
+```python
+client.authenticate("correct-jwt-token")
+```
+
+### SSL/TLS Errors
+
+```
+Error: TLS handshake failed
+```
+
+**Solution:**
+
+```bash
+# Disable TLS for local testing
+BARADB_TLS_ENABLED=false ./build/baradadb
+
+# Or provide valid certificates
+BARADB_TLS_ENABLED=true \
+BARADB_CERT_FILE=/path/to/cert.pem \
+BARADB_KEY_FILE=/path/to/key.pem \
+./build/baradadb
+```
+
+## Performance Issues
+
+### Slow Queries
+
+**Diagnose:**
+
+```bash
+# Check query plan
+curl -X POST http://localhost:8080/api/explain \
+  -d '{"query": "SELECT * FROM large_table"}'
+```
+
+**Solutions:**
+
+1. Add indexes:
+```sql
+CREATE INDEX idx_users_name ON users(name);
+```
+
+2. Use LIMIT:
+```sql
+SELECT * FROM users LIMIT 100;
+```
+
+3. Increase cache:
+```bash
+BARADB_CACHE_SIZE_MB=1024 ./build/baradadb
+```
+
+### High CPU Usage
+
+**Causes:**
+- Compaction running
+- Large vector search without HNSW
+- Complex graph traversal
+
+**Solutions:**
+
+```bash
+# Adjust compaction interval
+BARADB_COMPACTION_INTERVAL_MS=300000 ./build/baradadb
+
+# Use approximate vector search
+SELECT /*+ APPROXIMATE */ * FROM vectors
+ORDER BY cosine_distance(embedding, [...])
+LIMIT 10;
+```
+
+### High Memory Usage
+
+**Monitor:**
+
+```bash
+curl http://localhost:8080/metrics | grep memory
+```
+
+**Solutions:**
+
+```bash
+# Reduce memtable size
+BARADB_MEMTABLE_SIZE_MB=64
+
+# Reduce cache
+BARADB_CACHE_SIZE_MB=256
+
+# Limit HNSW graph size
+BARADB_VECTOR_M=8
+```
+
+## Cluster Issues
+
+### Raft Split-Brain
+
+```
+Warning: Multiple leaders detected
+```
+
+**Solution:** Ensure odd number of nodes (3, 5, 7). Restart minority partition.
+
+### Replication Lag
+
+```
+Warning: Replication lag > 10s
+```
+
+**Solution:**
+
+```bash
+# Check network latency
+ping replica-node
+
+# Increase replication threads
+BARADB_REPLICATION_THREADS=4 ./build/baradadb
+
+# Switch to async replication
+BARADB_REPLICATION_MODE=async
+```
+
+### Shard Imbalance
+
+```
+Warning: Shard 3 has 2× data of others
+```
+
+**Solution:**
+
+```bash
+# Trigger rebalancing
+curl -X POST http://localhost:8080/api/admin/rebalance
+```
+
+## Data Corruption
+
+### Checksum Mismatch
+
+```
+Error: SSTable checksum mismatch
+```
+
+**Solution:**
+
+```bash
+# Remove corrupted SSTable (data will be recovered from WAL)
+rm ./data/sstables/corrupted.sst
+
+# Restart and recover
+./build/baradadb --recover
+```
+
+### WAL Corruption
+
+```
+Error: WAL segment corrupted
+```
+
+**Solution:**
+
+```bash
+# Truncate WAL to last good segment
+./build/baradadb --truncate-wal --wal-sequence=15419
+
+# Restore from snapshot if needed
+./build/baradadb --recover --checkpoint=/backup/snapshot.db
+```
+
+## Debug Mode
+
+Enable debug logging for detailed diagnostics:
+
+```bash
+BARADB_LOG_LEVEL=debug \
+BARADB_LOG_FILE=/tmp/baradb_debug.log \
+./build/baradadb
+```
+
+## Getting Help
+
+If the issue persists:
+
+1. Check logs: `tail -f /var/log/baradb/baradb.log`
+2. Check metrics: `curl http://localhost:8080/metrics`
+3. Run diagnostics: `./build/baradadb --diagnose`
+4. Open an issue with:
+   - BaraDB version (`./build/baradadb --version`)
+   - OS and architecture
+   - Relevant log excerpts
+   - Steps to reproduce