EventDBX

You'll likely enjoy this database system. Worry less about how you structure your data and focus more on your business logic.

Overview

EventDBX is an event-sourced, key-value, write-side database system designed to provide immutable, append-only storage for events across various domains. It is ideal for applications requiring detailed audit trails for compliance, complex business processes involving states, and high data integrity levels.

Getting Started

Follow the steps below to spin up EventDBX locally. All commands are expected to run from the repository root unless stated otherwise.

1. Install prerequisites

   • Rust toolchain (edition 2024) via rustup
   • rocksdb is vendored through the Rust crate, so no extra native packages are required.

2. Clone and build

   git clone https://github.com/thachp/eventdbx.git
   cd eventdbx
   cargo build
   

3. (Optional) Run checks

   cargo fmt -- --check
   cargo check
   cargo test    # if you add tests locally
   

4. Create the initial configuration The first configuration must include both a master key and a data-encryption key. These values can be any non-empty strings in development.

   cargo run -- config --master-key dev-master --dek dev-dek
   

5. Start the server

   cargo run -- start --foreground
   

   • Omit --foreground to daemonise the process.
   • Use --data-dir <path> to override the default ./.eventdbx directory.
   • Restriction (schema enforcement) is enabled by default; disable it with --restrict=false if you need a permissive environment.

6. Define a schema (recommended when running in restricted mode)

   cargo run -- schema create \
     --aggregate patient \
     --events patient-added,patient-updated \
     --snapshot-threshold 100
   

7. Issue a token for CLI access

   cargo run -- token generate \
     --group admin \
     --user jane \
     --expiration 3600
   

8. Append an event

   cargo run -- aggregate apply \
     --aggregate patient \
     --aggregate-id p-001 \
     --event patient-added \
     --field name="Jane Doe" \
     --field status=active
   

You now have a working EventDBX instance with an initial aggregate. Explore the Command-Line Reference for the full set of supported operations.

Features

• Flexible JSON payloads: Events accept arbitrary JSON payloads; scalar values are normalized into strings for state tracking, while structured objects remain fully queryable.
• Immutable Data Structure: Once data is entered into EventDBX, it becomes immutable, meaning it cannot be altered or deleted. This characteristic is crucial for applications where the accuracy and traceability of historical data are paramount, such as medical records, financial transactions, and supply chain management. Data can be archived, moving from short-term to long-term storage, but cannot be deleted.
• Event Sourcing and Replay: EventDBX is built on the principle of event sourcing, storing all changes to the data as a sequence of events. This allows for the complete replay of events to reconstruct the database's state at any point in time, thereby enhancing data recovery and audit capabilities. Unlike traditional databases that execute update statements to modify data, this system is event-driven. Aggregate state changes are defined in the event object, allowing these events to be replayed at any time to reconstruct the aggregate's current state.
• Merkle Tree Integration: Each aggregate in EventDBX is associated with a Merkle tree of events, enabling verification of data integrity. The Merkle tree structure ensures that any data tampering can be detected, offering an additional security layer against data corruption.
• Built-in Audit Trails: EventDBX automatically maintains a comprehensive audit trail of all transactions, a feature invaluable for meeting compliance and regulatory requirements. It provides transparent and tamper-evident records. During audits, administrators can issue specific tokens to auditors to access and review specific aggregate instances and all relevant events associated with those instances.
• Security with Token-Based Authorization: EventDBX implements token-based authorization to manage database access. This approach allows for precise control over who can access and modify data, protecting against unauthorized changes. Unlike systems where a single application user account performs CRUD operations, EventDBX mandates that each user of the application obtains their own access token with a specific time horizon. For example, a doctor will receive their own access token, linked to their identifier (IAM-managed outside EventDBX), generated by the system for each event they handle, rather than having a single application user manage all CRUD operations. This ensures the system can accurately track that it was the doctor who made changes to an aggregate state, not the application.
• Powered by RocksDB and Rust: At its core, EventualDB utilizes RocksDB for storage, taking advantage of its high performance and efficiency. The system is developed in Rust, known for its safety, efficiency, and concurrency capabilities, ensuring that EventualDB is both rapid and dependable.

