# dynamo-es
> A DynamoDB implementation of the `PersistedEventRepository` trait in cqrs-es.
## Usage
Add to your Cargo.toml file:
```toml
[dependencies]
cqrs-es = "0.5.0"
dynamo-es = "0.5.0"
```
Requires access to a Dynamo DB with existing tables. See:
- [Sample database configuration](db/dynamo_db.yaml)
- [Sample database table layout](db/create_tables.sh)
- Use `docker-compose` and the `./db/create_tables.sh` script to quickly setup [a local database](docker-compose.yml)
### DynamoDb caveats
AWS' DynamoDb is fast, flexible and highly available, but it does
[set some limitations](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ServiceQuotas.html)
that must be considered in the design of your application.
#### Maximum limit of 25 operations in any transaction
Events are inserted in a single transaction, which limits the number of events that can be handled from a single command
using this repository. To operate correctly a command must not produce more than
- 25 events if using [an event store without snapshots](https://docs.rs/cqrs-es/latest/cqrs_es/persist/struct.PersistedEventStore.html#method.new_event_store)
- 24 events if using [snapshots](https://docs.rs/cqrs-es/latest/cqrs_es/persist/struct.PersistedEventStore.html#method.new_snapshot_store)
or [an aggregate store](https://docs.rs/cqrs-es/latest/cqrs_es/persist/struct.PersistedEventStore.html#method.new_aggregate_store)
#### Item size limit of 400 KB
A single event should never reach this size, but a large serialized aggregate might.
If this is the case for your aggregate beware of using [snapshots](https://docs.rs/cqrs-es/latest/cqrs_es/persist/struct.PersistedEventStore.html#method.new_snapshot_store)
or [an aggregate store](https://docs.rs/cqrs-es/latest/cqrs_es/persist/struct.PersistedEventStore.html#method.new_aggregate_store).
#### Maximum request size of 1 MB
This could have the same ramifications as the above for [snapshots](https://docs.rs/cqrs-es/latest/cqrs_es/persist/struct.PersistedEventStore.html#method.new_snapshot_store)
or [an aggregate store](https://docs.rs/cqrs-es/latest/cqrs_es/persist/struct.PersistedEventStore.html#method.new_aggregate_store).
Additionally, an aggregate instance with a large number of events may reach this threshold.
To prevent an error while loading or replaying events,
[set the streaming channel size](https://docs.rs/dynamo-es/latest/dynamo_es/struct.DynamoEventRepository.html#method.with_streaming_channel_size)
to a value that ensures you won't exceed this threshold.
### Testing
Requires access to DynamoDb with existing tables. This can be created locally using the included
`docker-compose.yml` and database initialization script.
To prepare a local test environment (requires a local installation of
[Docker](https://www.docker.com/products/docker-desktop) and
[AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)):
```
docker-compose up -d
./db/create_tables.sh
```
It is recommended that tables are configured to allow only transactions.
See:
https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis-iam.html
---
Things that could be helpful:
- [User guide](https://doc.rust-cqrs.org) along with an introduction to CQRS and event sourcing.
- [Demo application](https://github.com/serverlesstechnology/cqrs/tree/main/demo) using the warp http server.
- [Change log](https://github.com/serverlesstechnology/cqrs/blob/main/change_log.md)
[](https://crates.io/crates/dynamo-es)
[](https://docs.rs/dynamo-es)
