Overview

What KronosDB is, the parts it is made of, its ports and what it keeps.

KronosDB is an event store and a messaging server in one binary. The event store keeps an append-only log of events for event sourcing, with tag-based queries and conditional appends that implement dynamic consistency boundaries (DCB). The messaging server delivers commands and queries to handlers registered by the processes of an application. Clients reach both on the same TCP port, the client port described under Ports below.

An event in KronosDB has a type, a payload and a set of tags, such as a tool id or a customer id. A client reads the events matching a query, decides, and appends new events with a condition. The events the client read are the consistency boundary of its decision, and the append fails if an event matching the same query was stored after the position the client read. There are no streams or aggregates to declare in advance, because each decision selects its own boundary with a query, as described in Events and tags.

The parts

PartWhat it isPage
Event storeThe log of events in a context: events, tags, positions, reading by query, streaming from a position, and conditional appends with their durability.Events and tags
ContextsSeparate event stores on one server, each with its own log and positions, declared in a manifest or created through the admin API.Contexts
MessagingNamed buses with a command bus, a query bus and subscription queries, independent of contexts.Messaging
Clustering and replicationCopies of the log on several nodes, a leader that takes all appends, and the consistency a cluster gives.Clustering and replication
Admin console and APIA web console and a JSON API on a second port, for contexts, clients, processors and cluster membership.Admin console

Snapshots and scheduled events are part of the event store. A snapshot is a state blob a client stores under a key so that it can start a read from the snapshot's position, and a schedule makes the server append an event at a future time.

Clients

An application reaches KronosDB through a client library. The kronos command line tool is a client too. Run without arguments it opens a terminal UI, and its subcommands such as kronos events tail -f and kronos contexts ls print JSON with -o json.

ClientLanguageUse
@kronos-ts/kronosdbTypeScriptThe event store and buses of Kronos.
kronosdb-clientRustA client library in the server repository, used by the kronos CLI.
axon-kronosdb-connectorJavaConnects Axon Framework 5.3 and later applications, version 0.6 or later for KronosDB 0.11 or later.

Client authors find the protocol schema at github.com/KronosDB/kronosdb/tree/main/protocol.

Ports

The server listens on two ports.

PortDefaultServes
Client127.0.0.1:50051Clients and, in a cluster, the other nodes. TLS when a certificate and key are configured.
Admin127.0.0.1:9240The admin console, the JSON API, /health, /ready and /metrics.

Starting and configuring a server is covered in Getting started and Configuration.

What it keeps

The event log only grows. The server has no retention setting and no call that deletes events or a context.

Messages on the buses are transient. A command or query for which no handler is registered is not stored for later, because the events a handler appends are the durable record. Payloads of events, commands and queries are bytes the server does not interpret, so the schema and serialization format belong to the clients.

A single node is a cluster of one, and it acknowledges an append when its own log is durable. Adding nodes changes where the data is copied to and how many nodes must have an append before it is acknowledged, and the client is configured the same way.

Measurements of the server and the conditions they were taken under are in docs/BENCHMARKS.md in the repository.

On this page