AionDB logo aiondb v0.3 vector update
AionDB v0.3 is live: vector search becomes a first-class engine surface with pgvector-style SQL, HNSW, IVF-flat, Qdrant-style filters, and published recall/latency benchmarks. See the v0.3 vector update.

Installation

AionDB is distributed as source, prebuilt container images for local evaluation, and, starting with the v0.5 release, prebuilt release binaries with a checksum-verifying installer.

Get the source

Every command on this page runs from inside a checkout of the AionDB repository. Clone it first:

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

Fastest Start

For local evaluation, use the published container images. This path does not build AionDB locally.

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

If your machine already runs PostgreSQL (or anything else) on port 5432 the aiondb container will fail to bind. Edit .env and set AIONDB_PGWIRE_PORT=5433 (or another free port) before starting compose.

Open AionDB Studio at http://127.0.0.1:8082. The Studio container connects automatically to the aiondb service through pgwire.

For terminal access, use another shell:

source .env
PGPASSWORD="$AIONDB_BOOTSTRAP_PASSWORD" \
psql "host=127.0.0.1 port=${AIONDB_PGWIRE_PORT:-5432} dbname=default user=$AIONDB_BOOTSTRAP_USER sslmode=disable"

Run the smoke SQL file:

source .env
PGPASSWORD="$AIONDB_BOOTSTRAP_PASSWORD" \
psql "host=127.0.0.1 port=${AIONDB_PGWIRE_PORT:-5432} dbname=default user=$AIONDB_BOOTSTRAP_USER sslmode=disable" \
  -f integrations/psql-smoke.sql

Stop the server:

docker compose down

Delete the local data volume:

docker compose down -v

The compose profile exposes PostgreSQL wire protocol on 5432 and AionDB Studio on 8082. It uses the bootstrap credentials you place in .env, disables pgwire TLS, and enables unencrypted local storage so it works immediately on developer machines. Replace the example password before using the stack anywhere except a loopback-only local evaluation.

By default Compose pulls prebuilt images from GitHub Container Registry: ghcr.io/ayoubnabil/aiondb:main and ghcr.io/ayoubnabil/aiondb-studio:main. Set AIONDB_IMAGE or AIONDB_STUDIO_IMAGE in .env to use a pinned release tag, a SHA tag, or an image published from a fork. The Docker GitHub Actions workflow publishes the default main images on every push to main, so this path only downloads images and starts containers. After the first image pull, repeated starts should only take the time needed for container creation and the /readyz health check. If the image pull is denied, the GHCR package is not public (or you are rate-limited); authenticate with docker login ghcr.io or build from source.

docker-compose.yml is self-contained and can also run without a repository checkout; see packaging/INSTALL.md for that variant.

To run only the database server without Studio:

docker compose up

Docker Without Compose

docker run --rm -it \
  -p 127.0.0.1:5432:5432 \
  -e AIONDB_BOOTSTRAP_USER=admin \
  -e AIONDB_BOOTSTRAP_PASSWORD='ReplaceWithLongUniquePassword42!' \
  -v aiondb-data:/var/lib/aiondb/data \
  ghcr.io/ayoubnabil/aiondb:main

Release Binary

Starting with the v0.5 release, each tagged GitHub Release attaches aiondb-<version>-<os>-<arch>.tar.gz archives with matching .sha256 checksum files for linux x86_64, linux aarch64, and macos arm64. Until the first such release is published there is nothing to download here; use the container images or build from source.

Install the latest released binary into ~/.local/bin:

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

The installer detects the OS and CPU architecture, downloads the matching archive from GitHub Releases, verifies the SHA256 checksum, and copies the aiondb binary into the install directory. It never uses sudo and never writes outside the install directory and a temporary directory.

Environment overrides:

# Install a specific release tag instead of the latest release.
curl -fsSL https://raw.githubusercontent.com/ayoubnabil/aiondb/main/packaging/install.sh | AIONDB_VERSION=v0.5.0 sh

# Install into a different directory (must be writable without sudo).
curl -fsSL https://raw.githubusercontent.com/ayoubnabil/aiondb/main/packaging/install.sh | AIONDB_INSTALL_DIR="$HOME/bin" sh

To verify a release archive manually instead:

curl -fsSLO https://github.com/ayoubnabil/aiondb/releases/download/v0.5.0/aiondb-0.5.0-linux-x86_64.tar.gz
curl -fsSLO https://github.com/ayoubnabil/aiondb/releases/download/v0.5.0/aiondb-0.5.0-linux-x86_64.tar.gz.sha256
sha256sum -c aiondb-0.5.0-linux-x86_64.tar.gz.sha256
tar -xzf aiondb-0.5.0-linux-x86_64.tar.gz

