Overview

EventDB is an advanced event-sourced system designed to provide immutable, append-only storage for events across various domains. EventDB is ideal for scenarios requiring detailed audit trails, complex business processes, and high levels of data integrity.

Features

• String-Only Storage: EventDB adopts a string-only storage format. This means all data, regardless of its original type (e.g., integers, dates), is stored as strings. This approach simplifies data handling and ensures uniformity across the database, which is especially beneficial for data integrity and auditability.

• Immutable Data Structure: Once data is written to EventDB, it cannot be altered or deleted. This immutability is crucial for applications where historical data accuracy and traceability are paramount, such as in medical records, financial transactions, and supply chain management.

• Event Sourcing and Replay: EventDB is built on the principle of event sourcing, where all changes to the data are stored as a sequence of events. This allows for the complete replay of events to reconstruct the state of the database at any point in time, enhancing data recovery and audit capabilities.

• Merkle Tree Integration: Each aggregate in EventDB is associated with a Merkle tree, enabling efficient and secure verification of data integrity. The Merkle tree structure ensures that any tampering with the data can be detected, providing an added layer of security against data corruption.

• Built-in Audit Trails: Thanks to its immutable nature and event sourcing model, EventDB automatically maintains a comprehensive audit trail of all transactions. This feature is invaluable for compliance and regulatory requirements, offering transparent and tamper-evident records.

• Compatibility with Major Database Systems: EventDB is designed to work seamlessly with well-known database systems such as SQL Server, MongoDB, MySQL, PostgreSQL, DynamoDB, and Redis. This compatibility allows for easy integration into existing infrastructures, leveraging EventDB's unique features alongside conventional database functionalities.

• Powered by RocksDB and Rust: At its core, EventDB uses RocksDB for storage, benefiting from its high performance and efficiency characteristics. The system is developed in Rust, known for its safety, efficiency, and concurrency features, ensuring that EventDB is both fast and reliable.

• Security with Token-Based Authorization: EventDB employs token-based authorization to manage access to the database. This security measure allows for precise control over who can access and modify the data, safeguarding against unauthorized changes.

Getting Started

Prerequisites

• Ensure you have Rust installed for development.

Installation

Clone the EventDB repository:

git clone https://github.com/thachp/eventdb.git

Navigate to the project directory and compile the project:

cargo build --release

Running EventDB

Start the EventDB server using the following command:

cargo run --release

Usage

System Commands

• init: Initializes the EventDB system, preparing it for first-time use by setting up essential configurations.
• start: Launches the EventDB server, making it ready to accept and process requests.
• stop: Gracefully shuts down the EventDB server, ensuring that all processes are correctly terminated.
• version: Displays the current version of the EventDB system, helping users identify the installed version.
• backup: Creates a backup of the EventDB data, ensuring data safety and facilitating disaster recovery strategies.
• restore: Restores the EventDB from a backup, useful for recovery after data loss or corruption.
• upgrade: Upgrades EventDB to a newer version, applying updates and migrations necessary for the new version.
• destroy: Removes all data, configurations, and resources associated with the EventDB server, effectively resetting the system to a state akin to a brand-new installation.

Managing Tokens

A token represents a set of credentials and permissions encoded as a compact, URL-safe string. When a user or service authenticates successfully, EventDB issues a token that includes claims about the identity of the token holder and their authorized actions. This token is then used in subsequent requests to access protected resources or execute operations, eliminating the need for repeated authentication.

• token:generate: Creates a new access token for authentication and authorization within the EventDB system.
• token:revoke: Invalidates an existing token, removing its access privileges to secure the system.
• token:list: Lists all active tokens, providing an overview of current access permissions.
• token:update: Updates the permissions or details associated with an existing token.
• token:refresh: Refreshes an access token, extending its validity without altering its permissions.

Schema Operations

A schema in EventDB is a formal definition that outlines the structure, constraints, and rules for data within the system, such as events and aggregates. It serves as a blueprint for ensuring data integrity and consistency by specifying the allowed format and content for stored information

