first commit
This commit is contained in:
457
QUICKSTART.md
Normal file
457
QUICKSTART.md
Normal file
@@ -0,0 +1,457 @@
|
||||
# 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:8000, ./data directory)
|
||||
make run
|
||||
```
|
||||
|
||||
You should see:
|
||||
```
|
||||
╔═══════════════════════════════════════════════╗
|
||||
║ ║
|
||||
║ ╦╔═╗╦═╗╔╦╗╦ ╦╔╗╔╔╦╗╔╗ ║
|
||||
║ ║║ ║╠╦╝║║║║ ║║║║ ║║╠╩╗ ║
|
||||
║ ╚╝╚═╝╩╚═╩ ╩╚═╝╝╚╝═╩╝╚═╝ ║
|
||||
║ ║
|
||||
║ DynamoDB-Compatible Database ║
|
||||
║ Powered by RocksDB + Odin ║
|
||||
║ ║
|
||||
╚═══════════════════════════════════════════════╝
|
||||
|
||||
Port: 8000 | Data Dir: ./data
|
||||
|
||||
Storage engine initialized at ./data
|
||||
Starting DynamoDB-compatible server on 0.0.0.0:8000
|
||||
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 (for local use)
|
||||
|
||||
```bash
|
||||
# Set dummy credentials (required but not checked by JormunDB)
|
||||
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:8000 \
|
||||
--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:8000
|
||||
```
|
||||
|
||||
**Put an Item:**
|
||||
```bash
|
||||
aws dynamodb put-item \
|
||||
--endpoint-url http://localhost:8000 \
|
||||
--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:8000 \
|
||||
--table-name Users \
|
||||
--key '{"id": {"S": "user123"}}'
|
||||
```
|
||||
|
||||
**Query Items:**
|
||||
```bash
|
||||
aws dynamodb query \
|
||||
--endpoint-url http://localhost:8000 \
|
||||
--table-name Users \
|
||||
--key-condition-expression "id = :id" \
|
||||
--expression-attribute-values '{
|
||||
":id": {"S": "user123"}
|
||||
}'
|
||||
```
|
||||
|
||||
**Scan Table:**
|
||||
```bash
|
||||
aws dynamodb scan \
|
||||
--endpoint-url http://localhost:8000 \
|
||||
--table-name Users
|
||||
```
|
||||
|
||||
**Delete an Item:**
|
||||
```bash
|
||||
aws dynamodb delete-item \
|
||||
--endpoint-url http://localhost:8000 \
|
||||
--table-name Users \
|
||||
--key '{"id": {"S": "user123"}}'
|
||||
```
|
||||
|
||||
**Delete a Table:**
|
||||
```bash
|
||||
aws dynamodb delete-table \
|
||||
--endpoint-url http://localhost:8000 \
|
||||
--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:8000",
|
||||
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:8000',
|
||||
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 8000
|
||||
lsof -i :8000
|
||||
|
||||
# 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.
|
||||
- Contribute! See [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Issues**: https://github.com/yourusername/jormundb/issues
|
||||
- **Discussions**: https://github.com/yourusername/jormundb/discussions
|
||||
- **Odin Discord**: https://discord.gg/sVBPHEv
|
||||
|
||||
## 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:8000/
|
||||
```
|
||||
|
||||
## Production Deployment
|
||||
|
||||
JormunDB is designed for **local development only**. For production, use:
|
||||
|
||||
- AWS DynamoDB (managed service)
|
||||
- DynamoDB Accelerator (DAX)
|
||||
- ScyllaDB (DynamoDB-compatible)
|
||||
|
||||
## Uninstalling
|
||||
|
||||
```bash
|
||||
# Remove build artifacts
|
||||
make clean
|
||||
|
||||
# Remove installed binary (if installed)
|
||||
make uninstall
|
||||
|
||||
# Remove data directory
|
||||
rm -rf ./data
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Happy coding! 🚀**
|
||||
|
||||
For questions or issues, please open a GitHub issue or join our Discord.
|
||||
Reference in New Issue
Block a user