Command-Line Reference

EventDBX ships a single eventdbx binary. Every command accepts an optional --config <path> to point at an alternate configuration file.

Server lifecycle

• eventdbx start [--port <u16>] [--data-dir <path>] [--foreground] [--restrict | --restrict=false]
  Launches the server. Schema validation is enforced by default; pass --restrict=false to run in permissive mode.
• eventdbx stop
  Stops the running daemon referenced by the PID file.
• eventdbx status
  Prints the current port, PID, uptime, and whether restriction is enabled.
• eventdbx restart [start options…]
  Stops the existing daemon (if any) and restarts it with the provided options.
• eventdbx destroy [--yes]
  Removes the PID file, data directory, and configuration file after confirmation (or immediately with --yes).

Configuration

• eventdbx config [--port <u16>] [--data-dir <path>] [--master-key <secret>] [--dek <secret>] [--memory-threshold <usize>] [--list-page-size <usize>] [--page-limit <usize>]
  Persists configuration updates. The first invocation must include both --master-key and --dek. --list-page-size sets the default page size for aggregate listings (default 10) and --page-limit caps any requested page size across list and event endpoints (default 1000, alias --event-page-limit).

Tokens

• eventdbx token generate --group <name> --user <name> [--expiration <secs>] [--limit <writes>] [--keep-alive]
  Issues a new token tied to a Unix-style group and user.
• eventdbx token list
  Lists all tokens with status, expiry, and remaining writes.
• eventdbx token revoke --token <value>
  Revokes a token immediately.
• eventdbx token refresh --token <value> [--expiration <secs>] [--limit <writes>]
  Extends the lifetime or write allowance of an existing token.

Schemas

• eventdbx schema create --aggregate <name> --events <event1,event2,...> [--snapshot-threshold <u64>]
• eventdbx schema add --aggregate <name> --events <event1,event2,...>
• eventdbx schema remove --aggregate <name> --event <name>
• eventdbx schema list

Schemas are stored on disk; when the server runs with restriction enabled, incoming events must satisfy the recorded schema.

Aggregates

• eventdbx aggregate apply --aggregate <type> --aggregate-id <id> --event <name> --field KEY=VALUE... [--stage]
  Appends an event immediately—use --stage to queue it for a later commit.
• eventdbx aggregate list [--skip <n>] [--take <n>] [--stage]
  Lists aggregates with version, Merkle root, and archive status; pass --stage to display queued events instead.
• eventdbx aggregate get --aggregate <type> --aggregate-id <id> [--version <u64>] [--include-events]
• eventdbx aggregate replay --aggregate <type> --aggregate-id <id> [--skip <n>] [--take <n>]
• eventdbx aggregate verify --aggregate <type> --aggregate-id <id>
• eventdbx aggregate snapshot --aggregate <type> --aggregate-id <id> [--comment <text>]
• eventdbx aggregate archive --aggregate <type> --aggregate-id <id> [--comment <text>]
• eventdbx aggregate restore --aggregate <type> --aggregate-id <id> [--comment <text>]
• eventdbx aggregate remove --aggregate <type> --aggregate-id <id> Removes an aggregate that has no events (version still 0).
• eventdbx aggregate commit
  Flushes all staged events in a single atomic transaction.

Staged events are stored in .eventdbx/staged_events.json. Use aggregate apply --stage to add entries to this queue, inspect them with aggregate list --stage, and persist the entire batch with aggregate commit. Events are validated against the active schema (when restriction is enabled) during both staging and commit. The commit operation writes every pending event in one RocksDB batch, guaranteeing all-or-nothing persistence.

Plugins

• eventdbx plugin map --aggregate <name> --field <field> --datatype <type> [--plugin postgres]
  Records the base column type for a field; use --plugin postgres to override only the Postgres mapping.
