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 v0.1 is distributed as source, a release binary you can build locally, and prebuilt container images for local evaluation.

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.

To run only the database server without the dashboard:

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

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

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