jormun-db/QUICKSTART.md

JormunDB Quick Start Guide

Get JormunDB running in 5 minutes.

Prerequisites

1. Install Odin

macOS:

# Using Homebrew
brew install odin

# Or download from https://odin-lang.org/docs/install/

Ubuntu/Debian:

# Download latest release
wget https://github.com/odin-lang/Odin/releases/latest/download/odin-ubuntu-amd64.tar.gz
tar -xzf odin-ubuntu-amd64.tar.gz
sudo mv odin /usr/local/bin/

# Verify
odin version

From Source:

git clone https://github.com/odin-lang/Odin
cd Odin
make
sudo cp odin /usr/local/bin/

2. Install RocksDB

macOS:

brew install rocksdb

Ubuntu/Debian:

sudo apt update
sudo apt install -y librocksdb-dev libsnappy-dev liblz4-dev libzstd-dev libbz2-dev

Arch Linux:

sudo pacman -S rocksdb

3. Verify Installation

# Check Odin
odin version

# Check RocksDB
pkg-config --libs rocksdb
# Should output: -lrocksdb -lstdc++ ...

Building JormunDB

Clone and Build

# Clone the repository
git clone https://github.com/yourusername/jormundb.git
cd jormundb

# Build debug version
make build

# Or build optimized release
make release

Troubleshooting Build Issues

"cannot find rocksdb"

# Check RocksDB installation
pkg-config --cflags --libs rocksdb

# If not found, install RocksDB (see prerequisites)

"odin: command not found"

# Add Odin to PATH
export PATH=$PATH:/path/to/odin

# Or install system-wide (see prerequisites)

Running the Server

Basic Usage

# Run with defaults (localhost:8002, ./data directory)
make run

You should see:

  ╔═══════════════════════════════════════════════╗
  ║                                               ║
  ║     ╦╔═╗╦═╗╔╦╗╦ ╦╔╗╔╔╦╗╔╗                      ║
  ║     ║║ ║╠╦╝║║║║ ║║║║ ║║╠╩╗                     ║
  ║    ╚╝╚═╝╩╚═╩ ╩╚═╝╝╚╝═╩╝╚═╝                     ║
  ║                                               ║
  ║   DynamoDB-Compatible Database                ║
  ║   Powered by RocksDB + Odin                   ║
  ║                                               ║
  ╚═══════════════════════════════════════════════╝

  Port: 8002 | Data Dir: ./data

Storage engine initialized at ./data
Starting DynamoDB-compatible server on 0.0.0.0:8002
Ready to accept connections!

Custom Configuration

# Custom port
make run PORT=9000

# Custom data directory
make run DATA_DIR=/tmp/jormun

# Enable verbose logging
make run VERBOSE=1

# Combine options
make run PORT=9000 DATA_DIR=/var/jormun VERBOSE=1

Environment Variables

# Set via environment
export JORMUN_PORT=9000
export JORMUN_HOST=127.0.0.1
export JORMUN_DATA_DIR=/var/jormun
make run

Testing with AWS CLI

Install AWS CLI

macOS:

brew install awscli

Ubuntu/Debian:

sudo apt install awscli

Verify:

aws --version

Configure AWS CLI

# Set dummy credentials (required but not checked by JormunDB yet)
aws configure
# AWS Access Key ID: dummy
# AWS Secret Access Key: dummy
# Default region name: us-east-1
# Default output format: json

Basic Operations

Create a Table:

aws dynamodb create-table \
    --endpoint-url http://localhost:8002 \
    --table-name Users \
    --key-schema \
        AttributeName=id,KeyType=HASH \
    --attribute-definitions \
        AttributeName=id,AttributeType=S \
    --billing-mode PAY_PER_REQUEST

List Tables:

aws dynamodb list-tables --endpoint-url http://localhost:8002

Put an Item:

