Remembering
EventSourcingDB
Building
ArchitectureKit
Version
1.2 · latest1.11.0
Docs / EventSourcingDB 1.0 / Quickstart / Quickstart

Quickstart

This quickstart gets EventSourcingDB running on your machine in a few minutes: you start it with Docker, write a first event, and read it back. It uses a temporary setup for development and testing – for all other options, see the links at the end.

Starting EventSourcingDB#

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

docker run -it -p 3000:3000 \
  thenativeweb/eventsourcingdb 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.

For Development and Testing Only

These settings simplify the setup but are not secure for production. For production-ready configurations, see Running EventSourcingDB and the CLI Overview.

To verify that EventSourcingDB is running, send a ping:

curl http://localhost:3000/api/v1/ping

If the response contains the message Oh my God, it's full of stars., EventSourcingDB is ready.

Writing an Event#

Events are written with a POST request to the /api/v1/write-events endpoint, authenticated with the API token. The following event records that the library acquired a book:

curl \
  -i \
  -X POST \
  -H "authorization: Bearer secret" \
  -H "content-type: application/json" \
  -d "{
    \"events\": [
      {
        \"source\": \"https://library.eventsourcingdb.io\",
        \"subject\": \"/books/42\",
        \"type\": \"io.eventsourcingdb.library.book-acquired\",
        \"data\": {
          \"title\": \"2001 – A Space Odyssey\",
          \"author\": \"Arthur C. Clarke\",
          \"isbn\": \"978-0756906788\"
        }
      }
    ]
  }" \
  http://localhost:3000/api/v1/write-events

Reading the Event#

To read the events of the subject /books/42, send a POST request to the /api/v1/read-events endpoint:

curl \
  -i \
  -X POST \
  -H "authorization: Bearer secret" \
  -H "content-type: application/json" \
  -d "{
    \"subject\": \"/books/42\",
    \"options\": {
      \"recursive\": false
    }
  }" \
  http://localhost:3000/api/v1/read-events

The response contains the event you have just written.

Opening the Management UI#

To see the state of the database and run queries, point your browser to http://localhost:3000. For details, see Using the Management UI.

Shutting Down#

Press Ctrl+C to shut down EventSourcingDB. Since the data directory is temporary, the event is gone afterwards.

Next Steps#