Getting Started

This page gets AionDB running locally from prebuilt containers, creates a development user, connects with psql, and runs the first query. It is the shortest path for a local evaluation.

Requirements

Docker Compose for the fastest prebuilt-image path.
Rust toolchain compatible with the workspace only if you build from source.
psql if you want to connect through the PostgreSQL wire protocol.
Python 3.8 or newer only if you want to rebuild this documentation site.

Get the source

Every command below runs from inside a checkout of the AionDB repository:

git clone https://github.com/ayoubnabil/aiondb.git
cd aiondb

Fastest Start

This path pulls published GHCR images and starts containers. It does not compile Rust or build Docker images on the user machine.

cp quickstart.env .env
docker compose --profile studio up

Open Studio at http://127.0.0.1:8082. To run only the database server, omit the studio profile:

docker compose up

Install a Release Binary

Starting with the v0.5 release, tagged GitHub Releases attach prebuilt aiondb binaries for linux x86_64, linux aarch64, and macos arm64. Once a release with binaries is published, this one-liner downloads the latest binary, verifies its SHA256 checksum, and installs it into ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/ayoubnabil/aiondb/main/packaging/install.sh | sh

Until the first v0.5 release is published there are no binaries to download; use the container images above or build from source below. See Installation for installer options and manual checksum verification.

Build From Source

cargo build --release -p aiondb-server --bin aiondb

During development, cargo run is usually enough:

cargo run -p aiondb-server --bin aiondb -- --help

Start an in-memory server

Use --ephemeral for a clean local session. Data is stored in memory and disappears when the process exits.

AIONDB_BOOTSTRAP_USER=dev \
AIONDB_BOOTSTRAP_PASSWORD='ReplaceWithLongUniquePassword42!' \
cargo run -p aiondb-server --bin aiondb -- --ephemeral

AIONDB_BOOTSTRAP_USER and AIONDB_BOOTSTRAP_PASSWORD create a local development role at startup. Keep this pattern for driver tests because it exercises authentication instead of relying on anonymous local behavior.

Connect

PGPASSWORD='ReplaceWithLongUniquePassword42!' \
psql "host=127.0.0.1 port=5432 dbname=default user=dev sslmode=disable"

The PGPASSWORD value must match AIONDB_BOOTSTRAP_PASSWORD from the server command above. If you change one, change the other.

Run a small SQL query:

CREATE TABLE tickets (
    id INT PRIMARY KEY,
    title TEXT,
    priority TEXT
);

INSERT INTO tickets VALUES
    (1, 'pgwire smoke test', 'high'),
    (2, 'embedded api check', 'normal');

SELECT id, title FROM tickets WHERE priority = 'high';

Expected result:

 id |       title
----+-------------------
  1 | pgwire smoke test

Initialize a persistent instance

aiondb init prepares a persistent local instance in one step. It creates the data directory, writes a commented aiondb.conf (owner read/write only) with strong generated bootstrap credentials, prints the credentials once, and prints the exact command to start the server. It refuses to overwrite a non-empty data directory or an existing config file.

target/release/aiondb init --data-dir ./data/aiondb
target/release/aiondb serve --config ./data/aiondb/aiondb.conf

Store the printed bootstrap password: it is shown only once (it is also written to the config file). If the data directory is not on an encrypted filesystem, init prints a note and the server refuses persistent storage until you uncomment AIONDB_ALLOW_UNENCRYPTED_STORAGE=true in the generated config file (development only).

--config accepts a KEY=VALUE file using the same keys as the AIONDB_* environment variables. Real environment variables take precedence over file values (priority: environment > file > defaults), and startup fails if the file is missing, unreadable, or contains an unknown key. See Configuration for the full key list.

Persistent local data

Alternatively, configure a data directory by hand for durable local testing:

AIONDB_BOOTSTRAP_USER=dev \
AIONDB_BOOTSTRAP_PASSWORD='ReplaceWithLongUniquePassword42!' \
AIONDB_ALLOW_UNENCRYPTED_STORAGE=true \
cargo run -p aiondb-server --bin aiondb -- --data-dir ./data/aiondb

Persistent storage expects filesystem-level encryption for production-like setups. AIONDB_ALLOW_UNENCRYPTED_STORAGE=true is a development override.

Embedded Rust

Use the embedded API when the database should run in the same process as a Rust application:

use aiondb_embedded::Database;

fn main() -> aiondb_embedded::DbResult<()> {
    let db = Database::in_memory()?;
    let conn = db.connect_anonymous("default", "app")?;

    conn.execute("CREATE TABLE notes (id INT PRIMARY KEY, body TEXT);")?;
    conn.execute("INSERT INTO notes VALUES (1, 'hello from embedded mode');")?;
    let _rows = conn.execute("SELECT id, body FROM notes;")?;

    Ok(())
}

Next steps

Core Concepts explains the data model.
Tutorial walks through SQL, graph labels, and vector scoring together.
Interfaces covers server and embedded usage.
Limitations lists current boundaries.