Get vector search working in under a minute:

Step 1: Start PostgreSQL with NeuronDB

# Start NeuronDB (CPU profile, default)
docker compose up -d neurondb

# Wait for service to be healthy (about 30-60 seconds)
docker compose ps

Step 2: Create Extension

# Connect and create extension
psql "postgresql://neurondb:neurondb@localhost:5433/neurondb" \
  -c "CREATE EXTENSION IF NOT EXISTS neurondb;"

Step 3: Create Table, Insert Vectors, and Search

# Create table, insert vectors, create index, and search
psql "postgresql://neurondb:neurondb@localhost:5433/neurondb" <<EOF
CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT,
  embedding vector(3)
);

INSERT INTO documents (content, embedding) VALUES
  ('Machine learning algorithms', '[0.1,0.2,0.3]'::vector),
  ('Neural networks and deep learning', '[0.2,0.3,0.4]'::vector),
  ('Natural language processing', '[0.3,0.4,0.5]'::vector);

CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

SELECT id, content, embedding <=> '[0.15,0.25,0.35]'::vector AS distance
FROM documents
ORDER BY embedding <=> '[0.15,0.25,0.35]'::vector
LIMIT 3;
EOF

Expected output:

 id |              content               |     distance      
----+------------------------------------+-------------------
  1 | Machine learning algorithms        | 0.141421356237309
  2 | Neural networks and deep learning  | 0.173205080756888
  3 | Natural language processing       | 0.244948974278318
(3 rows)

[!SUCCESS] Congratulations! You've successfully set up vector search. The results show documents ordered by similarity to your query vector, with the closest match first.

[!SECURITY] The default password (neurondb) is for development only. Always change it in production by setting POSTGRES_PASSWORD in your .env file. See Service URLs & ports for connection details.

NeuronDB enables you to build powerful AI applications directly in PostgreSQL:

-- Find similar documents with metadata filters
SELECT content, embedding <=> query_vector AS similarity
FROM documents
WHERE category = 'technology'
  AND created_at > '2024-01-01'
ORDER BY embedding <=> query_vector
LIMIT 10;

-- Generate embedding for query
WITH query AS (SELECT embed_text('your question') AS q_vec)
-- Retrieve relevant context
SELECT content, embedding <=> q.q_vec AS distance
FROM documents, query q
ORDER BY embedding <=> q.q_vec
LIMIT 5;

Choose what you need:

Option 1: Use published images (recommended)

Pull pre-built images from GitHub Container Registry:

# Pull latest images
docker compose pull

# Start services
docker compose up -d

# Wait for services to be healthy (30-60 seconds)
docker compose ps

# Verify all services are running
./scripts/neurondb-healthcheck.sh quick

What you'll see:

• 5 services starting: neurondb, neuronagent, neuronmcp, neurondesk-api, neurondesk-frontend
• All services should show "healthy" status after initialization

Option 2: Build from source

# Build and start all services
docker compose up -d --build

# Monitor build progress (first time takes 5-10 minutes)
docker compose logs -f

# Once built, wait for services to be healthy
docker compose ps

# Verify all services are running
./scripts/neurondb-healthcheck.sh quick

Build time: First build takes 5-10 minutes depending on your system. Subsequent starts are 30-60 seconds.

[!SECURITY] Default credentials are for development only. In production, set strong passwords via environment variables or .env file.

Install components directly on your system without Docker.

Install the NeuronDB extension directly into your existing PostgreSQL installation.

cd NeuronDB
make
sudo make install

CREATE EXTENSION neurondb;

shared_preload_libraries = 'neurondb'

sudo systemctl restart postgresql

# Vector index settings
neurondb.hnsw_ef_search = 40          # HNSW search quality
neurondb.enable_seqscan = on          # Allow sequential scans

# Memory settings
neurondb.maintenance_work_mem = 256MB # Index build memory

