Clojure API

This document provides detailed information about the ChronDB API.

Core API (Clojure/Java)

Creating a Database

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

;; Create with default configuration
(def db (chrondb/create-chrondb))

;; Create with custom configuration
(def db (chrondb/create-chrondb config))

Document Operations

Save Document

(chrondb/save db "key" value)

Parameters:

• db: ChronDB instance

• key: String identifier for the document

• value: Document data (will be stored as JSON)

Returns: The saved document

Get Document

(chrondb/get db "key")

Parameters:

• db: ChronDB instance

• key: String identifier for the document

Returns: The document if found, nil otherwise

Delete Document

(chrondb/delete db "key")

Parameters:

• db: ChronDB instance

• key: String identifier for the document

Returns: true if document was deleted, false otherwise

Search Operations

Search Documents

(chrondb/search db query)
(chrondb/search db query {:limit 10 :offset 0})

Parameters:

• db: ChronDB instance

• query: Lucene query string

• options: Optional map with:

  • :limit: Maximum number of results (default: 10)

  • :offset: Number of results to skip (default: 0)

Returns: Sequence of matching documents

Version Control Operations

Get Document History

(chrondb/history db "key")

Parameters:

• db: ChronDB instance

• key: String identifier for the document

Returns: Sequence of document versions with timestamps

Get Document at Point in Time

(chrondb/get-at db "key" timestamp)

Parameters:

• db: ChronDB instance

• key: String identifier for the document

• timestamp: ISO-8601 timestamp string or java.time.Instant

Returns: The document as it existed at the specified time

Compare Document Versions

(chrondb/diff db "key" timestamp1 timestamp2)

Parameters:

• db: ChronDB instance

• key: String identifier for the document

• timestamp1: First timestamp

• timestamp2: Second timestamp

Returns: Differences between versions

Branch Operations

Create Branch

(chrondb/create-branch db "branch-name")

Parameters:

• db: ChronDB instance

• branch-name: Name of the new branch

Returns: Updated ChronDB instance

Switch Branch

(chrondb/switch-branch db "branch-name")

Parameters:

• db: ChronDB instance

• branch-name: Name of the branch to switch to

Returns: Updated ChronDB instance

Merge Branches

(chrondb/merge-branch db "source-branch" "target-branch")

Parameters:

• db: ChronDB instance

• source-branch: Branch to merge from

• target-branch: Branch to merge into

Returns: Updated ChronDB instance

Transaction Operations

(chrondb/with-transaction [db]
  (chrondb/save db "key1" value1)
  (chrondb/save db "key2" value2))

All operations within the transaction block are atomic:

• Either all succeed or all fail

• Changes are only visible after successful commit

• Automatic rollback on failure

Transaction Metadata and Git Notes

ChronDB attaches a structured Git note to every commit. The payload includes the transaction id (tx_id), origin, optional user identifier, flags, and request metadata. You can enrich this payload by providing HTTP headers on REST requests:

Header	Description
X-ChronDB-Origin	Overrides the origin label stored in the note (defaults to rest).
X-ChronDB-User	Associates commits with an authenticated user id or service account.
X-ChronDB-Flags	Comma-separated list of semantic flags (for example: bulk-load, migration).
X-Request-Id / X-Correlation-Id	Propagate request correlation identifiers into commit metadata.

All ChronDB front-ends (REST, Redis, SQL) reuse the same transaction core, so commits that belong to the same logical operation share the same tx_id. Special operations automatically set semantic flags. For instance, document imports mark the transaction with bulk-load, and restore flows add rollback.

Inspect commit notes with standard Git tooling:

git log --show-notes=chrondb
git notes --ref=chrondb show <commit-hash>

You can parse the JSON payload to correlate commits with external systems or audit trails.

Event Hooks

Register Hook

(chrondb/register-hook db :pre-save
  (fn [doc]
    ;; Hook logic here
    doc))

Available hook points:

• :pre-save: Before saving a document

• :post-save: After saving a document

• :pre-delete: Before deleting a document

• :post-delete: After deleting a document

Utility Functions

Health Check

(chrondb/health-check db)

Returns: Map with health status information

Backup / Restore

(chrondb.backup.core/create-full-backup storage {:output-path "backups/full.tar.gz"})
(chrondb.backup.core/create-incremental-backup storage {:output-path "backups/incr.bundle"
                                                       :base-commit "<commit>"
                                                       :format :bundle})

(chrondb.backup.core/restore-backup storage {:input-path "backups/full.tar.gz"})

(chrondb.backup.core/export-snapshot storage {:output "backups/main.bundle"
                                              :refs ["refs/heads/main"]})

(chrondb.backup.core/import-snapshot storage {:input "backups/main.bundle"})

Scheduled backup example:

(chrondb.backup.core/schedule-backup storage {:mode :bundle
                                              :format :bundle
                                              :interval-minutes 60
                                              :output-dir "backups/"})

Statistics

(chrondb/stats db)

Returns: Map with database statistics

Error Handling

All API functions may throw the following exceptions:

• ChronDBException: Base exception class

• StorageException: Storage-related errors

• IndexException: Index-related errors

• ConfigurationException: Configuration errors

• ValidationException: Data validation errors

Example error handling:

(try
  (chrondb/save db "key" value)
  (catch chrondb.exceptions.StorageException e
    (log/error "Storage error:" (.getMessage e)))
  (catch chrondb.exceptions.ValidationException e
    (log/error "Validation error:" (.getMessage e))))