Cerberus

An EventStore administration tool.

EventStore is an open-source functional database.

Talk and exchange ideas in our dedicated Discord Server

Goal

Cerberus aims at providing an easy access to EventStore database in the comfort of our beloved terminal.

Feature list

Those features are not listed into an implementation order.

• Show a database node/cluster version.
• Database healthiness check-up (cluster mode included).
• Comprehensive events listing.
• Comprehensive stream listing.
• Comprehensive projection listing.
• Comprehensive persistent subscription lising.
• Create persistent subscription.
• Update persistent subscription.
• Delete persistent subscription.
• Create projection.
• Provide a packaged version to Linux (APT for inst., .deb,…etc), OSX (Homebrew) and whatever is used on Windows.
• Display cluster information.
• Expose node statistics.
• Comprehensive data migration.
• Comprehensive data export (as JSON file(s) or other human-readable format).
• Create a backup archive.
• Apply or check database compliance (If a database contains all the persistent subscriptions, projections, or other requirement needed)
• Featureful TUI interface.
• Install EventStore locally.

Install

Currently, we don't provide compiled binaries. However, we aim at providing means to install cerberus through OS package managers:

• APT for debian-based Linux distributions (a .deb file will be available too).
• Homebrew formula for OSX.
• Whatever Windows package manager.

From source

Cerberus is written in Rust. To install Rust dev tools, go to: https://rustup.rs/

From Crates.io

$ cargo install cerberus-es

The program will be available in ~/.cargo/bin

From source repository

Clone https://github.com/YoEight/cerberus.git git repository. Once you are in cerberus directory run:

$ cargo build --release

The binary will be in target/release/ directory.

Common usages

The following usage example don't showcase all parameters variation nor all commands. You need to run cerberus --help to get all supported commands or, cerberus [COMMAND] --help to get all parameters supported by a command.

Some commands might require a database user with the right permission. In such cases, you only need to provide --login and --password parameters.

Check database connection

$ cerberus check

Cerberus will automatically check if a node belongs to cluster. If the node does belong to a cluster, Cerberus will also check if node composing the cluster are reachable.

Cerberus will also return each node version.

List events

$ cerberus list-events --stream foo

This command lists every events of the foo streams.

$ cerberus list-events --stream foo --recent

This will command will do the same but will only take the last 50 foo 's events.

$ cerberus list-events --stream foo --group-id my_group

This command lists all parked events that belong to the persistent subscription targetting the stream foo and the group my_group.

$ cerberus list-events --stream foo --group-id my_group --checkpoint

This command is similiar to the previous one but will list all the persistent subscription checkpoints.

$ cerberus list-events --by-type user-created

This command lists all the events with the type user-created

List streams

$ cerberus list-streams

This command lists all user-defined streams plus deletion and and metadata streams.

$ cerberus list-streams --by-category user

This command lists all streams that start with user-.

Create a projection

# You will have to use an user with admin right to use that command.
$ cerberus --login=boogie_man --password=******* create-projection -k onetime --name amazing-proj --enabled /path/to/projection.js

The name parameter is optional. In this case, the projection named amazing-proj will start right away because of the flag --enabled.

Backup

Cerberus supports database backup. That feature requires rsync to be in $PATH. Currently, when in a cluster configuration, Cerberus doesn't backup all the nodes nor it selects the master node. We might implement those features mentioned above based on users demand.

Usage:

cerberus --host=1.2.3.4 backup --remote-user=yoeight --source-directory=/var/eventstore/db --destination-directory=/home/yoeight/es-backup

Compliance checking

Compliance checking makes sure a database setup is properly configured based on a compliance file. A compliance file uses the TOML format. In a compliance file, you can make sure that:

• Persistent subscriptions are created and also have all their configuration up-to-date.
• User-defined projections are created and also have all their configuration up-to-date.
• General database configuration (version, cluster configuration,…etc) WIP.

Example of compliance file:

[[projection]]
name = "foo-bar-indexing"
path = "path/to/my/amazing/code.js" # Absolute or relative filepath.
type = "continuous"                 # [possibilities: "continuous", "one-time"]

# Optional settings
emit = true # Optional [default: false]. Enable the ability for the
            # projection to write to streams.

enabled = true # Optional [default: false]. Indicates if the projection
               # will start right away when created.

checkpoints = true # Optional [default: false]
                   # [when projection's type is "continuous", forced at true]
                   # Enable persisting projection progress.

track_emitted_streams = true # Optional [default: false]
                             # Write the name of the streams the projection is
                             # managing to a separate stream:
                             # $projections-{projection-name}-emittedstreams

[[subscription]] # Think persistent subscription.
stream = "the_world" # The stream doesn't need to exist when creating the subscription.
group = "illuminatis"
start_from = 0 # Event number.

# Optional settings
resolve_link           = false         # Optional [default: false]
extra_stats            = false         # Optional [default: false]
msg_timeout_in_ms      = 10_000        # Optional [default: 10_000]
max_retry_count        = 10            # Optional [default: 10]
live_buffer_size       = 500           # Optional [default: 500]
buffer_size            = 500           # Optional [default: 500]
read_batch_size        = 20            # Optional [default: 20]
checkpoint_after_in_ms = 1_000         # Optional [default: 1_000]
min_checkpoint_count   = 10            # Optional [default: 10]
max_checkpoint_count   = 500           # Optional [default: 500]
max_subscriber_count   = 10            # Optional [default: 10]
strategy               = "round-robin" # Optional [default: "round-robin"] [possibilities: "round-robin", "dispatch-to-single", "pinned"]

Usage:

# You will have to use an user with admin right to use that command.
cerberus --login=boogie_man --password=******* apply-compliance --file=compliance.toml

Note: if you only want to see if your database configuration is up-to-date without updating the database itself, use the --dry-run flag. You'll got a complete report without any change pushed to the database.

Notes

That binary was tested on Linux and OSX. Contributions and bug reports are welcome!

MIT License.