avelino/chrondb

ChronDB: The Time-Traveling Database

Chronological key/value Database built on Git architecture with complete version history.

✨ Features

ChronDB offers unique capabilities for your data:

• Complete History - Every change is preserved, nothing is ever truly deleted
• Time Travel - Query your data as it existed at any point in time
• Multiple Interfaces:
  • 🧩 Native Clojure API - Direct integration for JVM applications
  • 📡 REST API - HTTP interface for any language
  • 🔄 Redis Protocol - Connect using Redis clients
  • 🗄️ PostgreSQL Protocol - Connect with SQL clients
• Language Bindings - Embed ChronDB directly in your application:
  • 🐍 Python - ctypes-based client with context manager support
  • 🦀 Rust - Safe wrapper with serde_json integration
• ACID Transactions - Guaranteed consistency and durability
• Schemaless Design - Store any JSON-compatible data
• Git Foundation - Leverage Git's powerful features:
  • Branching and merging for isolated environments
  • Diffs between versions
  • Complete audit trails with commit messages

🔍 Lucene Search Overhaul

ChronDB's indexing layer now runs entirely on Apache Lucene, replacing the previous bespoke search structures. The upgrade brings production-grade analyzers, configurable secondary and composite indexes, geospatial capabilities, and a query planner with smart caching. The work was motivated by real-world workloads that demanded lower latency and richer search semantics powered by a proven search engine. Dive into the updated documentation to learn how to enable and tune the new indexes for your applications.

🚀 Quick Start

Using Docker (Simplest)

# Start ChronDB with all protocols enabled
docker run -d --name chrondb \
  -p 3000:3000 \  # REST API
  -p 6379:6379 \  # Redis protocol
  -p 5432:5432 \  # PostgreSQL protocol
  -v chrondb-data:/data \
  avelino/chrondb:latest

Using Clojure

In your deps.edn:

{:deps {com.github.avelino/chrondb {:git/tag "v0.2.1"
                                     :git/sha "..."}}}

Then in your code:

(require '[chrondb.core :as chrondb])

;; Create a database connection
(def db (chrondb/create-chrondb))

;; Create a document
(chrondb/save db "user:1" {:name "Alice" :email "[email protected]"})

;; Update the document
(chrondb/save db "user:1" {:name "Alice" :email "[email protected]" :role "admin"})

;; Time travel: see how the document looked at a specific point in time
(def yesterday (chrondb/get-at db "user:1" "2023-07-15T00:00:00Z"))

;; See all versions of the document
(def history (chrondb/history db "user:1"))

Running the Server

# Clone the repository
git clone https://github.com/avelino/chrondb.git
cd chrondb

# Run with default settings (REST on 3000, Redis on 6379, PostgreSQL on 5432)
clojure -M:run

# Or with custom ports
clojure -M:run 8080 6380 5433

🧠 Concept

ChronDB maps database concepts to Git's structure:

• Database → Git repository
• Schema → Git branch
• Table → Directory in repository
• Document → JSON file in directory
• History → Commit timeline

This approach gives you all the power of Git for your database operations.

📚 Documentation

Complete documentation is available at chrondb.avelino.run

• Quick Start Guide - Up and running in minutes
• Core Concepts - Understand ChronDB's data model
• Time Travel Tutorial - Learn to use versioning
• Branching Guide - Master isolated environments
• Python Binding - Embed ChronDB in Python apps
• Rust Binding - Embed ChronDB in Rust apps

🛠️ Requirements

• Java 11 or later
• Git 2.25.0 or later

💬 Community

• GitHub Discussions - Share ideas and use cases
• GitHub Issues - Report bugs and request features
• Reddit

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

📄 License

ChronDB is licensed under the terms of the GNU Affero General Public License v3.0 (AGPLv3).

This means:

• You are free to use, study, modify, and redistribute the software.
• If you run a modified version as a network service, you must make the source available to users of that service.
• See the LICENSE file for full details or visit gnu.org/licenses/agpl-3.0.