-- Check current extension version
SELECT extversion FROM pg_extension WHERE extname = 'neurondb';

-- Expected output: 2.0

-- Upgrade to latest (if newer version available)
ALTER EXTENSION neurondb UPDATE;

-- Verify upgrade (returns JSONB with detailed version info)
SELECT neurondb.version();

For detailed installation instructions, see NeuronDB/install.md.

Install NeuronMCP, NeuronAgent, and NeuronDesktop from source with automated scripts.

Quick Installation:

# Install all components
sudo ./scripts/install-components.sh

# Install specific components
sudo ./scripts/install-components.sh neuronmcp neuronagent

# Install with system services enabled
sudo ./scripts/install-components.sh --enable-service

Prerequisites:

• Go 1.23+ (for building)
• PostgreSQL 16+ with NeuronDB extension
• Node.js 18+ (for NeuronDesktop)

Manual Installation:

See Native Installation Guide for detailed instructions.

Service Management:

# Start services
./scripts/manage-services.sh start

# Check status
./scripts/manage-services.sh status

# View logs
./scripts/manage-services.sh logs neuronagent

For service management details, see Service Management Guide.

Use NeuronDB as a PostgreSQL extension only, without the Agent, MCP, or Desktop services.

Benefits:

• ✅ No extra services or ports
• ✅ Minimal resource footprint
• ✅ Full vector search, ML algorithms, and embeddings
• ✅ Works with any PostgreSQL client

Installation:

Follow the Native install steps above. That's it! You now have vector search and ML capabilities in PostgreSQL.

Usage:

-- Create a table with vectors
CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT,
  embedding VECTOR(1536)
);

-- Create HNSW index
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

-- Vector similarity search
SELECT id, content
FROM documents
ORDER BY embedding <=> '[0.1, 0.2, ...]'::vector
LIMIT 10;

No additional services, ports, or configuration required!

• Start here: Docs/documentation.md (documentation index)
• Beginner walkthrough: Docs/getting-started/simple-start.md - Step-by-step guide for beginners
• Technical quick start: QUICKSTART.md - Fast setup for experienced users
• Complete guide: Docs/getting-started/installation.md - Detailed installation options
• Official docs: neurondb.ai/docs - Online documentation

• NeuronDB/README.md
• NeuronAgent/README.md
• NeuronMCP/README.md
• NeuronDesktop/README.md

• Examples index
• Semantic search docs example
• RAG chatbot (PDFs) example
• Agent tools example
• MCP integration example

NeuronDB includes a benchmark suite to evaluate vector search, hybrid search, and RAG performance.

Run all benchmarks:

cd NeuronDB/benchmark
./run_bm.sh

This validates connectivity and runs the vector/hybrid/RAG benchmark groups.

NeuronDB HNSW index building performance compared to pgvector:

Test Environment:

• PostgreSQL: 18.0
• CPU: Apple Silicon (aarch64-apple-darwin)
• RAM: 256MB maintenance_work_mem
• Index Parameters: m = 16, ef_construction = 200
• Distance Metric: L2 (Euclidean)

Performance Formula:

The speedup factor is calculated as:

$$Speedup = \frac{Time_{pgvector}}{Time_{NeuronDB}}$$

For throughput (vectors per second):

$$Throughput = \frac{Vector\ Count}{Build\ Time\ (seconds)}$$

Results:

Optimizations Applied:

• ✅ In-memory graph building using maintenance_work_mem
• ✅ Efficient neighbor finding during insert (not after flush)
• ✅ SIMD-optimized distance calculations (AVX2/NEON)
• ✅ Squared distance optimization (avoiding sqrt() overhead)
• ✅ Optimized flush with pre-computed neighbors

Benchmark Scripts:

• NeuronDB/benchmark/vector/neurondb_vector.sql - NeuronDB optimized HNSW benchmark
• NeuronDB/benchmark/vector/pgvector.sql - pgvector reference benchmark

How to Run:

