CleaveDB Logo
Back to Home
Getting Started

Installation

CleaveDB is built for extreme performance using hardware-accelerated memory access and vector search. You can choose to run the pre-compiled standalone binary (recommended for most users) or compile the core engine from source out of Rust and C++ SIMD.

A

Download Pre-Compiled Binary (Recommended)

You do not need to install Python, Rust, or C++ build tools. We provide a single, self-contained executable that has the hardware-accelerated C++ AVX-512 extensions and Rust engine fully baked in.

  1. Go to the Releases page on GitHub.
  2. Download CleaveShell.exe (or the equivalent binary for your OS).
  3. Double-click the executable to instantly start the database server and interactive shell.
Windows SmartScreen NoticeBecause CleaveDB is an independent, open-source project, the Windows installer does not use an expensive corporate EV certificate. When downloading or running the .exe, Windows or Edge might flag it as "unrecognized". To bypass this, click Keep → Keep anyway in Edge, and More info → Run anyway on the blue Windows screen.
B

Compile from Source (Advanced / Contributors)

If you want to modify the source code, extend the engine, or contribute to the project, you can compile the engine from scratch.

1. Prerequisites

  • Python 3.10+ (Required for the CleaveQL Interpreter and TCP Server bindings)
  • Rust Toolchain (2021 Edition) (Install via rustup.rs). The install takes ~1 minute.
  • C++ Build Tools (Required for compiling the AVX-512 and AVX2 hardware extensions).
  • Go 1.21+ (Optional, only needed if compiling the distributed cluster coordinator logic).

2. Install Python Dependencies

This installs everything from websockets and numpy for the AI semantic search, up to maturin, which is the Rust-to-Python compiler tool.

$pip install -r requirements.txt

3. Run the Master Build Script

Simply run the orchestrator script, which compiles the C++ SIMD layers, the Go Coordinator, and the Rust storage engine via PyO3/maturin:

$python build.py
What build.py does in the background:
  1. Compiles the C++ SIMD layers for vector dot-product, softmax, and matrix multiplication.
  2. Compiles the optional Go Coordinator into a shared library.
  3. Compiles the Custom Rust Storage Engine (B+Tree, WAL, Buffer Pool).
  4. Uses maturin to bind the Rust engine into a Python module (cleavedb3_storage) and installs it.

4. Start the Server

Once compiled, start the TCP / WebSocket / HTTP server:

$python cleavedb_server.py

Authentication & Multi-Tenancy Setup

CleaveDB enforces authentication before any query. Every client must register or login through the CLI shell before the database allows connections.

cleavedb-auth> register
Username: david
Password: ********
Dev Password (superuser override): ********
Security Question: What was the name of your first pet?
Answer: rover

Passwords are hashed natively with PBKDF2-HMAC-SHA256 (100,000 iterations, 16-byte random salt). Security questions and answers are encrypted at rest with AES-256-GCM.

← IntroductionNext: Quick Start →