jormun-db/QUICKSTART.md

# JormunDB Quick Start Guide

Get JormunDB running in 5 minutes.

## Prerequisites

### 1. Install Odin

**macOS:**
```bash
# Using Homebrew
brew install odin

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

**Ubuntu/Debian:**
```bash
# 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:**
```bash
git clone https://github.com/odin-lang/Odin
cd Odin
make
sudo cp odin /usr/local/bin/
```

### 2. Install RocksDB

**macOS:**
```bash
brew install rocksdb
```

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install -y librocksdb-dev libsnappy-dev liblz4-dev libzstd-dev libbz2-dev
```

**Arch Linux:**
```bash
sudo pacman -S rocksdb
```

### 3. Verify Installation

```bash
# Check Odin
odin version

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

## Building JormunDB

### Clone and Build

```bash
# 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"**
```bash
# Check RocksDB installation
pkg-config --cflags --libs rocksdb

# If not found, install RocksDB (see prerequisites)
```

**"odin: command not found"**
```bash
# Add Odin to PATH
export PATH=$PATH:/path/to/odin

# Or install system-wide (see prerequisites)
```

## Running the Server

### Basic Usage

```bash
# 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

```bash
# 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

```bash
# 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:**
```bash
brew install awscli
```

**Ubuntu/Debian:**
```bash
sudo apt install awscli
```

**Verify:**
```bash
aws --version
```

### Configure AWS CLI

```bash
# 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:**
```bash
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:**
```bash
aws dynamodb list-tables --endpoint-url http://localhost:8002
```

**Put an Item:**
```bash
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:**
```bash
aws dynamodb get-item \
    --endpoint-url http://localhost:8002 \
    --table-name Users \
    --key '{"id": {"S": "user123"}}'
```

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

**Scan Table:**
```bash
aws dynamodb scan \
    --endpoint-url http://localhost:8002 \
    --table-name Users
```

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

**Delete a Table:**
```bash
aws dynamodb delete-table \
    --endpoint-url http://localhost:8002 \
    --table-name Users
```

## Testing with AWS SDK

### Node.js Example

```javascript
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

```python
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

```bash
# Fast rebuild and run
make quick
```

### Clean Start

```bash
# Remove all build artifacts and data
make clean

# Build and run fresh
make dev
```

### Running Tests

```bash
# Run unit tests
make test

# Run AWS CLI integration tests
make aws-test
```

### Code Formatting

```bash
# Format all Odin files
make fmt
```

## Common Issues

### Port Already in Use

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

# Use a different port
make run PORT=9000
```

### Cannot Create Data Directory

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

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

### RocksDB Not Found

```bash
# Check installation
pkg-config --libs rocksdb

# Install if missing (see Prerequisites)
```

### Odin Compiler Errors

```bash
# 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](ARCHITECTURE.md) for internals
- Check [TODO.md](TODO.md) for implementation status
- Browse source code in `dynamodb/`, `rocksdb/`, etc.

## Getting Help

There is absolutely no support at this time

## Benchmarking

```bash
# 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

```bash
# Remove build artifacts
make clean

# Remove installed binary (if installed)
make uninstall

# Remove data directory
rm -rf ./data
```