mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 15:24:32 +00:00
71 lines
1.7 KiB
Markdown
71 lines
1.7 KiB
Markdown
---
|
|
title: Troubleshooting
|
|
sort: 140
|
|
section-id: operations
|
|
keywords: troubleshooting, errors, diagnostics, FAQ, common problems, debug
|
|
description: Common NeuralDB errors, diagnostic techniques, and frequently asked questions
|
|
language: en
|
|
---
|
|
|
|
# Troubleshooting
|
|
|
|
## Connection Issues
|
|
|
|
### `FATAL: password authentication failed`
|
|
|
|
```bash
|
|
sudo -u neuraldb neuraldb-cli
|
|
```
|
|
```sql
|
|
ALTER USER neuraldb PASSWORD 'new-password';
|
|
```
|
|
|
|
### `could not connect to server: Connection refused`
|
|
|
|
```bash
|
|
systemctl status neuraldb
|
|
ss -tlnp | grep 5432
|
|
journalctl -u neuraldb -n 50
|
|
```
|
|
|
|
### Connection slots exhausted
|
|
|
|
```sql
|
|
SELECT count(*), state FROM pg_stat_activity GROUP BY state;
|
|
SELECT pg_terminate_backend(pid) FROM pg_stat_activity
|
|
WHERE state = 'idle' AND state_change < NOW() - INTERVAL '10 minutes';
|
|
```
|
|
|
|
## Vector Query Issues
|
|
|
|
### Slow Vector Searches
|
|
|
|
```sql
|
|
EXPLAIN (ANALYZE, BUFFERS)
|
|
SELECT id FROM documents ORDER BY embedding <=> '[...]' LIMIT 10;
|
|
```
|
|
|
|
Common causes: missing LIMIT, HNSW graph not in memory, ef_search too low.
|
|
|
|
```sql
|
|
SELECT * FROM neuraldb_stat_vector_indexes; -- check hnsw_in_memory
|
|
SET enable_seqscan = off; -- force index for debugging
|
|
```
|
|
|
|
### Low Recall
|
|
|
|
```sql
|
|
SET hnsw.ef_search = 200;
|
|
SET neuraldb.vector_scan = 'exact'; -- compare against exact search
|
|
```
|
|
|
|
## FAQ
|
|
|
|
**Q: Can I use NeuralDB as a drop-in for PostgreSQL?**
|
|
Yes. NeuralDB implements the PostgreSQL wire protocol.
|
|
|
|
**Q: What should `vector_buffer` be set to?**
|
|
`SELECT SUM(hnsw_graph_size_bytes) FROM neuraldb_stat_vector_indexes` — set `vector_buffer` at least this large.
|
|
|
|
**Q: Is NeuralDB compatible with pgvector?**
|
|
Yes. All pgvector types (`VECTOR`, `HALFVEC`, `SPARSEVEC`) and operators (`<=>`, `<->`, `<#>`) work without modification.
|