Aeris Documentation

Complete technical specification, REST API contracts, and operational guides for the Aeris embedded database management system.

Overview

Aeris is a single-binary embedded DBMS written in Golang. It uses bbolt as its storage engine with a Write-Ahead Log (WAL) for durability, and embeds a React web console compiled directly into the binary via go:embed. The system exposes a REST API for authentication, querying, table management, and health checks.

Core Invariant: Aeris compiles all database routines, HTTP route handlers, and frontend web assets into a single static binary. You copy one file to run the entire system.

Installation

Choose your preferred installation method. All targets receive the identical self-contained executable.

$curl -fsSL https://get.diama.dev/aeris.sh | sh

Quick Start

Start the server daemon and begin executing queries immediately.

$aeris server --port 9090 --data-dir ./aeris-data

[INFO] Storage engine initialized: bbolt (WAL active)

[INFO] Embedded Web Console listening at http://localhost:9090

[INFO] REST API routing ready at http://localhost:9090/api/v1

Open http://localhost:9090 in your browser to access the interactive CodeMirror 6 query workspace.

Architecture

Aeris is composed of four decoupled subsystems residing in the same runtime:

1. Storage Engine (bbolt)

ACID compliant B+ tree key-value store with byte-level transactions and Write-Ahead Logging.

2. HTTP Router & API

Standard net/http mux serving JSON payloads, token validation, and table introspections.

3. Static Asset Embedding

Single virtual filesystem compiled at build time via native Go 1.16+ embed package.

4. Web Console Client

React + TypeScript single-page app bundled with CodeMirror 6 and Lucide icons.

Storage & WAL Engine

Aeris uses bbolt — a B+ tree key-value store — with an append-only Write-Ahead Log (WAL) for crash recovery. All mutating transactions write to the WAL before flushing to bbolt, guaranteeing durability across ungraceful shutdowns.

Property	Specification	Description
Storage Engine	bbolt	B+ tree key-value store with single-writer, multiple-reader concurrency.
Sync Mode	WAL + fdatasync	Append-only write-ahead log flushes to disk on transaction commit.
Concurrency	Single-writer / MVCC	Serialized writes, lock-free concurrent reads via bbolt transactions.

Embedded Web Console

The console enables direct browser access without separate database clients like DBeaver or TablePlus. Features include:

▸CodeMirror 6 editor with SQL syntax highlighting and keyword completion.
▸Schema tree visualizer with instant column types and row-count metrics.
▸Inline JSON and tabular result renderers with CSV export.

Auth & Permissions

Aeris supports Bearer token authentication via the POST /api/v1/auth/login endpoint. Tokens are scoped to read-only or read-write privilege levels per session.

Note: The GET /api/v1/health endpoint is publicly accessible and does not require authentication. All other endpoints require a valid Bearer token.

REST API Overview

Every query, mutation, and schema inspection can be performed via standard HTTP JSON requests.

Header	Format	Required
Authorization	Bearer <token>	Required (except for /health and /auth/login)
Content-Type	application/json	Yes (for POST requests)

POST /api/v1/auth/login

Authenticate and retrieve a session token for subsequent API calls.

cURL

curl -X POST http://localhost:9090/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "..."}'

POST /api/v1/query

Execute arbitrary SQL statements and receive structured tabular data or row modification counts.

curl -X POST http://localhost:9090/api/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer aeris_...95e0" \
  -d '{"query": "SELECT id, name, latency_ms FROM nodes WHERE status = \'active\' LIMIT 10;"}'

Response Format

Response (200 OK)

{
  "status": "ok",
  "execution_time_ms": 1.24,
  "columns": ["id", "name", "latency_ms"],
  "rows": [
    [1, "edge-sgp-01", 2.4],
    [2, "edge-jkt-02", 8.1]
  ]
}

GET /api/v1/tables

List all registered tables, column schemas, index layouts, and estimated record counts.

GET /api/v1/health

Retrieve daemon process health, uptime, active connections, and buffer pool stats.

aeris server

Start the server runtime with custom binding flags.

Flag	Default	Description
--port	9090	TCP port to bind web console and REST API.
--data-dir	./data	Directory storing WAL and B+ tree page files.
--in-memory	false	Run volatile in-memory engine without disk persistence.

aeris cli

Launch an interactive terminal REPL connected to a local or remote Aeris instance.

aeris backup

Perform an atomic hot snapshot of the database file without stopping active transactions.