AcornDB 0.5.0

🌰 AcornDB

A distributed, embeddable, reactive object database for .NET. Local-first persistence with mesh sync, LRU cache eviction, TTL enforcement, pluggable storage backends, and zero configuration.

🐿️ Built for developers who'd rather ship products than manage infrastructure.

dotnet add package AcornDB
dotnet add package AcornDB.Persistence.Cloud    # Optional: S3, Azure Blob
dotnet add package AcornDB.Persistence.RDBMS    # Optional: SQLite, SQL Server, PostgreSQL, MySQL

🚀 Why AcornDB?

Most apps don't need Cosmos DB, Kafka, or a $400/month cloud bill to store 5MB of JSON.

You need:

• ✅ Fast, local-first persistence
• ✅ Simple per-tenant or per-user storage
• ✅ Offline support + sync that actually works
• ✅ Zero configuration, zero ceremony

Perfect for:

• Desktop & mobile apps
• IoT & edge devices
• CLI tools & utilities
• Serverless & edge workloads
• Single-user SaaS apps

🌲 Core Concepts

Read More: Core Concepts →

⚡ Quick Start

30-Second Example

using AcornDB;

public class User
{
    public string Id { get; set; } = Guid.NewGuid().ToString();
    public string Name { get; set; }
}

// Create a tree (defaults to file storage, zero config!)
var tree = new Tree<User>();

// Or use the fluent builder pattern via Acorn
tree = new Acorn<User>().WithCompression().Sprout();

// Stash (auto-detects ID from property)
tree.Stash(new User { Name = "Alice" });

// Crack (retrieve)
var alice = tree.Crack("alice-id");

// Query with LINQ
var adults = tree.Nuts.Where(u => u.Age >= 18).ToList();

Use Git for Storage

Every Stash() creates a Git commit. Use Git tools to inspect your database:

using AcornDB;
using AcornDB.Storage;

var tree = new Acorn<User>()
    .WithGitTrunk(repoPath: "./my_db", autoPush: true)
    .Sprout();

tree.Stash(new User { Id = "alice", Name = "Alice" });
// ✅ Git commit created: "Stash: alice at 2025-10-07 10:30:45"

// Time-travel through history
var history = tree.GetHistory("alice"); // All previous versions

cd my_db
git log --oneline
# f4e8a91 Stash: alice at 2025-10-07 10:30:45
# c2d1b3a Stash: bob at 2025-10-07 10:25:12

Read More: GitHub Trunk Guide →

Dynamic Storage with Nursery

Discover and grow storage backends at runtime:

// Browse available storage types
Console.WriteLine(Nursery.GetCatalog());

// Grow trunk from config (no hardcoded dependencies!)
var tree = new Acorn<User>()
    .WithTrunk("git", new()
    {
        { "repoPath", "./my_repo" },
        { "authorName", "Alice" }
    })
    .Sprout();

// Change storage backend via environment variable
var storageType = Environment.GetEnvironmentVariable("STORAGE") ?? "file";
var tree = new Acorn<User>().WithTrunk(storageType).Sprout();

Read More: Nursery Guide →

Real-Time Sync

// In-process sync (no HTTP server needed!)
var tree1 = new Acorn<User>().Sprout();
var tree2 = new Acorn<User>().InMemory().Sprout();

tree1.Entangle(tree2); // Direct tree-to-tree sync

tree1.Stash(new User { Name = "Bob" });
// ✅ Automatically synced to tree2!

// HTTP sync with TreeBark server
var branch = new Branch("http://localhost:5000");
grove.Oversee<User>(branch); // Auto-syncs on every change

Read More: Data Sync Guide →

🎯 Features

✅ Implemented (v0.4)

🔜 Roadmap (Upcoming)

View Full Roadmap →

🗄️ Storage Backends (Trunks)

AcornDB uses Trunks to abstract storage. Swap backends without changing your code.

Built-in Trunks

Read More: Storage Guide → Cloud Storage Guide → Nursery Guide →

Using Fluent API

using AcornDB;

// File storage (default)
var tree = new Acorn<User>().Sprout();

// Git storage
var gitTree = new Acorn<User>()
    .WithGitTrunk("./my_repo", authorName: "Alice")
    .Sprout();

// With encryption + compression
var secureTree = new Acorn<User>()
    .WithEncryption("my-password")
    .WithCompression()
    .Sprout();

// LRU cache with limit
var cachedTree = new Acorn<User>()
    .WithLRUCache(maxSize: 1000)
    .Sprout();

