NeuronDB - AI Database Extension for PostgreSQL

---

Run the system in 5 minutes

From the repository root:

docker compose -f docker/docker-compose.yml up -d neurondb
docker compose -f docker/docker-compose.yml ps   # wait until healthy
docker compose -f docker/docker-compose.yml exec neurondb psql -U neurondb -d neurondb -c "CREATE EXTENSION IF NOT EXISTS neurondb; SELECT neurondb.version();"

Then run your first vector search: Simple Start or Quick Start.

Table of Contents

Expand full table of contents

• Overview
  • Key Capabilities
  • Performance Metrics
• Documentation
  • Getting Started
  • Vector Search & Indexing
  • ML Algorithms & Analytics
  • ML & Embeddings
  • Hybrid Search & Retrieval
  • Reranking
  • RAG Pipeline
  • Background Workers
  • GPU Acceleration
  • Performance & Security
  • Configuration & Operations
• Official Documentation
• Architecture
  • System Architecture
  • Vector Query Flow
  • HNSW Index Structure
• Compatibility
• Support & Community
• Contributing
• License
• Authors

---

Overview

Vectors, embeddings, and ML—inside PostgreSQL. NeuronDB keeps similarity search and models on your live rows, not in a separate database you have to sync and babysit.

HNSW · IVFFlat · kNN · hybrid full-text + vector · RAG pieces · train & predict in SQL—all first-class in the engine.

One extension: same Postgres backups, HA, and security. Start with CREATE EXTENSION neurondb;, then index and query from SQL.

Key Capabilities

Feature summary

Category	Details
Vector types	vector, vectorp, vecmap, vgraph, rtext, halfvec, binaryvec, sparsevec (8 types)
Index access methods	HNSW and IVF only. PQ and OPQ are quantization (codebook training), not separate index types. Hybrid and multi-vector search are query-level functions.
Distance metrics	L2, cosine, inner product, L1, Hamming, Jaccard, and others
ML	25+ algorithm families (train/predict/evaluate): linear regression, XGBoost, LightGBM, CatBoost, K-Means, etc.
SQL	~650+ functions and operators (vector, ML, embeddings, RAG, indexing). See FEATURES.md and SQL API.
GPU	CUDA, ROCm, Metal (distance and search; index build is CPU only). See GPU feature matrix.
Background workers	neuranq, neuranmon, neurandefrag, neuranllm

Performance Metrics

NeuronDB provides significant performance improvements over standard PostgreSQL extensions:

Index Build Performance:

The index build time for HNSW follows the relationship:

$$T_{build} = O(N \cdot \log N \cdot m \cdot ef_{construction})$$

Where:

• $N$ = number of vectors
• $m$ = number of connections per node (typically 16-32)
• $ef_{construction}$ = size of candidate list during construction (typically 64-200)

Query Performance:

Query latency for HNSW search:

$$T_{query} = O(\log N + ef_{search} \cdot k)$$

Where:

• $ef_{search}$ = size of candidate list during search (typically 40-200)
• $k$ = number of results requested

Throughput Calculation:

$$QPS = \frac{1}{T_{query}} = \frac{1}{O(\log N + ef_{search} \cdot k)}$$

[!TIP] For optimal performance, tune ef_search based on your recall requirements. Higher values improve recall but increase latency.

Documentation

Getting Started

• Installation - Install NeuronDB extension
• Extension packaging - Control file, file layout, CREATE/UPDATE/DROP EXTENSION, dump/restore
• Quick Start - Get up and running quickly

Vector Search & Indexing

• Vector Types — vector, vectorp, vecmap, vgraph, rtext, halfvec, binaryvec, sparsevec
• Indexing — HNSW and IVF indexing
• Distance Metrics — L2, cosine, inner product, and more
• Quantization — PQ and OPQ compression

ML Algorithms & Analytics