# Create separate databases for fair comparison
psql -d postgres -c "CREATE DATABASE neurondb_bench;"
psql -d postgres -c "CREATE DATABASE pgvector_bench;"

# Run NeuronDB benchmark
psql -d neurondb_bench -f NeuronDB/benchmark/vector/neurondb_vector.sql

# Run pgvector benchmark
psql -d pgvector_bench -f NeuronDB/benchmark/vector/pgvector.sql

To reproduce benchmark results:

# Use exact Docker image tags (see releases)
docker pull ghcr.io/neurondb/neurondb-postgres:v1.0.0-pg17-cpu

# Run with documented hardware profile
cd NeuronDB/benchmark
./run_bm.sh --hardware-profile "cpu-8core-16gb"

# Individual benchmark with exact parameters
cd NeuronDB/benchmark/vector
./run_bm.py --prepare --load --run \
  --datasets sift-128-euclidean \
  --max-queries 1000 \
  --index hnsw \
  --ef-search 40

# Vector benchmark
cd NeuronDB/benchmark/vector
./run_bm.py --prepare --load --run --datasets sift-128-euclidean --max-queries 100

# Hybrid benchmark
cd NeuronDB/benchmark/hybrid
./run_bm.py --prepare --load --run --datasets nfcorpus --model all-MiniLM-L6-v2

# RAG benchmark
cd NeuronDB/benchmark/rag
./run_bm.py --prepare --verify --run --benchmarks mteb

The root docker-compose.yml supports multiple GPU backends via Docker Compose profiles:

Available profiles:

• CPU (default): docker compose up -d or docker compose --profile cpu up -d
• CUDA (NVIDIA): docker compose --profile cuda up -d
• ROCm (AMD): docker compose --profile rocm up -d
• Metal (Apple Silicon): docker compose --profile metal up -d

Ports differ per profile (see env.example):

• CPU: POSTGRES_PORT=5433 (default)
• CUDA: POSTGRES_CUDA_PORT=5434
• ROCm: POSTGRES_ROCM_PORT=5435
• Metal: POSTGRES_METAL_PORT=5436

Example: Start with CUDA support

# Stop CPU services first
docker compose down

# Start CUDA profile
docker compose --profile cuda up -d

# Verify CUDA services are running
docker compose ps

# Connect to CUDA-enabled PostgreSQL
psql "postgresql://neurondb:neurondb@localhost:5434/neurondb" -c "SELECT neurondb.version();"

GPU Requirements:

• CUDA: NVIDIA GPU with CUDA 12.2+ and nvidia-container-toolkit
• ROCm: AMD GPU with ROCm 5.7+ and proper device access
• Metal: Apple Silicon (M1/M2/M3) Mac with macOS 13+

# Stop everything (keep data volumes)
docker compose down

# Stop everything (delete data volumes - WARNING: deletes all data!)
docker compose down -v

# See status of all services
docker compose ps

# Tail logs for all services
docker compose logs -f

# Tail logs for specific services
docker compose logs -f neurondb neuronagent neuronmcp neurondesk-api neurondesk-frontend

# View last 100 lines of logs
docker compose logs --tail=100

# View logs for specific service
docker compose logs neurondb

Key operational considerations for production:

• Vacuum and bloat: Vector indexes require periodic maintenance. See NeuronDB/docs/operations/playbook.md
• Index rebuild guidance: When and how to rebuild HNSW/IVF indexes. See NeuronDB/docs/troubleshooting.md
• Memory configuration: Tune neurondb.maintenance_work_mem and index-specific parameters. See NeuronDB/docs/configuration.md

• Contributing: CONTRIBUTING.md
• Security: SECURITY.md - Report security issues to security@neurondb.ai
• License: LICENSE (proprietary)
• Changelog: CHANGELOG.md - See what's new
• Roadmap: ROADMAP.md - Planned features
• Releases: RELEASE.md - Release process