Logo
Logo

Preconditions

Commits are atomic and can be guarded by preconditions that are checked under the writer lock.

All events of one commit are published atomically: either every event becomes visible or none does. Preconditions add business rules to that guarantee. They are evaluated under the writer lock, together with the commit, so no other commit can slip in between the check and the write.

json
{
  "events": [
    { "source": "io.genesisdb.app", "subject": "/customer/42", "type": "io.genesisdb.app.customer-added", "data": { "email": "bruce@wayne.enterprises" } }
  ],
  "preconditions": [
    { "type": "isSubjectNew", "payload": { "subject": "/customer/42" } },
    { "type": "isQueryResultTrue", "payload": { "query": "STREAM e FROM events WHERE e.data.email == 'bruce@wayne.enterprises' MAP COUNT() == 0" } }
  ]
}
TypePayloadHolds when
isSubjectNew{"subject": "/customer/42"}neither the subject nor a descendant has events
isSubjectExisting{"subject": "/customer/42"}the subject or a descendant has events
isQueryResultTrue{"query": "<GDBQL>"}the query result is true

A query result counts as true when it is the boolean true, a number other than 0, the text true or 1, or a non-empty list of rows. See Query Language.

When a precondition fails

The commit is rejected with 412 Precondition Failed and nothing is written:

json
{ "type": "isSubjectNew", "message": "subject /customer/42 already has events" }

The SDKs turn this into a typed error that carries type and message.

Failed commits

If a commit fails after its events reached the event log, for example because of a storage error, the events are durable and become visible after a restart. The store then rejects writes until it is restarted. Do not retry a failed commit blindly, check whether it was applied first.