• Random Forest - Classification and regression
• Gradient Boosting - XGBoost, LightGBM, CatBoost
• Clustering - K-Means, DBSCAN, GMM, Hierarchical
• Dimensionality Reduction - PCA and PCA Whitening
• Classification - SVM, Logistic Regression, Naive Bayes, Decision Trees
• Regression - Linear, Ridge, Lasso, Deep Learning
• Outlier Detection - Z-score, Modified Z-score, IQR
• Quality Metrics - Recall@K, Precision@K, F1@K, MRR
• Drift Detection - Centroid drift, Distribution divergence
• Topic Discovery - Topic modeling and analysis
• Time Series - Forecasting and analysis
• Recommendation Systems - Collaborative filtering

ML & Embeddings

• Embedding Generation - Text, image, multimodal embeddings
• Model Inference - ONNX runtime, batch processing
• Model Management - Load, export, version models
• AutoML - Automated hyperparameter tuning
• Feature Store - Feature management and versioning

Hybrid Search & Retrieval

• Hybrid Search - Combine vector and full-text search
• Multi-Vector - Multiple embeddings per document
• Faceted Search - Category-aware retrieval
• Temporal Search - Time-decay relevance scoring

Reranking

• Cross-Encoder - Neural reranking models
• LLM Reranking - GPT/Claude-powered scoring
• ColBERT - Late interaction models
• Ensemble - Combine multiple strategies

RAG Pipeline

• Complete RAG Support - End-to-end RAG
• LLM Integration - Hugging Face and OpenAI
• Document Processing - Text processing and NLP

Background Workers

• neuranq - Async job queue executor
• neuranmon - Live query auto-tuner
• neurandefrag - Index maintenance
• neuranllm - LLM job processor

GPU Acceleration

• CUDA Support - NVIDIA GPU acceleration
• ROCm Support - AMD GPU acceleration
• Metal Support - Apple Silicon GPU acceleration
• Auto-Detection - Automatic GPU detection

Performance & Security

• SIMD Optimization - AVX2/AVX512, NEON optimization
• Security - Encryption, privacy, RLS
• Monitoring - Monitoring views and Prometheus

Configuration & Operations

• Configuration - Essential configuration options
• Troubleshooting - Common issues and solutions (getting started and operations)

Official Documentation

https://www.neurondb.ai/docs — API reference (~650+ SQL functions), tutorials, deployment, and troubleshooting.

Architecture

NeuronDB follows PostgreSQL's architectural patterns and extends the database with AI capabilities.

System Architecture

graph TB
    subgraph SQL["SQL Interface Layer"]
        FUNC["~650+ SQL Functions"]
        TYPES["Vector Types: vector, vectorp, vecmap, vgraph, rtext, halfvec, binaryvec, sparsevec"]
        OPS["Distance Operators: <->, <=>, <#>"]
    end
    
    subgraph VECTOR["Vector Operations"]
        INDEX["HNSW/IVF Indexes"]
        DIST["Distance Metrics: L2, Cosine, Inner Product"]
        QUANT["Quantization: PQ, OPQ, int8, fp16"]
    end
    
    subgraph ML["Machine Learning"]
        ALGO["25+ ML algorithm families: RF, XGBoost, LightGBM, etc."]
        INFER["Model Inference: ONNX Runtime"]
        EMBED["Embedding Generation: Text, Image, Multimodal"]
    end
    
    subgraph SEARCH["Search & Retrieval"]
        HYBRID[Hybrid Search<br/>Vector + Full-text]
        RERANK[Reranking<br/>Cross-encoder, LLM, ColBERT]
        RAG[RAG Pipeline<br/>Document Processing]
    end
    
    subgraph WORKERS["Background Workers"]
        NEURANQ[neuranq<br/>Job Queue]
        NEURANMON[neuranmon<br/>Query Tuner]
        NEURANDEFRAG[neurandefrag<br/>Index Maintenance]
        NEURANLLM[neuranllm<br/>LLM Processor]
    end
    
    subgraph GPU["GPU Acceleration"]
        CUDA[CUDA<br/>NVIDIA]
        ROCM[ROCm<br/>AMD]
        METAL[Metal<br/>Apple Silicon]
    end
    
    subgraph PG["PostgreSQL Core"]
        STORAGE[Storage Engine]
        WAL[Write-Ahead Log]
        SPI[Server Programming Interface]
        SHMEM[Shared Memory]
    end
    
    SQL --> VECTOR
    SQL --> ML
    SQL --> SEARCH
    VECTOR --> INDEX
    ML --> INFER
    SEARCH --> RAG
    WORKERS --> PG
    GPU --> VECTOR
    GPU --> ML
    VECTOR --> PG
    ML --> PG
    SEARCH --> PG