• schema:create: Defines a new schema for events or aggregates, setting the data structure and rules for how data should be organized and validated within the system.
• schema:update: Updates an existing schema to accommodate changes in the application's data requirements or business logic, ensuring the system remains aligned with current needs.
• schema:list: Lists all schemas defined within the system, providing a comprehensive view of the data models and structures in use.
• schema:get: Retrieves detailed information about a specific schema, including its components, version, and any constraints or rules it enforces.
• schema:validate: Validates a schema against the system's schema standards, ensuring it is correctly formed and consistent with system capabilities.
• schema:export: Exports a schema definition, allowing it to be shared, reviewed, or stored outside the system for documentation or integration purposes.
• schema:push: Uploads a local schema definition to the EventDB server or a centralized schema repository, facilitating version control and collaboration among multiple developers or teams.
• schema:pull: Downloads the latest schema definition from the EventDB server or a centralized schema repository to a local environment, ensuring developers are working with the most current data models.
• schema:migrate: Applies changes from one version of a schema to another, managing the transition and data transformation necessary to move from an old schema version to an updated one without losing data integrity.
• schema:deploy: Deploys schema changes across environments (development, staging, production), ensuring that the schema is consistently applied and the system behaves predictably in each context.

Working with Aggregates

An aggregate in EventDB is a collection of related events that are treated as a single unit for the purpose of data manipulation and state management. Aggregates serve as the cornerstone of EventDB's event sourcing model, encapsulating a set of changes or actions that together represent the state of a domain entity.

• aggregate:create: Initiates a new aggregate, starting a collection of related events under a unified entity.
• aggregate:apply: Applies an event to an aggregate, altering its state according to the event's data.
• aggregate:list: Lists all aggregates, offering a snapshot of the system's current state entities.
• aggregate:get: Fetches detailed information about a specific aggregate, including its state and event history.
• aggregate:replay: Reapplies past events to an aggregate, useful for rebuilding state or debugging.
• aggregate:snapshot: Creates a point-in-time snapshot of an aggregate's state, optimizing future state reconstructions.
• aggregate:archive: Moves an aggregate to archival storage, preserving its history while optimizing active storage.
• aggregate:export: Exports the current state and event history of a specified aggregate to a file or external system.

Working with Events

Events in EventDB are intrinsically linked to aggregates, with each event representing an individual state change or action that affects a specific aggregate. Aggregates are composed of these related events and are treated as a cohesive unit, encapsulating the sequence of changes that collectively define the state of a domain entity.

• event:add: Records a new event, capturing a state change within the system.
• event:list: Displays a list of events, allowing for audit and analysis of state changes.
• event:get: Retrieves detailed data about a specific event, including its type, payload, and timestamp.
• event:archive: Transfers events to long-term storage, maintaining system performance while preserving history.
• event:export: Exports event data, facilitating external analyses or backups.

Managing Integrations

Integrations in EventDB enable seamless connections between EventDB and external systems, services, or applications, enhancing its core functionalities and enabling a more comprehensive data ecosystem. Through integrations, EventDB can export data for analysis, trigger workflows in other systems, synchronize with external databases, and much more.

• integration:configure: Sets up a connection between EventDB and an external service, enabling data exchange or functionality extension.
• integration:list: Lists all configured integrations, providing an overview of external connections.
• integration:sync: Manually triggers a data synchronization with an external service, ensuring data consistency.
• integration:test: Verifies the setup of an integration, ensuring that EventDB can communicate effectively with the external service.
• integration:enable: Activates a configured integration, enabling its operations within EventDB.
• integration:disable: Temporarily turns off an integration, halting its data exchange or functional impact on EventDB.

Contributing

Thank you for your interest in EventDB. At this time, I am focusing on addressing known bugs and stabilizing core features, which means the project is currently closed to public contributions.

Quick Start

• Report Issues: Found a bug or have a suggestion? Open an issue with detailed information.
• Contribute Code:
  • Fork & Clone: Fork the EventDB 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

• 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

EventDB is licensed under the MIT License.