umadb 0.5.0

Event store built for Dynamic Consistency Boundaries
Documentation

UmaDB - Dynamic Consistency Boundary Event Store

UmaDB is a specialist open-source event store built for dynamic consistency boundaries.

This crate provides the umadb binary, a gRPC server for running UmaDB as a standalone service.

Installation

Via Cargo

Install the umadb binary using Cargo:

cargo install umadb

After installation, run the server:

umadb --listen 127.0.0.1:50051 --db-path ./data

Pre-built Binaries

Pre-built binaries for various platforms are available on GitHub:

Download the appropriate binary for your platform and architecture.

Docker Images

UmaDB Docker images are available from multiple registries:

Docker Hub:

docker pull umadb/umadb:latest
docker run -p 50051:50051 -v /path/to/data:/data umadb/umadb:latest

GitHub Container Registry (GHCR):

docker pull ghcr.io/umadb-io/umadb:latest
docker run -p 50051:50051 -v /path/to/data:/data ghcr.io/umadb-io/umadb:latest

CLI Usage

The umadb command-line interface provides options to configure the server:

umadb [OPTIONS]

Options

  • --db-path - Path to the database file or directory
  • --listen - Server bind address (e.g. 127.0.0.1:50051)
  • --tls-cert - Optional file path to TLS server certificate (also via UMADB_TLS_CERT)
  • --tls-key - Optional file path to TLS server private key (also via UMADB_TLS_KEY)
  • --api-key - Optional API key for authenticating clients (also via UMADB_API_KEY)
  • -h, --help - Print help
  • -V, --version - Print version

Examples

Run CLI listening to 0.0.0.0:50051 using ./data to store events.

umadb --listen 0.0.0.0:50051 --db-path ./data

Run Docker image, publishing port 50051 and persisting data to a local volume:

docker run -p 50051:50051 -v $(pwd)/umadb-data:/data umadb/umadb:latest

Quick Start

Once the server is running, you can connect using client libraries:

Python Client

pip install umadb

from umadb import Client, Event

# Connect to UmaDB server
client = Client("http://localhost:50051")

# Create and append events
event = Event(
    event_type="UserCreated",
    data=b"user data",
    tags=["user:123"],
)
position = client.append([event])
print(f"Event appended at position: {position}")

# Read events
events = client.read()
for seq in events:
    print(f"Position {seq.position}: {seq.event.event_type}")

Rust Client

Add the client dependency to your Cargo.toml:

[dependencies]
umadb-client = "0.1"

Use the client in your code:

use umadb_client::UmaDcClient;
use umadb_dcb::{DcbEvent, DcbEventStoreAsync};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = UmaDbClient::new("http://localhost:50051".to_string())
        .connect_async()
        .await?;

    let events = vec![DcbEvent {
        event_type: "UserCreated".to_string(),
        data: b"user data".to_vec(),
        tags: vec!["user:123".to_string()],
        uuid: None,
    }];

    let position = client.append(events, None).await?;
    println!("Event appended at position: {}", position);

    Ok(())
}

Features

  • High-performance concurrency with non-blocking reads and writes
  • Optimistic concurrency control to prevent simultaneous write conflicts
  • Dynamic business-rule enforcement via query-driven append conditions
  • Real-time subscriptions with seamless catch-up and continuous delivery
  • gRPC API for cross-language compatibility

Documentation

For more information about UmaDB and Dynamic Consistency Boundaries:

License

This project is licensed under either of:

at your option.