Simple Start Guide

Get a working local environment with minimal friction

This guide walks you through setup step by step. If you know Docker and PostgreSQL, use the Technical Quickstart.

Goal

What you'll accomplish:

Get NeuronDB running locally
Create your first vector table
Perform your first similarity search
Understand the basic concepts

Time required: 5-10 minutes

Choose Your Path

Pick the method that works best for you:

Method	Best For	Time	Difficulty	Prerequisites
Docker (recommended)	Fastest start, easiest setup	5 min	Easy	Docker installed
Native build	Custom setup, production-like	30+ min	Advanced	PostgreSQL dev headers, C compiler

Docker handles all dependencies automatically. You do not need to install PostgreSQL or configure it. Everything runs in isolated containers.

Docker Quickstart (Recommended)

Minimal setup (copy-paste)

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 follow Step 4 below for your first vector search.

Prerequisites Checklist

Before you begin, make sure you have:

Docker 20.10+ installed
Docker Compose 2.0+ installed
4GB+ RAM available
5-10 minutes of time
Ports available: 5433, 8080, 8081, 3000 (optional)

Verify Docker Installation

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.

Step-by-Step Instructions

Step 1: Start the Database

From the repository root, start NeuronDB (the compose file is in docker/):


# Start NeuronDB (database only)
docker compose -f docker/docker-compose.yml up -d neurondb

# Or: cd docker && docker compose up -d neurondb

Docker downloads and starts a PostgreSQL container with the NeuronDB extension. The -d flag runs it in the background.

What to expect:

First time: Downloads images (may take 2-5 minutes)
Subsequent runs: Starts immediately (30-60 seconds)

Step 2: Wait for Services to Be Healthy

Check that the service is running:


# Check service status (from repo root)
docker compose -f docker/docker-compose.yml ps

Expected output:

NAME                STATUS
neurondb-cpu        healthy (or running)

Wait for "healthy" status. This means PostgreSQL initialized and accepts connections. This takes 30 to 60 seconds.

What if it's not healthy?

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

Check logs:


docker compose -f docker/docker-compose.yml logs neurondb

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
Get help: See Troubleshooting Guide

Step 3: Verify Installation

Connect to the database and verify NeuronDB is installed:


# Create the extension (if not already created)
docker compose -f docker/docker-compose.yml exec neurondb psql -U neurondb -d neurondb -c "CREATE EXTENSION IF NOT EXISTS neurondb;"

# Check the version
docker compose -f docker/docker-compose.yml exec neurondb psql -U neurondb -d neurondb -c "SELECT neurondb.version();"

Expected output:

CREATE EXTENSION
 version
---------
 2.0
(1 row)

[!SUCCESS] Great! If you see version 2.0 (or similar), NeuronDB is installed and working correctly.

Step 4: Your First Vector Search

Let's create a simple example to understand how vector search works:


docker compose -f docker/docker-compose.yml exec neurondb psql -U neurondb -d neurondb <<EOF
-- Step 1: Create a table to store documents with embeddings
CREATE TABLE test_vectors (
  id SERIAL PRIMARY KEY,
  name TEXT,
  embedding vector(3)  -- 3-dimensional vectors for this example
);

-- Step 2: Insert some sample data
INSERT INTO test_vectors (name, embedding) VALUES
  ('apple', '[1.0, 0.0, 0.0]'::vector),
  ('banana', '[0.0, 1.0, 0.0]'::vector),
  ('orange', '[0.5, 0.5, 0.0]'::vector);

-- Step 3: Query the data
SELECT name, embedding FROM test_vectors;

-- Step 4: Find the most similar vector to a query
SELECT 
  name,
  embedding <=> '[0.9, 0.1, 0.0]'::vector AS distance
FROM test_vectors
ORDER BY embedding <=> '[0.9, 0.1, 0.0]'::vector
LIMIT 3;

-- Step 5: Clean up
DROP TABLE test_vectors;
EOF

Expected output:

 name   |   embedding    
--------+----------------
 apple  | [1,0,0]
 banana | [0,1,0]
 orange | [0.5,0.5,0]
(3 rows)

 name   |     distance      
--------+-------------------
 apple  | 0.141421356237309
 orange | 0.424264068711929
 banana | 0.905538513813742
(3 rows)

[!NOTE] Understanding the results: The <=> operator calculates cosine distance. Lower distance = more similar. Apple is closest to [0.9, 0.1, 0.0] because both are close to [1, 0, 0].

Native Quickstart (Advanced)

Native Installation Steps

For advanced users only - Requires PostgreSQL development headers and C compiler

Prerequisites

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

Installation Steps

1. Build the Extension


# From repository root
./build.sh
# Or manually: PG_CONFIG=/path/to/pg_config make && sudo make install

[!NOTE] What's happening? The build compiles the C extension. See INSTALL.md for full steps. make install copies the extension into PostgreSQL's extension directory.

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: 2.0

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;

🎓 Understanding What You Just Did

Key Concepts Explained

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

Next Steps

Continue your journey:

Read architecture.md to understand the moving parts
Try examples from src/examples/
Explore the documentation index
If something fails, check troubleshooting.md
Try the Quickstart Data Pack for sample data

Quick Tips

Helpful Tips for Success

Docker Tips

Docker is recommended for the easiest setup
Keep containers running - They use minimal resources when idle
Use docker compose -f docker/docker-compose.yml logs neurondb to see what's happening
Port conflicts? Change ports in docker/docker-compose.yml

Learning Tips

Start simple - Get it running first, then explore advanced features
Read the architecture guide to understand how components work together
Try the examples - They're designed to teach concepts
Check troubleshooting if you encounter issues

Development Tips

Use the SQL recipes - Ready-to-run examples in getting-started/recipes/
Try the CLI helpers - Scripts in scripts/ for common tasks
Explore the examples - Working code in src/examples/

❓ Common Questions

❓ Frequently Asked Questions

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?

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?


# From repo root (keeps data)
docker compose -f docker/docker-compose.yml down

# Stop and remove all data
docker compose -f docker/docker-compose.yml 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.

Document	Description
Architecture Guide	Understand how components work
Installation Guide	Detailed installation options
Troubleshooting	Common issues and solutions
Documentation index	Full documentation index

Simple Start Guide

Simple Start Guide

Goal

Choose Your Path

Docker Quickstart (Recommended)

Minimal setup (copy-paste)

Prerequisites Checklist

Step-by-Step Instructions

Step 1: Start the Database

Step 2: Wait for Services to Be Healthy

Step 3: Verify Installation

Step 4: Your First Vector Search

Native Quickstart (Advanced)

Prerequisites

Installation Steps

1. Build the Extension

2. Configure PostgreSQL

3. Create the Extension

4. Test with a Basic Query

🎓 Understanding What You Just Did

What is a Vector?

What is Vector Search?

What is an Embedding?

Why Use NeuronDB?

Next Steps

Quick Tips

Docker Tips

Learning Tips

Development Tips

❓ Common Questions

Q: Do I need all services running?

Q: Can I use my existing PostgreSQL?

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

Q: How do I stop everything?

Q: Where is my data stored?

Related Documentation