diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index 9b6230e..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -1,437 +0,0 @@ -# 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 -``` - -### 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 - -- 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 -```