Operations Guide
This guide covers operational aspects of ChronDB, including installation, execution, monitoring, and maintenance.
Installation
Requirements
Java 11+
Git 2.25.0+
1GB+ RAM (recommended)
Disk space proportional to data volume and history
Installation via JAR
Download the latest JAR file from the releases page:
curl -LO https://github.com/avelino/chrondb/releases/latest/download/chrondb.jarRun the JAR:
java -jar chrondb.jar
Manual Compilation
Clone the repository:
git clone https://github.com/avelino/chrondb.git cd chrondbCompile the project:
clojure -T:build uberRun the generated JAR:
java -jar target/chrondb.jar
Running ChronDB
Command Line Options
As a Systemd Service
Create a service file
/etc/systemd/system/chrondb.service:Reload systemd:
Start the service:
Monitoring
ChronDB exposes metrics and health information for monitoring.
Health Check Endpoint
Response:
Logs
Logs contain detailed information about operations and errors. By default, they are sent to stdout or a file as configured.
Prometheus Integration
ChronDB exposes metrics in Prometheus format at:
Backup and Restoration
ChronDB usa Git internamente, então cada gravação gera commits imutáveis. A partir desta versão há suporte oficial a backup/restore completos e incrementais, tanto via CLI quanto via REST.
Backup (CLI)
Full tar.gz (default):
Full bundle:
Incremental bundle (desde commit base):
Restore (CLI)
Tar.gz:
Bundle:
Export/Import bundle (CLI)
Scheduler (CLI)
Backup via REST
POST
/api/v1/backup— body JSON{"output":"/path/to/full.tar.gz","format":"tar.gz"}POST
/api/v1/export— JSON{"output":"/path/to/main.bundle","refs":["refs/heads/main"]}
Restore via REST
POST
/api/v1/restorecom upload multipart (campofile) e campo opcionalformatPOST
/api/v1/importcom upload multipart (file) e flagverify
As respostas retornam status HTTP e o manifesto com checksum, refs inclusas e tipo (:full, :incremental).
Dica: Incrementais suportam apenas formato bundle; para reconstruir completamente, aplique primeiro o full e depois os incrementais na ordem.
Maintenance
Compaction
To optimize performance and space usage:
This operation:
Runs git gc to optimize the repository
Rebuilds indices to improve search performance
Optimizes the internal structure
Background Reindexing
ChronDB mantém o Ãndice Lucene sincronizado através de uma tarefa de reindexação em segundo plano. Sempre que chrondb server é iniciado, um processo assÃncrono percorre commits existentes para garantir que documentos antigos também estejam presentes nos novos Ãndices Lucene. A tarefa roda sem bloquear gravações ou leituras e respeita a ordem cronológica: novas confirmações continuam chegando enquanto a reindexação prossegue.
Inicialização resiliente: após restaurações, importações ou grandes refatorações de esquema, o reindexador faz o catch-up automático para que a busca reflita imediatamente o estado do repositório Git.
Janela de manutenção recorrente: além do bootstrap inicial, uma rotina programada executa a verificação/reindexação a cada hora (valor padrão). Esse intervalo é seguro para ambientes de produção porque processa batches incrementais e atualiza métricas de uso para o planejador de consultas.
Observabilidade: logs no namespace
chrondb.index.luceneindicam quando a reindexação começa e termina, bem como eventuais erros de documento. Métricas expostas emchrondb.index.*ajudam a acompanhar progresso e filas pendentes.Uso recomendado: após rodar
chrondb restore,import-snapshotou grandes cargas batch, aguarde a conclusão da tarefa em background ou monitore os logs antes de liberar novas buscas crÃticas.
Updating
Stop the ChronDB service
Backup your data
Replace the JAR file with the new version
Start the service again
Branch Management
Unused branches can be removed:
Disk Space Monitoring
ChronDB will grow over time due to the historical storage nature. Monitor disk usage and configure retention policies if necessary.
FFI / Language Bindings
Export and backup operations are available in all language bindings (Python, Rust, Ruby, Node.js).
Available Methods
Export to directory
export_to_directory()
export_to_directory()
export_to_directory()
exportToDirectory()
Create backup
create_backup()
create_backup()
create_backup()
createBackup()
Restore backup
restore_backup()
restore_backup()
restore_backup()
restoreBackup()
Export snapshot
export_snapshot()
export_snapshot()
export_snapshot()
exportSnapshot()
Import snapshot
import_snapshot()
import_snapshot()
import_snapshot()
importSnapshot()
See the individual binding documentation for detailed usage examples.
Last updated
Was this helpful?