Getting Started

Table of Contents

  1. Prerequisites
  2. Quick Installation
    1. From Crates.io
    2. From Binary Release
    3. From Source
    4. Build Dashboard (Optional)
  3. Configuration
    1. Environment Variables
    2. Configuration File
  4. Verify Installation
    1. Check Server Status
    2. Test Query
    3. Access Dashboard
  5. Using the CLI
  6. Using the Client SDK
    1. Rust
    2. Python
    3. JavaScript
  7. PM2 Deployment (Production)
  8. Next Steps

Prerequisites

Before installing Aegis-DB, ensure you have:

  • Rust 1.75+ (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh)
  • Trunk (for dashboard): cargo install trunk

Quick Installation

From Crates.io 

# Install server
cargo install aegis-server

# Install CLI
cargo install aegisdb-cli

From Binary Release 

# Download latest release (v0.2.5)
curl -LO https://github.com/AutomataNexus/Aegis-DB/releases/latest/download/aegis-db-0.2.5-linux-x86_64.tar.gz

# Extract
tar -xzf aegis-db-0.2.5-linux-x86_64.tar.gz
cd aegis-db-0.2.5-linux-x86_64

# Run server (default port 9090)
./aegis-server

From Source 

# Clone the repository
git clone https://github.com/AutomataNexus/Aegis-DB.git
cd Aegis-DB

# Build release
cargo build --release --workspace

# Run server (default port 9090)
./target/release/aegis-server

Build Dashboard (Optional) 

cd crates/aegis-dashboard
trunk build --release

Configuration

Environment Variables

Variable Description Default
AEGIS_DATA_DIR Data storage directory ./data
AEGIS_PORT Server port 9090
AEGIS_HOST Bind address 0.0.0.0
AEGIS_LOG_LEVEL Logging level info
AEGIS_TLS_CERT TLS certificate path (none)
AEGIS_TLS_KEY TLS key path (none)

Configuration File

Create aegis.toml:

[server]
host = "0.0.0.0"
port = 9090
data_dir = "/var/lib/aegis"

[auth]
enabled = true
jwt_secret = "your-secret-key-here"
session_timeout = 3600

[storage]
backend = "localfs"
compression = "lz4"

[replication]
enabled = false
mode = "single"

Verify Installation

Check Server Status 

curl http://localhost:9090/health | jq

Expected response:

{
  "status": "healthy",
  "version": "0.2.5",
  "uptime": 123
}

Test Query 

curl -X POST http://localhost:9090/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT 1 + 1 AS result"}'

Access Dashboard

Open http://localhost:8000 in your browser.

Default credentials: demo / demo

Using the CLI 

# Install CLI (from crates.io)
cargo install aegisdb-cli

# Or install from source
cargo install --path crates/aegis-cli

# Check server status (port 9090)
aegis-client -s http://localhost:9090 status

# Run queries (subcommand comes AFTER the database flag)
aegis-client -s http://localhost:9090 query "CREATE TABLE users (id INT, name TEXT)"
aegis-client -s http://localhost:9090 query "INSERT INTO users VALUES (1, 'Alice')"
aegis-client -s http://localhost:9090 query "SELECT * FROM users"

# Interactive shell
aegis-client -s http://localhost:9090 shell

Using the Client SDK

Rust 

use aegis_client::AegisClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AegisClient::connect("localhost:9090").await?;

    client.execute("CREATE TABLE users (id INT, name TEXT)").await?;
    client.execute("INSERT INTO users VALUES (1, 'Alice')").await?;

    let rows = client.query("SELECT * FROM users").await?;
    for row in rows {
        println!("{:?}", row);
    }

    Ok(())
}

Python 

from aegis_client import AegisClient

client = AegisClient("localhost:9090")

client.execute("CREATE TABLE users (id INT, name TEXT)")
client.execute("INSERT INTO users VALUES (1, 'Alice')")

for row in client.query("SELECT * FROM users"):
    print(row)

JavaScript 

import { AegisClient } from '@aegis-db/client';

const client = new AegisClient('localhost:9090');

await client.execute('CREATE TABLE users (id INT, name TEXT)');
await client.execute("INSERT INTO users VALUES (1, 'Alice')");

const rows = await client.query('SELECT * FROM users');
rows.forEach(row => console.log(row));

PM2 Deployment (Production)

Create ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'aegis-server',
    script: './target/release/aegis-server',
    cwd: '/opt/Aegis-DB',
    env: {
      AEGIS_PORT: 9090,
      AEGIS_DATA_DIR: '/var/lib/aegis',
      RUST_LOG: 'info'
    }
  }]
};

Start with PM2:

pm2 start ecosystem.config.js
pm2 save
pm2 startup

Next Steps