# 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:

```bash
./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](https://datatracker.ietf.org/doc/html/rfc3339)** 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:

```bash
[...] --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**:

```bash
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](/docs/eventsourcingdb/backup-and-restore)**.