See packaging/INSTALL.md for the full install notes.

Build From Source

cargo build --release -p aiondb-server --bin aiondb
target/release/aiondb --version

Build local Docker images only when changing Dockerfiles or testing a fork that has not published images yet:

docker compose -f docker-compose.yml -f docker-compose.build.yml --profile studio up --build

Run an in-memory server:

AIONDB_BOOTSTRAP_USER=admin \
AIONDB_BOOTSTRAP_PASSWORD='ReplaceWithLongUniquePassword42!' \
target/release/aiondb --ephemeral

Run with persistent local storage:

AIONDB_BOOTSTRAP_USER=admin \
AIONDB_BOOTSTRAP_PASSWORD='ReplaceWithLongUniquePassword42!' \
AIONDB_ALLOW_UNENCRYPTED_STORAGE=true \
target/release/aiondb --data-dir ./data/aiondb --storage-backend durable

Initialize a Local Instance

aiondb init prepares a persistent local instance instead of passing everything through environment variables. 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

Use --output <path> to write the config file somewhere other than <data-dir>/aiondb.conf.

--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.

If the data directory is not on a LUKS/dm-crypt encrypted filesystem, init prints a note and the server refuses persistent storage until AIONDB_ALLOW_UNENCRYPTED_STORAGE=true is uncommented in the generated config file (development only).

Local Archive

Create a minimal binary archive:

make package-local

The archive lands under target/ and contains the aiondb binary, public README and license files, governance and security notes, integrations/psql-smoke.sql, packaging/INSTALL.md, packaging/kubernetes/aiondb.yaml, packaging/kubernetes/aiondb-production.yaml, packaging/systemd/aiondb.service, and packaging/systemd/aiondb.env.example. It is meant for local evaluation and release-candidate checks, not a signed production distribution.

Notes

Observability stays bound to loopback inside the container and is used by the container healthcheck through /readyz. This matches the policy that observability should not be exposed directly.

For production-like tests, set explicit secrets, mount the data volume on encrypted storage, and remove AIONDB_ALLOW_UNENCRYPTED_STORAGE=true.

Kubernetes Profile

The local Kubernetes evaluation profile lives at packaging/kubernetes/aiondb.yaml. A stricter production-like starting point lives at packaging/kubernetes/aiondb-production.yaml. Both define a single-replica StatefulSet, persistent volume claim, ConfigMap, Secret templates, and ClusterIP Service for pgwire on 5432. The evaluation profile keeps TLS disabled and enables unencrypted local storage. The production-like profile requires TLS, mounts explicit certificate material, and leaves unencrypted storage disabled. Observability is used for /readyz and /livez probes but is not published as a Service.

Before applying it, replace the Secret placeholder, review the image tag, and review the storage class defaults. If you are testing an unpublished local build, build or load aiondb:local into the cluster and update the StatefulSet image accordingly.

systemd Template

The service template lives at packaging/systemd/aiondb.service.

Before using it:

Backup and Restore

aiondb dump and aiondb restore operate on a stopped data directory. They authenticate against the on-disk catalog, so AIONDB_BOOTSTRAP_USER and AIONDB_BOOTSTRAP_PASSWORD must match the credentials the server was started with. Output and input paths are relative to ./backups/ in the current working directory, not to --data-dir.

AIONDB_BOOTSTRAP_USER=dev \
AIONDB_BOOTSTRAP_PASSWORD='ReplaceWithLongUniquePassword42!' \
AIONDB_ALLOW_UNENCRYPTED_STORAGE=true \
target/release/aiondb dump --data-dir ./data/aiondb --output dump.sql
# writes ./backups/dump.sql

AIONDB_BOOTSTRAP_USER=dev \
AIONDB_BOOTSTRAP_PASSWORD='ReplaceWithLongUniquePassword42!' \
AIONDB_ALLOW_UNENCRYPTED_STORAGE=true \
target/release/aiondb restore --data-dir ./data/aiondb-new --input dump.sql
# reads ./backups/dump.sql

Running these commands without the bootstrap env vars fails with must be superuser to BACKUP DATABASE (42501).

Smoke Test

PGPASSWORD='ReplaceWithLongUniquePassword42!' \
psql "host=127.0.0.1 port=5432 dbname=default user=admin sslmode=disable" \
  -f integrations/psql-smoke.sql

If this fails, fix the server command, environment, or network path before testing graph, vector, ORM, or benchmark behavior.