Go SDK

Installation#

To install the SDK, run:

Changed in 2.0

go get github.com/thenativeweb/eventsourcingdb-client-golang/eventsourcingdb

You can also find this SDK on pkg.go.dev.

Capabilities#

This SDK intentionally focuses on application-level use cases. It provides core functionality for writing, reading, and observing events, and deliberately excludes operational concerns such as backup, restore, or health monitoring.

For a detailed explanation of the specific requirements behind each capability, see the Compliance Criteria.

Essentials

✓ Initialize the Client
✓ Ping the Server
✓ Verify API Token

Writing Events

✓ Write Single Events
✓ Write Multiple Events
✓ Use isSubjectPristine
Added in 1.5Requires EventSourcingDB 1.2✓ Use isSubjectPopulated
✓ Use isSubjectOnEventId
Added in 1.1✓ Use isEventQlQueryTrue
✓ Include OpenTelemetry Trace Context

Reading Events

✓ Read Events by Subject
✓ Read Recursively
✓ Read Chronological and Anti-Chronological
✓ Use Boundaries
✓ Use fromLatestEvent

Using EventQL

✓ Execute EventQL Queries

Observing Events

✓ Observe Events By Subject
✓ Observe Recursively
✓ Use Boundaries
✓ Use fromLatestEvent

Metadata and Discovery

✓ Register Event Schemas
✓ List Subjects
✓ List Event Types
Added in 1.2✓ List a Specific Event Type
Added in 1.3✓ Verify Event Hashes
Added in 1.3✓ Verify Event Signatures

Testcontainers Support

✓ Start and Stop EventSourcingDB in Tests
✓ Use Custom Configuration (e.g., API Token, Port, …)

Getting Started#

Import the package and create an instance by providing the URL of your EventSourcingDB instance and the API token to use:

Changed in 2.0

import (
  "net/url"

  "github.com/thenativeweb/eventsourcingdb-client-golang/eventsourcingdb"
)

// ...

baseURL, err := url.Parse("http://localhost:3000")
if err != nil {
  // ...
}

apiToken := "secret"

client, err := eventsourcingdb.NewClient(baseURL, apiToken)
if err != nil {
  // ...
}

Changed in 1.9Then call the Ping function to check whether the instance is reachable. If it is not, the function will return an error:

err := client.Ping()
if err != nil {
  // ...
}

Note that Ping does not require authentication, so the call may succeed even if the API token is invalid.

Changed in 1.9If you want to verify the API token, call VerifyAPIToken. If the token is invalid, the function will return an error:

err := client.VerifyAPIToken()
if err != nil {
  // ...
}

Writing Events#

Changed in 1.9Call the WriteEvents function and hand over a slice with one or more events. You do not have to provide all event fields – some are automatically added by the server.

Specify Source, Subject, Type, and Data according to the CloudEvents format.

For Data, you may provide any struct with public fields. It is recommended to have JSON annotations on this struct to control how the struct gets serialized.

Optionally, set the trace context of OpenTelemetry with TraceParent and TraceState, each a pointer to a string.

The function returns the written events, including the fields added by the server:

Changed in 1.9

type BookAcquired struct {
  Title  string `json:"title"`
  Author string `json:"author"`
  ISBN   string `json:"isbn"`
}

event := eventsourcingdb.EventCandidate{
  Source:  "https://library.eventsourcingdb.io",
  Subject: "/books/42",
  Type:    "io.eventsourcingdb.library.book-acquired",
  Data: BookAcquired{
    Title:  "2001 – A Space Odyssey",
    Author: "Arthur C. Clarke",
    ISBN:   "978-0756906788",
  },
}

writtenEvents, err := client.WriteEvents(
  []eventsourcingdb.EventCandidate{
    event,
  },
  nil,
)

Using the isSubjectPristine precondition#

Changed in 1.9If you only want to write events in case a subject (such as /books/42) does not yet have any events, use the NewIsSubjectPristinePrecondition function to create a precondition and pass it in a slice as the second argument:

writtenEvents, err := client.WriteEvents(
  []eventsourcingdb.EventCandidate{
    // ...
  },
  []eventsourcingdb.Precondition{
    eventsourcingdb.NewIsSubjectPristinePrecondition("/books/42"),
  },
)

