Quickstart

Before You Begin#

You need Docker to run EventSourcingDB, and curl to send requests to EventSourcingDB and to SynthEvents.

Downloading a Data Set#

The product page of SynthEvents offers ready-made data sets for every domain, over the year 2025, in three sizes: about 500, about 5,000, and about 20,000 events. Each of them comes as plain CloudEvents and as a backup for EventSourcingDB.

The standard data sets are generated with the fixed seed standard, so they are the same for everyone. This comes in handy when a whole workshop works with the same events. For another range or size, the product page tells you how to ask for a tailor-made data set.

Download the standard data set of the library with about 5,000 events as a backup for EventSourcingDB, either from the product page or with curl, which saves it as library.ndjson in the current directory:

curl \
  -o library.ndjson \
  https://www.eventfoundation.io/products/synthevents/data-sets/library-everyday-medium.eventsourcingdb.ndjson

Starting EventSourcingDB#

Start EventSourcingDB with the following command. On the first start, Docker downloads the image:

docker run -it -p 3000:3000 \
  thenativeweb/eventsourcingdb:preview run \
  --api-token=secret \
  --data-directory-temporary \
  --http-enabled \
  --https-enabled=false \
  --with-ui

This starts EventSourcingDB on port 3000, with the API token secret, a temporary data directory that is cleaned up on shutdown, unencrypted HTTP, and the management UI.

Restoring the Data Set#

In a second terminal, send the data set to the /api/v1/restore endpoint of EventSourcingDB:

curl \
  -i \
  -X POST \
  -H "authorization: Bearer secret" \
  --data-binary "@library.ndjson" \
  http://localhost:3000/api/v1/restore

If everything worked as expected, EventSourcingDB responds with HTTP status code 200 OK:

HTTP/1.1 200 OK

A restore only works on an empty database. Since the data directory is temporary, the database is empty after every start. For details, see Backup and Restore.

Exploring the Data Set#

The database now holds a year of a library. To see which events it holds, count them by their type with an EventQL query:

curl \
  -i \
  -X POST \
  -H "authorization: Bearer secret" \
  -H "content-type: application/json" \
  -d "{
    \"query\": \"FROM e IN events GROUP BY e.type PROJECT INTO { type: UNIQUE(e.type), count: COUNT() }\"
  }" \
  http://localhost:3000/api/v1/run-eventql-query

The response contains one row for every event type, from io.synthevents.library.book-imported, the stock the library had when the year began, to io.synthevents.library.book-borrowed, io.synthevents.library.book-returned, and the late fees. Every copy of a book is a subject of its own, such as /books/<uuid>. What the events mean, and which rules they follow, is described in Library.

To browse the events and run further queries, point your browser to http://localhost:3000. For details, see Using the Management UI.

Generating a Data Set With the API#

The ready-made data sets cover the year 2025 and three sizes. To choose every parameter yourself, call the API of SynthEvents at https://api.synthevents.io. Generating a data set takes a token, which you get when you ask for a tailor-made data set. If you have none yet, skip to Shutting Down.

Send a POST request to the /api/v1/generate-events endpoint, with your token in place of <TOKEN>:

curl \
  -X POST \
  -H "authorization: Bearer <TOKEN>" \
  -H "content-type: application/json" \
  -d '{
    "domain": "library",
    "scenario": "everyday",
    "range": {
      "from": "2025-01-01T00:00:00Z",
      "to": "2026-01-01T00:00:00Z"
    },
    "eventCount": 5000,
    "seed": "my-first-data-set",
    "format": "eventsourcingdb"
  }' \
  -o my-library.ndjson \
  https://api.synthevents.io/api/v1/generate-events

This asks for the domain library in its scenario everyday, over the year 2025, with about 5,000 events. The number is approximate, because SynthEvents simulates the library over the time range rather than counting events out. The seed makes the data set reproducible: the same request to the same version of SynthEvents gives the same data set again, byte for byte. The format eventsourcingdb makes it a backup for EventSourcingDB; with cloudevents, you get plain CloudEvents instead.

A restore needs an empty database, so press Ctrl+C in the first terminal to shut EventSourcingDB down, and start it again with the same command. Then restore the new data set:

curl \
  -i \
  -X POST \
  -H "authorization: Bearer secret" \
  --data-binary "@my-library.ndjson" \
  http://localhost:3000/api/v1/restore

If a request to SynthEvents is refused, the response names the problem, and its code links to a page that explains it. For an overview, see Errors.

Shutting Down#

Press Ctrl+C in the first terminal to shut down EventSourcingDB. Since the data directory is temporary, the events are gone afterwards. The data set is still in its file, so you can restore it again at any time.

Next Steps#

• Generating Data Sets explains how the range, the number of events, and the seed shape a data set, and how its source tells you how to generate it again.
• Formats describes plain CloudEvents and the backup for EventSourcingDB.
• Courses, Library, and To-Dos describe the domains, with their events and rules.
• API covers every route of SynthEvents, with its requests, responses, and limits.
• Using the Data explains what you may do with the data.