Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yoeight/cerberus
An EventStore administration tool.
https://github.com/yoeight/cerberus
Last synced: 4 days ago
JSON representation
An EventStore administration tool.
- Host: GitHub
- URL: https://github.com/yoeight/cerberus
- Owner: YoEight
- License: mit
- Created: 2019-07-30T19:37:29.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-03-24T23:37:34.000Z (over 1 year ago)
- Last Synced: 2024-10-04T13:34:36.341Z (about 1 month ago)
- Language: Rust
- Size: 286 KB
- Stars: 18
- Watchers: 6
- Forks: 3
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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.
- [x] Show a database node/cluster version.
- [x] Database healthiness check-up (cluster mode included).
- [x] Comprehensive events listing.
- [x] Comprehensive stream listing.
- [x] Comprehensive projection listing.
- [x] Comprehensive persistent subscription lising.
- [x] Create persistent subscription.
- [x] Update persistent subscription.
- [x] Delete persistent subscription.
- [x] 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.
- [x] Comprehensive data migration.
- [ ] Comprehensive data export (as JSON file(s) or other human-readable format).
- [x] Create a backup archive.
- [x] 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:
```toml
[[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.
[EventStore]: http://eventstore.org
[Talk and exchange ideas in our dedicated Discord Server]: https://discord.gg/x7q37jJ