// Via Nursery (dynamic)
var dynamicTree = new Acorn<User>()
    .WithTrunk("git", new() { { "repoPath", "./data" } })
    .Sprout();

Cloud & RDBMS Extensions

using AcornDB.Persistence.Cloud;
using AcornDB.Persistence.RDBMS;

// S3 storage
var s3Tree = new Acorn<User>()
    .WithS3Trunk(accessKey, secretKey, bucketName, region: "us-east-1")
    .Sprout();

// Azure Blob
var azureTree = new Acorn<User>()
    .WithAzureBlobTrunk(connectionString, containerName)
    .Sprout();

// SQLite
var sqliteTree = new Acorn<User>()
    .WithSqliteTrunk("Data Source=mydb.db")
    .Sprout();

// PostgreSQL
var pgTree = new Acorn<User>()
    .WithPostgreSQLTrunk("Host=localhost;Database=acorn")
    .Sprout();

📚 Documentation

• Getting Started Guide - Your first AcornDB app
• Core Concepts - Understanding Trees, Nuts, and Trunks
• Storage Guide - Available trunk types and usage
• Data Sync Guide - In-process, HTTP, and mesh sync
• Conflict Resolution - Handling sync conflicts
• Events & Reactivity - Real-time change notifications
• GitHub Trunk Demo - Git-as-database guide
• Nursery Guide - Dynamic trunk discovery
• Cloud Storage Guide - S3, Azure Blob setup
• Dashboard & Visualizer - Web UI for grove management
• Cluster & Mesh - Distributed sync patterns

🧪 Examples

// Example 1: Local-first desktop app
var tree = new Acorn<Document>()
    .WithStoragePath("./user_data")
    .WithLRUCache(5000)
    .Sprout();

tree.Subscribe(doc => Console.WriteLine($"Changed: {doc.Title}"));

// Example 2: IoT edge device with cloud backup
var edgeTree = new Acorn<SensorReading>()
    .WithStoragePath("./local_cache")
    .Sprout();

var cloudBranch = new Branch("https://api.example.com/sync");
grove.Oversee<SensorReading>(cloudBranch); // Auto-syncs to cloud

// Example 3: Multi-tenant SaaS with per-tenant storage
string GetTenantPath(string tenantId) => $"./data/{tenantId}";

var tenantTree = new Acorn<Order>()
    .WithStoragePath(GetTenantPath(currentTenantId))
    .Sprout();

// Example 4: Git-based audit log
var auditLog = new Acorn<AuditEntry>()
    .WithGitTrunk("./audit_log", authorName: "System")
    .Sprout();

auditLog.Stash(new AuditEntry { Action = "Login", User = "alice" });
// Git commit created with full history!

More Examples: Demo Project → Live Sync Demo →

🎨 Canopy - Web UI

Explore your Grove with an interactive dashboard:

cd Canopy
dotnet run
# Open http://localhost:5100

Features:

• 📊 Real-time statistics
• 🌳 Tree explorer with metadata
• 📈 Interactive graph visualization
• 🔍 Nut inspector with history
• ⚙️ Trunk capabilities viewer

Read More: Dashboard Guide →

🧱 Project Structure

🌰 The Acorn Philosophy

🐿️ Serious software. Zero seriousness.

We built AcornDB because we were tired of:

• Paying $$$ to store JSON
• Managing Kubernetes for simple persistence
• Writing DataClientServiceManagerFactoryFactory
• YAML-induced existential dread

We believe:

• Developers deserve tools that make them smile
• Syncing JSON shouldn't require a PhD
• Local-first is the future
• API names should be memorable (Stash, Crack, Shake > Insert, Select, Synchronize)

If you've ever rage-quit YAML or cried syncing offline-first apps — welcome home. 🌳

🤝 Contributing

We welcome contributions! Check out:

• Roadmap for planned features
• Issues for bugs and enhancements
• Wiki for documentation

🐿️ Stay Nutty

Built with acorns and sarcasm by developers who've had enough.

⭐ Star the repo if AcornDB saved you from another cloud bill 🍴 Fork it if you want to get squirrelly 💬 Share your weirdest squirrel pun in the discussions

🧾 License

AcornDB is source-available software provided by Anadak LLC.

• Free for personal, educational, and non-commercial use under the
  PolyForm Noncommercial License 1.0.0
• Commercial use requires a separate license from Anadak LLC. The cost of which will be inversely proportionate to the degree of good you're doing. Contact licensing@anadak.ai for details.

© 2025 Anadak LLC. All rights reserved.