Vector Query Flow

sequenceDiagram
    participant Client
    participant PG as PostgreSQL
    participant ND as NeuronDB Extension
    participant Index as HNSW/IVF Index
    participant GPU as GPU Backend
    
    Client->>PG: SELECT ... ORDER BY embedding <=> query
    PG->>ND: Parse vector query
    ND->>ND: Optimize query plan
    
    alt Index Available
        ND->>Index: Search index (ef_search)
        Index->>ND: Return candidate vectors
        ND->>GPU: Compute distances (SIMD/GPU)
        GPU-->>ND: Distance scores
        ND->>ND: Sort and filter (LIMIT)
    else Sequential Scan
        ND->>PG: Scan table
        ND->>GPU: Compute all distances
        GPU-->>ND: Distance scores
        ND->>ND: Sort and filter
    end
    
    ND-->>PG: Return results
    PG-->>Client: Query results

HNSW Index Structure

graph TD
    subgraph HNSW["HNSW (Hierarchical Navigable Small World)"]
        L2[Layer 2<br/>Few nodes, long edges]
        L1[Layer 1<br/>More nodes, medium edges]
        L0[Layer 0<br/>All nodes, short edges]
    end
    
    L2 -->|Entry Point| L1
    L1 -->|Entry Point| L0

[!NOTE] HNSW creates a multi-layer graph where higher layers have fewer nodes and longer edges, enabling fast approximate nearest neighbor search. The search starts at the top layer and navigates down to find the closest neighbors.

Compatibility

Compatibility matrix

PostgreSQL	Status	Platforms	Architectures
16.x	✅ Supported	Ubuntu 20.04/22.04, Debian 11/12, Rocky Linux 8/9, macOS 13+	linux/amd64, linux/arm64, darwin/arm64
17.x	✅ Supported	Ubuntu 20.04/22.04, Debian 11/12, Rocky Linux 8/9, macOS 13+	linux/amd64, linux/arm64, darwin/arm64
18.x	✅ Supported	Ubuntu 20.04/22.04, Debian 11/12, Rocky Linux 8/9, macOS 13+	linux/amd64, linux/arm64, darwin/arm64

[!NOTE] NeuronDB supports PostgreSQL 16, 17, and 18. The extension validates the PostgreSQL version at creation time. GPU acceleration requires platform-specific drivers (CUDA 12.2+, ROCm 5.7+, or macOS 13+ for Metal).

Support & Community

Get help

Resource	Link	Description
GitHub Issues	Report Issues	Bug reports and feature requests
GitHub Discussions	Join Discussion	Community Q&A and discussions
Email Support	support@neurondb.ai	Direct email support
Security Issues	security@neurondb.ai	Report security vulnerabilities
Documentation	neurondb.ai/docs	Complete documentation

Contributing

We welcome contributions. See CONTRIBUTING.md for:

Contribution guidelines

• ✅ Code style guidelines - Follow PostgreSQL coding standards
• ✅ Development workflow - Fork, branch, test, submit PR
• ✅ Testing requirements - All changes must include tests
• ✅ Pull request process - Review and approval workflow
• ✅ Documentation - Update docs for new features

License

NeuronDB is released under a proprietary license. See LICENSE for details.

License summary

Usage Type	Permitted	Notes
Personal Use	✅ Yes	Binary code only
Commercial Use	❌ No	Contact for licensing
Source Modifications	❌ No	No derivatives allowed
Redistribution	❌ No	Contact for distribution rights

For commercial licensing, contact support@neurondb.ai

Authors

neurondb, Inc.
Email: support@neurondb.ai
Website: https://neurondb.ai/docs

---