Skip to content

Generating Events Step by Step

EventSourcingDB provides a built-in feature to generate synthetic but realistic event data for various application domains. This makes it easy to populate a new instance with plausible events for testing, experimentation, or demonstration purposes – without having to rely on real-world data or build complex scenarios by hand.

The generated events follow domain-specific behavioral models. These include typical user interactions and realistic time patterns based on the domain.

Simulating a Library

One such domain is library, which models a public library where readers borrow and return books over time. The following section illustrates how the generator works using the library domain.

Available Domains

Currently, the library domain is the only available option for event generation. Additional domains may be added in future versions of EventSourcingDB.

To generate synthetic events for a public library, start by deciding which time period and configuration you want to simulate. Suppose you're interested in the time frame from February 17, 1981 to September 27, 2018, and you want to model a library that manages up to 30,000 books and 5,000 readers. At the beginning of the simulation, 10,000 books are already available in the system, and 1,000 readers have already registered.

To generate this dataset, use the following command:

./eventsourcingdb generate \
  --domain-name library \
  --start-time "1981-02-17T08:00:00.0+02:00" \
  --end-time "2018-09-27T18:00:00.0+02:00" \
  --domain-option "maxNumberOfBooks=30000" \
  --domain-option "maxNumberOfReaders=5000" \
  --domain-option "initialNumberOfBooks=10000" \
  --domain-option "initialNumberOfReaders=1000" \
  > backup.json

This command uses the library domain to simulate realistic interactions – such as borrowing books during weekdays, extending loan periods, or returning books late. The --start-time and --end-time flags define the simulation window, and must use the RFC 3339 format.

The --domain-option flags allow further customization by providing key-value pairs that define how the simulation behaves. These options are domain-specific and control parameters such as capacity, population, and initial state.

By default, each run of the generator produces different results unless you explicitly set a random seed using the --seed flag. Providing a seed ensures deterministic output – useful when you want reproducible results across teams or test environments:

[...] --seed 31415926535

With this flag, you can generate the same output repeatedly, even across different machines.

Saving and Restoring the Output

The generated events are printed to standard output, so it is recommended to redirect the output to a file using the > operator. The resulting file, such as backup.json, contains a valid backup in the standard EventSourcingDB format.

To import the data into an EventSourcingDB instance, you can use the HTTP restore endpoint:

curl \
  -i \
  -X POST \
  -H "Authorization: Bearer <API_TOKEN>" \
  --data-binary "@backup.json" \
  http://localhost:3000/api/v1/restore

Restore Requires an Empty Database

Restores can only be performed into an empty database. If data is already present, the restore will be rejected. This prevents accidental overwrites or conflicts.

For more details on the restore process, refer to Backup and Restore.