Logo
Logo
WebsiteBlogChangelog

Quickstart

Run GenesisDB with Docker or as a binary and commit, fetch and query your first events.

Start GenesisDB

The fastest way is the container image. It is published for linux/amd64 and linux/arm64 on Docker Hub and GitHub Packages.

bash
export GENESISDB_AUTH_TOKEN="$(openssl rand -hex 32)"

docker run --rm --name genesisdb \
  -e GENESISDB_AUTH_TOKEN \
  -p 127.0.0.1:8080:8080 \
  -v genesisdb-data:/app/data \
  genesisdb/genesisdb:latest

Prefer a native binary? Install it with Go or download it from the releases page:

bash
go install github.com/genesisdb-io/genesisdb/v2/cmd/genesisdb@latest
genesisdb

The token is required and must have at least 32 bytes. The server binds to 127.0.0.1:8080 and stores its data in ./data.

Check that it runs

bash
curl localhost:8080/ping
# Pong

Commit events

bash
curl localhost:8080/api/v2/commit \
  -H "Authorization: Bearer $GENESISDB_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "source": "io.genesisdb.app", "subject": "/customer/1", "type": "io.genesisdb.app.customer-added", "data": { "name": "Bruce Wayne" } },
      { "source": "io.genesisdb.app", "subject": "/customer/2", "type": "io.genesisdb.app.customer-added", "data": { "name": "Selina Kyle" } }
    ]
  }'

The answer contains the stored events with ID, time, hash and predecessor hash, one per line (NDJSON).

Fetch a subject

bash
curl localhost:8080/api/v2/fetch \
  -H "Authorization: Bearer $GENESISDB_AUTH_TOKEN" \
  -d '{ "subject": "/customer" }'

/customer returns the events of /customer and all of its descendants, in commit order.

Query with GDBQL

bash
curl localhost:8080/api/v2/query \
  -H "Authorization: Bearer $GENESISDB_AUTH_TOKEN" \
  -d "{ \"query\": \"STREAM e FROM events WHERE e.subject UNDER '/customer' MAP { id: e.id, name: e.data.name }\" }"

Next steps

PreviousIntroductionNext About Event Sourcing