DocumentationNeurondB Documentation

Background Workers

Overview

Background Workers are dedicated processes that handle async processing, monitoring, and maintenance tasks to keep your NeurondB system running optimally. These workers operate independently from query processing, ensuring that maintenance and optimization tasks don't impact query performance.

Available Workers

  • neuranq: Async job queue executor for batch operations
  • neuranmon: Auto-tuner for query performance optimization
  • neurandefrag: Index maintenance and defragmentation
  • neuranllm: LLM job processor for async generation

Benefits

  • Non-Blocking: Maintenance tasks don't impact query performance
  • Automatic: Workers run continuously without manual intervention
  • Configurable: Tune worker behavior to match your workload
  • Observable: Monitor worker status and performance metrics

neuranq - Async Job Queue

Asynchronous job queue executor with SKIP LOCKED, rate limits, retries, and poison job handling. Perfect for batch embedding generation, model inference, and long-running operations that should not block query processing.

Features

  • SKIP LOCKED Queuing: Concurrent job processing without lock contention
  • Rate Limiting: Per-tenant QPS and token budgets
  • Auto Retry: Exponential backoff for transient failures
  • Poison Jobs: Dead letter queue for failed jobs

Configuration

postgresql.conf

# postgresql.conf
neurondb.neuranq_enabled = on
neurondb.neuranq_naptime = 1000        # Check queue every 1 second
neurondb.neuranq_batch_size = 100      # Process 100 jobs per cycle
neurondb.neuranq_max_retries = 3       # Retry failed jobs 3 times

neuranmon - Auto-Tuner

Automatically tunes index parameters based on query performance and SLO targets. Adjusts ef_search, rotates caches, and tracks recall@k metrics.

What It Does

  • Monitors query latency and adjusts ef_search for HNSW indexes
  • Tracks recall@10 and recall@100 to measure search quality
  • Rotates embedding and model caches based on access patterns
  • Records performance metrics for trend analysis

Configuration

postgresql.conf

# postgresql.conf
neurondb.neuranmon_enabled = on
neurondb.neuranmon_naptime = 60000     # Check every 60 seconds
neurondb.neuranmon_target_latency_ms = 10  # Target latency SLO
neurondb.neuranmon_min_recall = 0.95   # Minimum 95% recall

neurandefrag - Index Maintenance

Automatic index maintenance: compacts HNSW graphs, re-levels layers, prunes tombstones, and schedules rebuilds for optimal performance.

Maintenance Tasks

  • Graph Compaction: Removes fragmentation from HNSW graphs after deletes and updates
  • Layer Re-leveling: Rebalances hierarchical layers for optimal search performance
  • Tombstone Pruning: Removes deleted vector markers to reclaim space
  • Rebuild Scheduling: Automatically rebuilds indexes when fragmentation exceeds threshold

Configuration

postgresql.conf

# postgresql.conf
neurondb.neurandefrag_enabled = on
neurondb.neurandefrag_naptime = 300000     # Check every 5 minutes
neurondb.neurandefrag_fragmentation_threshold = 0.30  # Rebuild at 30%

neuranllm - LLM Processor

Dedicated worker for processing LLM generation jobs asynchronously. Handles prompt processing, token generation, and response streaming without blocking database operations.

Features

  • Async Generation: Process LLM requests in the background
  • Token Streaming: Stream tokens as they're generated
  • Rate Limiting: Control API usage and costs
  • Error Handling: Automatic retries with exponential backoff

Configuration

postgresql.conf

# postgresql.conf
neurondb.neuranllm_enabled = on
neurondb.neuranllm_naptime = 5000        # Check queue every 5 seconds
neurondb.neuranllm_batch_size = 10       # Process 10 jobs per cycle
neurondb.neuranllm_max_tokens = 2048     # Maximum tokens per generation
neurondb.neuranllm_rate_limit = 100     # Requests per minute

Monitor Workers

View all worker status

-- View all worker status
SELECT * FROM neurondb_worker_status();

-- Returns:
--  worker_name  | status  |      last_run       | jobs_processed | avg_runtime_ms
-- --------------+---------+---------------------+----------------+---------------
--  neuranq      | running | 2025-11-03 12:30:15 |      427       |      12.3
--  neuranmon    | running | 2025-11-03 12:30:10 |       89       |      45.7
--  neurandefrag | running | 2025-11-03 12:28:00 |       23       |     234.8
--  neuranllm    | running | 2025-11-03 12:29:45 |       156      |      234.1

Worker Metrics

Detailed worker metrics

-- Get detailed metrics for a specific worker
SELECT * FROM neurondb_worker_metrics('neuranq')
WHERE timestamp > NOW() - INTERVAL '1 hour'
ORDER BY timestamp DESC;

-- Monitor job queue depth
SELECT 
  queue_name,
  pending_jobs,
  processing_jobs,
  completed_jobs,
  failed_jobs
FROM neurondb_queue_stats();

Worker Details

Next Steps

PreviousIndexing
NextPerformance