Getting Started with NeurondB

Introduction

NeurondB is a PostgreSQL extension that provides GPU-accelerated vector search, ONNX model inference, and hybrid retrieval. It offers AI and machine learning capabilities in PostgreSQL. This guide covers installation, configuration, and your first semantic search queries.

NeurondB enables you to:

• Perform fast similarity search on high-dimensional vectors
• Run ONNX model inference directly in PostgreSQL
• Combine vector, keyword, and metadata filters for hybrid retrieval
• Build RAG pipelines with SQL workflows
• Train and deploy machine learning models using SQL

Why NeurondB? NeurondB provides a solution for vector search, machine learning, and AI workloads. It combines vector search, ML inference, hybrid retrieval, and RAG pipelines in one extension.

Requirements

Before installing NeurondB, ensure you have:

• PostgreSQL 16, 17, or 18 (server + development headers)
• Build toolchain: gcc/clang, make, autoconf, libtool
• Optional: CUDA-enabled GPU for accelerated search and inference
• Internet access for downloading models or dependencies

Installation

Build NeurondB from source on your platform of choice. Each snippet installs prerequisites, clones the repository, and compiles the extension.

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y postgresql-17 postgresql-server-dev-17 build-essential \
    libcurl4-openssl-dev libssl-dev zlib1g-dev

git clone https://github.com/pgElephant/NeurondB.git
cd NeurondB
make PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
sudo make install PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config

macOS (Homebrew)

brew install postgresql@17

git clone https://github.com/pgElephant/NeurondB.git
cd NeurondB
./build.sh                    # Prepare build environment
make PG_CONFIG=/opt/homebrew/opt/postgresql@17/bin/pg_config
sudo make install PG_CONFIG=/opt/homebrew/opt/postgresql@17/bin/pg_config

Rocky Linux / RHEL

sudo dnf install -y postgresql17-server postgresql17-devel gcc make \
    curl-devel openssl-devel zlib-devel

git clone https://github.com/pgElephant/NeurondB.git
cd NeurondB
./build.sh                    # Prepare build environment
make PG_CONFIG=/usr/pgsql-17/bin/pg_config
sudo make install PG_CONFIG=/usr/pgsql-17/bin/pg_config

Quick Start Checklist

Validate your installation and run the core NeurondB commands in minutes.

Verify Extension

-- Ensure extension is available
SELECT extname, extversion
FROM   pg_extension
WHERE  extname = 'neurondb';

-- Check GPU support (if available)
SELECT * FROM neurondb_gpu_info();

-- List available vector functions
SELECT proname, pronargs
FROM   pg_proc
WHERE  proname LIKE 'vector_%' OR proname LIKE 'neurondb_%'
ORDER  BY proname
LIMIT  15;

Create Sample Data

-- Create a simple documents table
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT,
    embedding vector(384)
);

-- Insert sample documents with manual vectors
INSERT INTO documents (title, content, embedding) VALUES
    ('PostgreSQL Guide', 'Introduction to PostgreSQL database', 
     '[' || array_to_string((SELECT array_agg(random()::float4) FROM generate_series(1, 384)), ',') || ']'::vector),
    ('Vector Search', 'Understanding vector similarity search', 
     '[' || array_to_string((SELECT array_agg(random()::float4) FROM generate_series(1, 384)), ',') || ']'::vector),
    ('Machine Learning', 'ML algorithms and neural networks', 
     '[' || array_to_string((SELECT array_agg(random()::float4) FROM generate_series(1, 384)), ',') || ']'::vector);

Run First Vector Search

-- Create a query vector
WITH query_vec AS (
    SELECT '[' || array_to_string((SELECT array_agg(random()::float4) FROM generate_series(1, 384)), ',') || ']'::vector(384) AS qv
)
SELECT 
    d.id,
    d.title,
    d.content,
    vector_l2_distance(d.embedding, qv.qv) AS distance
FROM documents d, query_vec qv
ORDER BY distance
LIMIT 5;

Configure PostgreSQL

Load NeurondB at startup and adjust optional GPU settings in postgresql.conf.

shared_preload_libraries = 'neurondb'

# Optional GPU settings
neurondb.gpu_enabled = on
neurondb.gpu_backend = 'cuda'
neurondb.gpu_memory_pool_mb = 2048
neurondb.gpu_fail_open = on

# Apply and restart PostgreSQL
ALTER SYSTEM SET shared_preload_libraries = 'neurondb';
# sudo systemctl restart postgresql

Initialize and Query

Create the extension, define your vector schema, and run the first semantic search query.

Create Extension

CREATE EXTENSION neurondb;

Create a Vector Table

CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT,
    embedding vector(384)
);

Insert & Search

-- Insert documents with vector embeddings
INSERT INTO documents (title, content, embedding) VALUES
    ('Machine Learning', 'Introduction to ML', 
     '[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]'::vector(384)),
    ('Deep Learning', 'Neural networks and backpropagation', 
     '[0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]'::vector(384));

-- Query similar documents using L2 distance
SELECT 
    title, 
    content,
    vector_l2_distance(embedding, '[0.15, 0.25, 0.35, 0.45, 0.55, 0.65, 0.75, 0.85]'::vector(384)) AS distance
FROM documents
ORDER BY distance
LIMIT 10;

-- Alternative: Use distance operator <-> (L2) or <=> (cosine)
SELECT 
    title,
    embedding <-> '[0.15, 0.25, 0.35, 0.45, 0.55, 0.65, 0.75, 0.85]'::vector(384) AS l2_distance,
    embedding <=> '[0.15, 0.25, 0.35, 0.45, 0.55, 0.65, 0.75, 0.85]'::vector(384) AS cosine_distance
FROM documents
ORDER BY l2_distance
LIMIT 10;

Next Steps

• Vector Indexing - Configure HNSW, IVF, and quantization strategies for large-scale search.
• ONNX Inference - Deploy ONNX models and batch infer directly in PostgreSQL.
• Hybrid Retrieval - Combine vector, keyword, and metadata filters for production search.
• RAG Pipelines - Build retrieval augmented generation pipelines with SQL workflows.