Simple Start

Run these commands to verify Docker is installed correctly:

# Check Docker version
docker --version

# Check Docker Compose version
docker compose version

# Verify Docker is running
docker ps

Expected output:

Docker version 20.10.0 or higher
Docker Compose version v2.0.0 or higher
CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES

If you see errors, install Docker from docker.com.

If the service shows as "unhealthy" or keeps restarting:

1. Check logs:

   View logs

   Copy

   docker compose logs neurondb

2. Common issues:
   • Port 5433 already in use → Stop the conflicting service
   • Not enough memory → Allocate more RAM to Docker
   • Disk space full → Free up disk space
3. Get help: See Troubleshooting Guide

Prerequisites

• PostgreSQL 16, 17, or 18 installed
• PostgreSQL development headers (postgresql-dev or postgresql-devel)
• C compiler (gcc or clang)
• Make utility

1. Build the Extension

# Navigate to NeuronDB directory
cd NeuronDB

# Build the extension
make

# Install the extension
sudo make install

2. Configure PostgreSQL

Add to postgresql.conf:

# Enable the extension
shared_preload_libraries = 'neurondb'

Then restart PostgreSQL:

# On Linux (systemd)
sudo systemctl restart postgresql

# On macOS (Homebrew)
brew services restart postgresql@16

3. Create the Extension

Connect to your database:

psql -d your_database_name

Then run:

-- Create the extension
CREATE EXTENSION neurondb;

-- Verify installation
SELECT neurondb.version();

Expected output: 3.0 (or current version)

4. Test with a Basic Query

-- Create a test table
CREATE TABLE test (
  id SERIAL,
  vec vector(3)
);

-- Insert a vector
INSERT INTO test (vec) VALUES ('[1,2,3]'::vector);

-- Query it
SELECT * FROM test;

-- Clean up
DROP TABLE test;

What is a Vector?

A vector is an array of numbers that represents data in a multi-dimensional space. For example:

• [1.0, 0.0, 0.0] is a 3-dimensional vector
• In AI, vectors often represent embeddings (dense numerical representations of text, images, etc.)

What is Vector Search?

Vector search finds similar vectors by calculating distances. The <=> operator uses cosine distance:

• Lower distance = more similar
• Higher distance = less similar

What is an Embedding?

An embedding is a vector representation of data (text, images, etc.) that captures semantic meaning. Similar concepts have similar embeddings.

Why Use NeuronDB?

NeuronDB adds vector search capabilities directly to PostgreSQL, so you can:

• Store vectors alongside your regular data
• Use SQL to query vectors
• Combine vector search with traditional SQL filters
• Leverage PostgreSQL's ACID guarantees

Q: Do I need all services running?

A: No! You can run just NeuronDB (the database) if you only need vector search. The other services (Agent, MCP, Desktop) are optional.

Q: Can I use my existing PostgreSQL?

A: Yes! You can install NeuronDB into your existing PostgreSQL installation. See Native Installation.

Q: What's the difference between Docker and native install?

A:

• Docker: Everything is isolated, easy to remove, no system changes
• Native: Direct integration with your PostgreSQL, more control, production-like

Q: How do I stop everything?

# Stop all services (keeps data)
docker compose down

# Stop and remove all data
docker compose down -v

Q: Where is my data stored?

A: In Docker volumes. Use docker volume ls to see them. Data persists even if you stop containers.