Using the isSubjectPopulated preconditionAdded in 1.5Changed in 1.9Requires EventSourcingDB 1.2#

If you only want to write events in case a subject (such as /books/42) already has at least one event, use the NewIsSubjectPopulatedPrecondition function to create a precondition and pass it in a slice as the second argument:

writtenEvents, err := client.WriteEvents(
  []eventsourcingdb.EventCandidate{
    // ...
  },
  []eventsourcingdb.Precondition{
    eventsourcingdb.NewIsSubjectPopulatedPrecondition("/books/42"),
  },
)

Using the isSubjectOnEventId precondition#

Changed in 1.9If you only want to write events in case the last event of a subject (such as /books/42) has a specific ID (e.g., 0), use the NewIsSubjectOnEventIDPrecondition function to create a precondition and pass it in a slice as the second argument:

writtenEvents, err := client.WriteEvents(
  []eventsourcingdb.EventCandidate{
    // ...
  },
  []eventsourcingdb.Precondition{
    eventsourcingdb.NewIsSubjectOnEventIDPrecondition("/books/42", "0"),
  },
)

Note that according to the CloudEvents standard, event IDs must be of type string.

Using the isEventQlQueryTrue preconditionChanged in 1.2Changed in 1.9#

If you want to write events depending on an EventQL query, use the NewIsEventQLQueryTruePrecondition function to create a precondition:

writtenEvents, err := client.WriteEvents(
  []eventsourcingdb.EventCandidate{
    // ...
  },
  []eventsourcingdb.Precondition{
    eventsourcingdb.NewIsEventQLQueryTruePrecondition("FROM e IN events WHERE e.type == 'io.eventsourcingdb.library.book-borrowed' PROJECT INTO COUNT() < 10"),
  },
)

Note that the query must return a single row with a single value, which is interpreted as a boolean.

Reading Events#

To read all events of a subject, call the ReadEvents function with a context, the subject and an options object. Set the Recursive option to false. This ensures that only events of the given subject are returned, not events of nested subjects.

The function returns an iterator, which you can use e.g. inside a for range loop:

for event, err := range client.ReadEvents(
  context.TODO(),
  "/books/42",
  eventsourcingdb.ReadEventsOptions{
    Recursive: false,
  },
) {
  // ...
}

Reading From Subjects Recursively#

If you want to read not only all the events of a subject, but also the events of all nested subjects, set the Recursive option to true:

for event, err := range client.ReadEvents(
  context.TODO(),
  "/books/42",
  eventsourcingdb.ReadEventsOptions{
    Recursive: true,
  },
) {
  // ...
}

This also allows you to read all events ever written. To do so, provide / as the subject and set Recursive to true, since all subjects are nested under the root subject.

Reading in Anti-Chronological Order#

By default, events are read in chronological order. To read in anti-chronological order, provide the Order option and set it using the OrderAntichronological function:

for event, err := range client.ReadEvents(
  context.TODO(),
  "/books/42",
  eventsourcingdb.ReadEventsOptions{
    Recursive: false,
    Order:     eventsourcingdb.OrderAntichronological(),
  },
) {
  // ...
}

Note that you can also use the OrderChronological function to explicitly enforce the default order.

Specifying Bounds#

Sometimes you do not want to read all events, but only a range of events. For that, you can specify the LowerBound and UpperBound options – either one of them or even both at the same time.

Specify the ID and whether to include or exclude it, for both the lower and upper bound:

for event, err := range client.ReadEvents(
  context.TODO(),
  "/books/42",
  eventsourcingdb.ReadEventsOptions{
    Recursive:  false,
    LowerBound: &eventsourcingdb.Bound{
      ID:   "100",
      Type: eventsourcingdb.BoundTypeInclusive,
    },
    UpperBound: &eventsourcingdb.Bound{
      ID:   "200",
      Type: eventsourcingdb.BoundTypeExclusive,
    },
  },
) {
  // ...
}

Starting From the Latest Event of a Given Type#

To read starting from the latest event of a given type, provide the FromLatestEvent option and specify the subject, the type, and how to proceed if no such event exists.