• eventdbx plugin postgres --connection <connection-string> [--disable]
• eventdbx plugin sqlite --path <file> [--disable]
• eventdbx plugin csv --output-dir <dir> [--disable]
• eventdbx plugin tcp --host <hostname> --port <u16> [--disable]
• eventdbx plugin http --endpoint <url> [--header KEY=VALUE]... [--disable]
• eventdbx plugin json --path <file> [--pretty] [--disable]
• eventdbx plugin log --level <trace|debug|info|warn|error> [--template "text with {aggregate} {event} {id}"] [--disable]

Plugins fire after every committed event to keep external systems in sync. Each plugin sends or records different data:

• Postgres: Applies schema/base types to create/alter columns and upsert the aggregate row. Payload is the aggregate state at the time of the event.
• SQLite: Mirrors state into a local SQLite file with the same column set as Postgres.
• CSV: Appends state snapshots into <aggregate>.csv, expanding columns as new fields appear.
• TCP: Writes a single-line JSON EventRecord to the configured socket.
• HTTP: POSTs the EventRecord JSON to the endpoint with optional headers.
• JSON: Appends the EventRecord JSON (pretty if requested) to the given file.
• Log: Emits a formatted line via tracing at the configured level. By default: aggregate=<type> id=<id> event=<event>.

Example TCP/HTTP/JSON payload (EventRecord):

{
  "aggregate_type": "patient",
  "aggregate_id": "p-001",
  "event_type": "patient-updated",
  "payload": {
    "status": "inactive",
    "comment": "Archived via API"
  },
  "metadata": {
    "event_id": "45c3013e-9b95-4ed0-9af9-1a465f81d3cf",
    "created_at": "2024-12-01T17:22:43.512345Z",
    "issued_by": {
      "group": "admin",
      "user": "jane"
    }
  },
  "version": 5,
  "hash": "cafe…",
  "merkle_root": "deadbeef…"
}

REST API

The server exposes a small HTTP API (served on port 7070 by default). All endpoints require a bearer token unless otherwise noted.

Paginated responses cap take at the configurable page_limit (default 1000). Adjust it with eventdbx config --page-limit <n> if you need larger pages.

All authenticated requests must include Authorization: Bearer <token> with a token issued via the CLI.

cURL examples

# Post a JSON event (global endpoint)
curl \
  -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "aggregate_type": "patient",
        "aggregate_id": "p-001",
        "event_type": "patient-updated",
        "payload": {
          "status": "inactive",
          "meta": {"source": "api"}
        }
      }' \
  http://localhost:7070/v1/events

# Retrieve the first 10 events for an aggregate (supports `skip`/`take` up to `page_limit`)
curl \
  -H "Authorization: Bearer TOKEN" \
  "http://localhost:7070/v1/aggregates/patient/p-001/events?skip=0&take=10"

# Health check
curl http://localhost:7070/health

# List aggregates (replace TOKEN with an active value)
curl \
  -H "Authorization: Bearer TOKEN" \
  http://localhost:7070/v1/aggregates

# Append an event (global endpoint)
curl \
  -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "aggregate_type": "patient",
        "aggregate_id": "p-001",
        "event_type": "patient-updated",
        "payload": {
          "status": "inactive",
          "comment": "Archived via API"
        }
      }' \
  http://localhost:7070/v1/events

Contributing

Quick Start

1. Report Issues: Found a bug or have a suggestion? Open an issue with detailed information.
2. Contribute Code:
   • Fork & Clone: Fork the EventDBX repo and clone your fork.
   • Branch: Create a branch for your changes from develop.
   • Develop: Make your changes, adhering to our coding standards. Add or update tests as necessary.
   • Commit: Use Conventional Commits for clear, structured commit messages (e.g., feat: add new feature or fix: correct a bug).
   • Pull Request: Submit a pull request (PR) against the develop branch of the original repo. Describe your changes and link to any related issues.

Guidelines

• Formatting: A project-wide Prettier configuration lives at .prettierrc.json; use it for Markdown/JSON/YAML changes.
• Commit linting: Conventional Commit headers are enforced through .commitlintrc.json.
• Code Review: Your PR will be reviewed by the team. Be open to feedback and make requested adjustments.
• Merge: Once approved, your PR will be merged into the project, and you'll be credited as a contributor.

License

EventDBX is licensed under the MIT License.