Installation Guide

Install the NeuronDB PostgreSQL extension via Docker or from source.

New here? Start with Simple Start.

Choose your method

Prerequisites

• PostgreSQL: 16, 17, or 18 (for native install)
• OS: Linux, macOS, or Windows (WSL2)
• Docker: For containerized install

Source build only: C toolchain, pg_config, make. See INSTALL.md for ML library prerequisites (XGBoost, LightGBM, CatBoost). Optional: GPU support (CUDA, ROCm, Metal).

Method 1: Docker

Copy
git clone <repository-url>
cd neurondb

docker compose -f docker/docker-compose.yml up -d

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

• Compose file: docker/docker-compose.yml. See docker/README.md and docker/docker.sh for GPU profiles.

Method 2: Native installation

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

See INSTALL.md and Native Installation for details.

Method 3: Source build (manual)

From the repository root:

Copy
PG_CONFIG=/path/to/pg_config make
sudo PG_CONFIG=/path/to/pg_config make install

Then in PostgreSQL:

Copy
CREATE EXTENSION neurondb;

See INSTALL.md for full steps.

Method 4: Package Installation

Install using platform-specific packages (DEB/RPM), if available.

Copy
# Debian/Ubuntu
sudo dpkg -i neurondb_*.deb

# RHEL/CentOS
sudo rpm -i neurondb_*.rpm

See Packaging Documentation for package build instructions.

Database Setup

Create Database

Copy
createdb neurondb

Install Extension

Copy
psql -d neurondb -c "CREATE EXTENSION neurondb;"

For NeuronAgent or NeuronDesktop database migrations, see their respective repositories.

Verification

Verify NeuronDB

Copy
psql -d neurondb -c "SELECT neurondb.version();"

For verifying NeuronAgent, NeuronMCP, or NeuronDesktop, see their repositories.

Configuration

NeuronDB configuration

• Configuration reference — GUCs, shared_preload_libraries, etc.
• Environment variables for Docker are in .env.example at the repository root.

Configuration for NeuronAgent, NeuronMCP, and NeuronDesktop is documented in their respective repositories.

Next Steps

1. Quick Start Guide — Run your first queries
2. Components — NeuronDB component overview

Troubleshooting

Common Issues

• Connection Errors: Verify database is running and connection parameters are correct
• Extension Not Found: Ensure NeuronDB extension is installed in the database
• Port Conflicts: Check if ports 5432, 8080, 8081, 3000 are available
• Build Errors: Verify all prerequisites are installed

For detailed troubleshooting, see:

• Troubleshooting (this repo)
• Official Documentation

Official Documentation

For comprehensive installation guides and platform-specific instructions: ** https://www.neurondb.ai/docs/installation**