Changed in 1.6Possible options are ReadIfEventIsMissingReadNothing, which skips reading entirely, or ReadIfEventIsMissingReadEverything, which effectively behaves as if FromLatestEvent was not specified:

for event, err := range client.ReadEvents(
  context.TODO(),
  "/books/42",
  eventsourcingdb.ReadEventsOptions{
    Recursive:  false,
    FromLatestEvent: &eventsourcingdb.ReadFromLatestEvent{
      Subject:          "/books/42",
      Type:             "io.eventsourcingdb.library.book-borrowed",
      IfEventIsMissing: eventsourcingdb.ReadIfEventIsMissingReadEverything,
    },
  },
) {
  // ...
}

Note that FromLatestEvent and LowerBound can not be provided at the same time.

Aborting Reading#

If you need to abort reading use break or return within the for range loop. However, this only works if there is currently an iteration going on.

To abort reading independently of that, cancel the context you provided:

ctx, cancel := context.WithCancel(context.TODO())

for event, err := range client.ReadEvents(
  ctx,
  "/books/42",
  eventsourcingdb.ReadEventsOptions{
    Recursive:  false,
  },
) {
  // ...
}

// Somewhere else, cancel the context, which will cause
// reading to end.
cancel()

Added in 1.6Reading then ends with the error of the context, context.Canceled, so that an aborted read can be told apart from a complete one.

Running EventQL Queries#

To run an EventQL query, call the RunEventQLQuery function and provide a context and the query as arguments. The function returns an iterator, which you can use e.g. inside a for range loop:

for row, err := range client.RunEventQLQuery(
  context.TODO(),
  "FROM e IN events PROJECT INTO e",
) {
  // ...
}

Note that each row returned by the iterator is of type json.RawMessage and matches the projection specified in your query.

Aborting a Query#

If you need to abort a query use break or return within the for range loop. However, this only works if there is currently an iteration going on.

To abort the query independently of that, cancel the context you provided:

ctx, cancel := context.WithCancel(context.TODO())

for row, err := range client.RunEventQLQuery(
  ctx,
  "FROM e IN events PROJECT INTO e",
) {
  // ...
}

// Somewhere else, cancel the context, which will cause
// the query to end.
cancel()

Added in 1.6The query then ends with the error of the context, context.Canceled, so that an aborted query can be told apart from a complete one.

Observing Events#

To observe all events of a subject, call the ObserveEvents function with a context, the subject and an options object. Set the Recursive option to false. This ensures that only events of the given subject are returned, not events of nested subjects.

The function returns an iterator, which you can use e.g. inside a for range loop:

for event, err := range client.ObserveEvents(
  context.TODO(),
  "/books/42",
  eventsourcingdb.ObserveEventsOptions{
    Recursive: false,
  },
) {
  // ...
}

Observing From Subjects Recursively#

If you want to observe not only all the events of a subject, but also the events of all nested subjects, set the Recursive option to true:

for event, err := range client.ObserveEvents(
  context.TODO(),
  "/books/42",
  eventsourcingdb.ObserveEventsOptions{
    Recursive: true,
  },
) {
  // ...
}

This also allows you to observe all events ever written. To do so, provide / as the subject and set Recursive to true, since all subjects are nested under the root subject.

Specifying Bounds#

Sometimes you do not want to observe all events, but only a range of events. For that, you can specify the LowerBound option.

Specify the ID and whether to include or exclude it:

for event, err := range client.ObserveEvents(
  context.TODO(),
  "/books/42",
  eventsourcingdb.ObserveEventsOptions{
    Recursive:  false,
    LowerBound: &eventsourcingdb.Bound{
      ID:   "100",
      Type: eventsourcingdb.BoundTypeInclusive,
    },
  },
) {
  // ...
}

Starting From the Latest Event of a Given Type#

To observe starting from the latest event of a given type, provide the FromLatestEvent option and specify the subject, the type, and how to proceed if no such event exists.

Changed in 1.6Possible options are ObserveIfEventIsMissingWaitForEvent, which waits for an event of the given type to happen, or ObserveIfEventIsMissingReadEverything, which effectively behaves as if FromLatestEvent was not specified:

for event, err := range client.ObserveEvents(
  context.TODO(),
  "/books/42",
  eventsourcingdb.ObserveEventsOptions{
    Recursive:  false,
    FromLatestEvent: &eventsourcingdb.ObserveFromLatestEvent{
      Subject:          "/books/42",
      Type:             "io.eventsourcingdb.library.book-borrowed",
      IfEventIsMissing: eventsourcingdb.ObserveIfEventIsMissingReadEverything,
    },
  },
) {
  // ...
}

Note that FromLatestEvent and LowerBound can not be provided at the same time.

Aborting Observing#

If you need to abort observing use break or return within the for range loop. However, this only works if there is currently an iteration going on.

To abort observing independently of that, cancel the context you provided:

ctx, cancel := context.WithCancel(context.TODO())

for event, err := range client.ObserveEvents(
  ctx,
  "/books/42",
  eventsourcingdb.ObserveEventsOptions{
    Recursive:  false,
  },
) {
  // ...
}

// Somewhere else, cancel the context, which will cause
// observing to end.
cancel()

Added in 1.6Changed in 2.0Observing then ends with the error of the context, context.Canceled. Since observing does not end on its own, this is how it usually ends.

Registering an Event Schema#

Changed in 1.9To register an event schema, call the RegisterEventSchema function and hand over an event type and the desired schema:

client.RegisterEventSchema(
  "io.eventsourcingdb.library.book-acquired",
  map[string]any{
    "type": "object",
    "properties": map[string]any{
      "title":  map[string]any{ "type": "string" },
      "author": map[string]any{ "type": "string" },
      "isbn":   map[string]any{ "type": "string" },
    },
    "required": []string{
      "title",
      "author",
      "isbn",
    },
    "additionalProperties": false,
  },
)

Listing Subjects#

Changed in 2.0To list all subjects, call the ReadSubjects function with a context and / as the base subject. The function returns an iterator, which you can use e.g. inside a for range loop:

for subject, err := range client.ReadSubjects(
  context.TODO(),
  "/",
) {
  // ...
}

If you only want to list subjects within a specific branch, provide the desired base subject instead:

for subject, err := range client.ReadSubjects(
  context.TODO(),
  "/books",
) {
  // ...
}

Aborting Listing#

If you need to abort listing use break or return within the for range loop. However, this only works if there is currently an iteration going on.

To abort listing independently of that, cancel the context you provided:

Changed in 2.0

ctx, cancel := context.WithCancel(context.TODO())

for subject, err := range client.ReadSubjects(
  ctx,
  "/",
) {
  // ...
}

// Somewhere else, cancel the context, which will cause
// reading to end.
cancel()

Added in 1.6Reading then ends with the error of the context, context.Canceled, so that an aborted read can be told apart from a complete one.

Listing Event Types#

Changed in 2.0To list all event types, call the ReadEventTypes function. The function returns an iterator, which you can use e.g. inside a for range loop:

for eventType, err := range client.ReadEventTypes(
  context.TODO(),
) {
  // ...
}

Aborting Listing#

If you need to abort listing use break or return within the for range loop. However, this only works if there is currently an iteration going on.

To abort listing independently of that, cancel the context you provided:

ctx, cancel := context.WithCancel(context.TODO())

for eventType, err := range client.ReadEventTypes(
  ctx,
) {
  // ...
}

// Somewhere else, cancel the context, which will cause
// reading to end.
cancel()

Added in 1.6Reading then ends with the error of the context, context.Canceled, so that an aborted read can be told apart from a complete one.

Listing a Specific Event TypeAdded in 1.2Changed in 1.9#

To list a specific event type, call the ReadEventType function with the event type as an argument. The function returns the detailed event type, which includes the schema:

eventType, err := client.ReadEventType(
  "io.eventsourcingdb.library.book-acquired",
)

Verifying an Event's HashAdded in 1.3Changed in 1.10#

To verify the integrity of an event, call the VerifyHash function on the event instance. This recomputes the event's hash locally and compares it to the hash stored in the event. If the hashes differ, the function returns an error:

err := event.VerifyHash()
if err != nil {
  // ...
}

Note that this only verifies the hash. If you also want to verify the signature, you can skip this step and call VerifySignature directly, which performs a hash verification internally.

Verifying an Event's SignatureAdded in 1.3Changed in 1.10#