aws dynamodb put-item \
    --endpoint-url http://localhost:8002 \
    --table-name Users \
    --item '{
        "id": {"S": "user123"},
        "name": {"S": "Alice"},
        "age": {"N": "30"},
        "email": {"S": "alice@example.com"}
    }'

Get an Item:

aws dynamodb get-item \
    --endpoint-url http://localhost:8002 \
    --table-name Users \
    --key '{"id": {"S": "user123"}}'

Query Items:

aws dynamodb query \
    --endpoint-url http://localhost:8002 \
    --table-name Users \
    --key-condition-expression "id = :id" \
    --expression-attribute-values '{
        ":id": {"S": "user123"}
    }'

Scan Table:

aws dynamodb scan \
    --endpoint-url http://localhost:8002 \
    --table-name Users

Delete an Item:

aws dynamodb delete-item \
    --endpoint-url http://localhost:8002 \
    --table-name Users \
    --key '{"id": {"S": "user123"}}'

Delete a Table:

aws dynamodb delete-table \
    --endpoint-url http://localhost:8002 \
    --table-name Users

Testing with AWS SDK

Node.js Example

const { DynamoDBClient, PutItemCommand, GetItemCommand } = require("@aws-sdk/client-dynamodb");

const client = new DynamoDBClient({
    endpoint: "http://localhost:8002",
    region: "us-east-1",
    credentials: {
        accessKeyId: "dummy",
        secretAccessKey: "dummy"
    }
});

async function test() {
    // Put an item
    await client.send(new PutItemCommand({
        TableName: "Users",
        Item: {
            id: { S: "user123" },
            name: { S: "Alice" }
        }
    }));

    // Get the item
    const result = await client.send(new GetItemCommand({
        TableName: "Users",
        Key: { id: { S: "user123" } }
    }));

    console.log(result.Item);
}

test();

Python Example

import boto3

dynamodb = boto3.client(
    'dynamodb',
    endpoint_url='http://localhost:8002',
    region_name='us-east-1',
    aws_access_key_id='dummy',
    aws_secret_access_key='dummy'
)

# Put an item
dynamodb.put_item(
    TableName='Users',
    Item={
        'id': {'S': 'user123'},
        'name': {'S': 'Alice'}
    }
)

# Get the item
response = dynamodb.get_item(
    TableName='Users',
    Key={'id': {'S': 'user123'}}
)

print(response['Item'])

Development Workflow

Quick Rebuild

# Fast rebuild and run
make quick

Clean Start

# Remove all build artifacts and data
make clean

# Build and run fresh
make dev

Running Tests

# Run unit tests
make test

# Run AWS CLI integration tests
make aws-test

Code Formatting

# Format all Odin files
make fmt

Common Issues

Port Already in Use

# Check what's using port 8002
lsof -i :8002

# Use a different port
make run PORT=9000

Cannot Create Data Directory

# Create with proper permissions
mkdir -p ./data
chmod 755 ./data

# Or use a different directory
make run DATA_DIR=/tmp/jormun

RocksDB Not Found

# Check installation
pkg-config --libs rocksdb

# Install if missing (see Prerequisites)

Odin Compiler Errors

# Check Odin version
odin version

# Update Odin if needed
brew upgrade odin  # macOS
# or download latest from odin-lang.org

Next Steps

• Read ARCHITECTURE.md for internals
• Check TODO.md for implementation status
• Browse source code in dynamodb/, rocksdb/, etc.

Getting Help

There is absolutely no support at this time

Benchmarking

# Run benchmarks
make bench

# Profile memory usage
make profile

# Load test
ab -n 10000 -c 100 -p item.json -T application/json \
   http://localhost:8002/

Production Deployment

JormunDB is not ready for production use just yet. But there will be easy package installs, as well as a container and a helm chart

Uninstalling

# Remove build artifacts
make clean

# Remove installed binary (if installed)
make uninstall

# Remove data directory
rm -rf ./data