Getting Started with KotaDB¶

This guide will help you get KotaDB up and running quickly. We'll cover installation, basic configuration, and your first database operations.

Prerequisites¶

Before you begin, ensure you have the following installed:

• Rust 1.75.0 or later (Install Rust)
• Git for cloning the repository
• Just command runner (optional but recommended)

Quick Installation¶

From Source¶

# Clone the repository
git clone https://github.com/jayminwest/kota-db.git
cd kota-db

# Build the project
cargo build --release

# Run tests to verify installation
cargo test --lib

Using Just¶

If you have just installed:

# Build and test
just build
just test

# Start development server
just dev

Docker Installation¶

# Pull the Docker image
docker pull kotadb/kotadb:latest

# Run KotaDB container
docker run -p 8080:8080 -v $(pwd)/data:/data kotadb/kotadb:latest

First Steps¶

1. Create a Configuration File¶

Create a kotadb.toml configuration file:

[storage]
path = "./data"
cache_size = 1000
wal_enabled = true

[server]
host = "127.0.0.1"
port = 8080
max_connections = 100

[indices]
primary_enabled = true
trigram_enabled = true
vector_enabled = false

2. Start the Server¶

# Using cargo
cargo run -- --config kotadb.toml

# Or with the built binary
./target/release/kotadb --config kotadb.toml

3. Verify Installation¶

Check that the server is running:

# Check server status
curl http://localhost:8080/health

# View database statistics
cargo run stats

Basic Operations¶

Insert a Document¶

use kotadb::{DocumentBuilder, create_file_storage};

#[tokio::main]
async fn main() -> Result<()> {
    // Create storage instance
    let storage = create_file_storage("./data", Some(1000)).await?;

    // Build a document
    let doc = DocumentBuilder::new()
        .path("/docs/example.md")?
        .title("My First Document")?
        .content(b"# Hello KotaDB\nThis is my first document.")?
        .build()?;

    // Insert the document
    storage.insert(doc).await?;

    Ok(())
}

Search Documents¶

// Full-text search
let results = storage.search("Hello KotaDB").await?;

// Wildcard search
let all_docs = storage.search("*").await?;

// Path-based search
let docs_in_folder = storage.search("/docs/*").await?;

Next Steps¶

Now that you have KotaDB running, explore:

• Configuration Options - Detailed configuration guide
• Basic Operations - CRUD operations and queries
• API Reference - Complete API documentation
• Architecture Overview - Understanding KotaDB internals

Getting Help¶

If you encounter issues:

1. Check the Troubleshooting Guide
2. Search GitHub Issues
3. Ask in GitHub Discussions
4. Review the FAQ

Example Projects¶

Explore complete examples in the examples directory:

• Basic CRUD - Simple document operations
• Search Examples - Various search patterns
• MCP Integration - LLM integration examples
• Performance Testing - Benchmark scripts