To verify the authenticity of an event, call the VerifySignature function on the event instance. This requires the public key that matches the private key used for signing on the server.

The function first verifies the event's hash, and then checks the signature. If any verification step fails, it returns an error:

import "crypto/ed25519"

// ...

verificationKey := /* public key as ed25519.PublicKey */

err := event.VerifySignature(verificationKey)
if err != nil {
  // ...
}

Handling ErrorsAdded in 1.7Changed in 1.9#

If the server answers a request with an unexpected HTTP status code, the client returns a *DBAPIError. It contains the StatusCode and the Reason the server gives, so you can tell failures apart without parsing the error message. Use errors.As to get it:

_, err := client.WriteEvents(
  []eventsourcingdb.EventCandidate{
    // ...
  },
  []eventsourcingdb.Precondition{
    eventsourcingdb.NewIsSubjectPristinePrecondition("/books/42"),
  },
)

var dbAPIError *eventsourcingdb.DBAPIError
if errors.As(err, &dbAPIError) {
  switch dbAPIError.StatusCode {
  case http.StatusConflict:
    // dbAPIError.Reason tells why, e.g. "state conflict: precondition failed".
  case http.StatusUnauthorized:
    // ...
  }
}

Note that different failures may share a status code: a failed precondition and an event that does not match its schema are both answered with 409, and only their reasons differ.

If the server is not an EventSourcingDB, e.g. because a proxy answers in its place, the client returns ErrInvalidServerHeader. Use errors.Is to check for it:

err := client.Ping()
if errors.Is(err, eventsourcingdb.ErrInvalidServerHeader) {
  // ...
}

Using Testcontainers#

Added in 1.6The test container lives in the eventsourcingdbtest package, so applications that only use the client do not depend on Testcontainers. Add it to your module, and import it in your tests:

Added in 1.6Changed in 2.0

go get github.com/thenativeweb/eventsourcingdb-client-golang/eventsourcingdbtest

import "github.com/thenativeweb/eventsourcingdb-client-golang/eventsourcingdbtest"

Call the NewContainer function, start the test container, defer stopping it, get a client, and run your test code:

Changed in 1.6

ctx := context.TODO()

container := eventsourcingdbtest.NewContainer()
container.Start(ctx)
defer container.Stop(ctx)

client, err := container.GetClient(ctx)
if err != nil {
  // ...
}

// ...

To check if the test container is running, call the IsRunning function:

isRunning := container.IsRunning()

Added in 1.6Note that up to version 1.5, the test container was part of the eventsourcingdb package. To upgrade, import eventsourcingdbtest and call eventsourcingdbtest.NewContainer instead of eventsourcingdb.NewContainer.

Configuring the Container InstanceChanged in 1.6#

By default, Container uses the latest tag of the official EventSourcingDB Docker image. To change that, call the WithImageTag function:

container := eventsourcingdbtest.NewContainer().
  WithImageTag("1.0.0")

Similarly, you can configure the port to use and the API token. Call the WithPort or the WithAPIToken function respectively:

container := eventsourcingdbtest.NewContainer().
  WithPort(4000).
  WithAPIToken("secret")

If you want to sign events, call the WithSigningKey function. This generates a new signing and verification key pair inside the container:

container := eventsourcingdbtest.NewContainer().
  WithSigningKey()

You can retrieve the private key (for signing) and the public key (for verifying signatures) once the container has been started:

signingKey, err := container.GetSigningKey()
verificationKey, err := container.GetVerificationKey()

The signingKey is the private key EventSourcingDB signs events with. The verificationKey is a pointer to the public key, so pass *verificationKey to VerifySignature when verifying events read from the database.

Configuring the Client Manually#

In case you need to set up the client yourself, use the following functions to get details on the container:

• GetHost(ctx) returns the host name
• GetMappedPort(ctx) returns the port
• GetBaseURL(ctx) returns the full URL of the container
• GetAPIToken() returns the API token

The first three ask Docker, so they take a context and return an error as well.

Further Resources#

• Repository: thenativeweb/eventsourcingdb-client-golang
• Changed in 2.0Registry: pkg.go.dev
• License (MIT): License file
• Issue tracker: GitHub Issues