{"id":27765721,"url":"https://github.com/thenativeweb/eventsourcingdb-client-golang","last_synced_at":"2026-02-27T17:33:29.350Z","repository":{"id":287519174,"uuid":"539898572","full_name":"thenativeweb/eventsourcingdb-client-golang","owner":"thenativeweb","description":"The official Go client SDK for EventSourcingDB.","archived":false,"fork":false,"pushed_at":"2025-08-11T21:34:59.000Z","size":343,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-11T23:30:32.959Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.eventsourcingdb.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thenativeweb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-22T09:22:04.000Z","updated_at":"2025-08-11T21:35:02.000Z","dependencies_parsed_at":"2025-04-12T08:31:59.213Z","dependency_job_id":"ecf8c3a7-0bbc-40b5-9176-f4b9deb41cba","html_url":"https://github.com/thenativeweb/eventsourcingdb-client-golang","commit_stats":null,"previous_names":["thenativeweb/eventsourcingdb-client-golang"],"tags_count":58,"template":false,"template_full_name":null,"purl":"pkg:github/thenativeweb/eventsourcingdb-client-golang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenativeweb%2Feventsourcingdb-client-golang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenativeweb%2Feventsourcingdb-client-golang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenativeweb%2Feventsourcingdb-client-golang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenativeweb%2Feventsourcingdb-client-golang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thenativeweb","download_url":"https://codeload.github.com/thenativeweb/eventsourcingdb-client-golang/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenativeweb%2Feventsourcingdb-client-golang/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271346188,"owners_count":24743588,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-29T16:58:56.926Z","updated_at":"2026-02-27T17:33:29.321Z","avatar_url":"https://github.com/thenativeweb.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# eventsourcingdb\n\nThe official Go client SDK for [EventSourcingDB](https://www.eventsourcingdb.io) – a purpose-built database for event sourcing.\n\nEventSourcingDB enables you to build and operate event-driven applications with native support for writing, reading, and observing events. This client SDK provides convenient access to its capabilities in Go.\n\nFor more information on EventSourcingDB, see its [official documentation](https://docs.eventsourcingdb.io/).\n\nThis client SDK includes support for [Testcontainers](https://testcontainers.com/) to spin up EventSourcingDB instances in integration tests. For details, see [Using Testcontainers](#using-testcontainers).\n\n## Getting Started\n\nInstall the client SDK:\n\n```shell\ngo get github.com/thenativeweb/eventsourcingdb-client-golang\n```\n\nImport the package and create an instance by providing the URL of your EventSourcingDB instance and the API token to use:\n\n```go\nimport (\n  \"net/url\"\n\n  \"github.com/thenativeweb/eventsourcingdb-client-golang/eventsourcingdb\"\n)\n\n// ...\n\nbaseURL, err := url.Parse(\"http://localhost:3000\")\nif err != nil {\n  // ...\n}\n\napiToken := \"secret\"\n\nclient, err := eventsourcingdb.NewClient(baseURL, apiToken)\nif err != nil {\n  // ...\n}\n```\n\nThen call the `Ping` function to check whether the instance is reachable. If it is not, the function will return an error:\n\n```go\nerr := client.Ping()\nif err != nil {\n  // ...\n}\n```\n\n*Note that `Ping` does not require authentication, so the call may succeed even if the API token is invalid.*\n\nIf you want to verify the API token, call `VerifyAPIToken`. If the token is invalid, the function will return an error:\n\n```go\nerr := client.VerifyAPIToken()\nif err != nil {\n  // ...\n}\n```\n\n### Writing Events\n\nCall 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.\n\nSpecify `Source`, `Subject`, `Type`, and `Data` according to the [CloudEvents](https://docs.eventsourcingdb.io/fundamentals/cloud-events/) format.\n\nFor `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.\n\nThe function returns the written events, including the fields added by the server:\n\n```go\ntype BookAcquired struct {\n  Title  string `json:\"title\"`\n  Author string `json:\"author\"`\n  ISBN   string `json:\"isbn\"`\n}\n\nevent := eventsourcingdb.EventCandidate{\n  Source:  \"https://library.eventsourcingdb.io\",\n  Subject: \"/books/42\",\n  Type:    \"io.eventsourcingdb.library.book-acquired\",\n  Data: BookAcquired{\n    Title:  \"2001 – A Space Odyssey\",\n    Author: \"Arthur C. Clarke\",\n    ISBN:   \"978-0756906788\",\n  },\n}\n\nwrittenEvents, err := client.WriteEvents(\n  []eventsourcingdb.EventCandidate{\n    event,\n  },\n  nil,\n)\n```\n\n#### Using the `isSubjectPristine` precondition\n\nIf 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:\n\n```go\nwrittenEvents, err := client.WriteEvents(\n  []eventsourcingdb.EventCandidate{\n    // ...\n  },\n  []eventsourcingdb.Precondition{\n    eventsourcingdb.NewIsSubjectPristinePrecondition(\"/books/42\"),\n  },\n)\n```\n\n#### Using the `isSubjectPopulated` precondition\n\nIf 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:\n\n```go\nwrittenEvents, err := client.WriteEvents(\n  []eventsourcingdb.EventCandidate{\n    // ...\n  },\n  []eventsourcingdb.Precondition{\n    eventsourcingdb.NewIsSubjectPopulatedPrecondition(\"/books/42\"),\n  },\n)\n```\n\n#### Using the `isSubjectOnEventId` precondition\n\nIf 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:\n\n```go\nwrittenEvents, err := client.WriteEvents(\n  []eventsourcingdb.EventCandidate{\n    // ...\n  },\n  []eventsourcingdb.Precondition{\n    eventsourcingdb.NewIsSubjectOnEventIDPrecondition(\"/books/42\", \"0\"),\n  },\n)\n```\n\n*Note that according to the CloudEvents standard, event IDs must be of type string.*\n\n#### Using the `isEventQlQueryTrue` precondition\n\nIf you want to write events depending on an EventQL query, use the `NewIsEventQLQueryTruePrecondition` function to create a precondition:\n\n```go\nwrittenEvents, err := client.WriteEvents(\n  []eventsourcingdb.EventCandidate{\n    // ...\n  },\n  []eventsourcingdb.Precondition{\n    eventsourcingdb.NewIsEventQLQueryTruePrecondition(\"FROM e IN events WHERE e.type == 'io.eventsourcingdb.library.book-borrowed' PROJECT INTO COUNT() \u003c 10\"),\n  },\n)\n```\n\n*Note that the query must return a single row with a single value, which is interpreted as a boolean.*\n\n### Reading Events\n\nTo 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.\n\nThe function returns an iterator, which you can use e.g. inside a `for range` loop:\n\n```golang\nfor event, err := range client.ReadEvents(\n  context.TODO(),\n  \"/books/42\",\n  eventsourcingdb.ReadEventsOptions{\n    Recursive: false,\n  },\n) {\n  // ...\n}\n```\n\n#### Reading From Subjects Recursively\n\nIf 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`:\n\n```golang\nfor event, err := range client.ReadEvents(\n  context.TODO(),\n  \"/books/42\",\n  eventsourcingdb.ReadEventsOptions{\n    Recursive: true,\n  },\n) {\n  // ...\n}\n```\n\nThis 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.\n\n#### Reading in Anti-Chronological Order\n\nBy default, events are read in chronological order. To read in anti-chronological order, provide the `Order` option and set it using the `OrderAntichronological` function:\n\n```golang\nfor event, err := range client.ReadEvents(\n  context.TODO(),\n  \"/books/42\",\n  eventsourcingdb.ReadEventsOptions{\n    Recursive: false,\n    Order:     eventsourcingdb.OrderAntichronological(),\n  },\n) {\n  // ...\n}\n```\n\n*Note that you can also use the `OrderChronological` function to explicitly enforce the default order.*\n\n#### Specifying Bounds\n\nSometimes 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.\n\nSpecify the ID and whether to include or exclude it, for both the lower and upper bound:\n\n```golang\nfor event, err := range client.ReadEvents(\n  context.TODO(),\n  \"/books/42\",\n  eventsourcingdb.ReadEventsOptions{\n    Recursive:  false,\n    LowerBound: \u0026eventsourcingdb.Bound{\n      ID:   \"100\",\n      Type: eventsourcingdb.BoundTypeInclusive,\n    },\n    UpperBound: \u0026eventsourcingdb.Bound{\n      ID:   \"200\",\n      Type: eventsourcingdb.BoundTypeExclusive,\n    },\n  },\n) {\n  // ...\n}\n```\n\n#### Starting From the Latest Event of a Given Type\n\nTo 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.\n\nPossible options are `ReadNothingIfEventIsMissing`, which skips reading entirely, or `ReadEverythingIfEventIsMissing`, which effectively behaves as if `FromLatestEvent` was not specified:\n\n```golang\nfor event, err := range client.ReadEvents(\n  context.TODO(),\n  \"/books/42\",\n  eventsourcingdb.ReadEventsOptions{\n    Recursive:  false,\n    FromLatestEvent: \u0026eventsourcingdb.ReadFromLatestEvent{\n      Subject:          \"/books/42\",\n      Type:             \"io.eventsourcingdb.library.book-borrowed\",\n      IfEventIsMissing: eventsourcingdb.ReadEverythingIfEventIsMissing,\n    },\n  },\n) {\n  // ...\n}\n```\n\n*Note that `FromLatestEvent` and `LowerBound` can not be provided at the same time.*\n\n#### Aborting Reading\n\nIf 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.\n\nTo abort reading independently of that, cancel the context you provided:\n\n```golang\nctx, cancel := context.WithCancel(context.TODO())\n\nfor event, err := range client.ReadEvents(\n  ctx,\n  \"/books/42\",\n  eventsourcingdb.ReadEventsOptions{\n    Recursive:  false,\n  },\n) {\n  // ...\n}\n\n// Somewhere else, cancel the context, which will cause\n// reading to end.\ncancel()\n```\n\n### Running EventQL Queries\n\nTo 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:\n\n```golang\nfor row, err := range client.RunEventQLQuery(\n  context.TODO(),\n  \"FROM e IN events PROJECT INTO e\",\n) {\n  // ...\n}\n```\n\n*Note that each row returned by the iterator is of type `json.RawMessage` and matches the projection specified in your query.*\n\n#### Aborting a Query\n\nIf 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.\n\nTo abort the query independently of that, cancel the context you provided:\n\n```golang\nctx, cancel := context.WithCancel(context.TODO())\n\nfor row, err := range client.RunEventQLQuery(\n  ctx,\n  \"FROM e IN events PROJECT INTO e\",\n) {\n  // ...\n}\n\n// Somewhere else, cancel the context, which will cause\n// the query to end.\ncancel()\n```\n\n### Observing Events\n\nTo 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.\n\nThe function returns an iterator, which you can use e.g. inside a `for range` loop:\n\n```golang\nfor event, err := range client.ObserveEvents(\n  context.TODO(),\n  \"/books/42\",\n  eventsourcingdb.ObserveEventsOptions{\n    Recursive: false,\n  },\n) {\n  // ...\n}\n```\n\n#### Observing From Subjects Recursively\n\nIf 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`:\n\n```golang\nfor event, err := range client.ObserveEvents(\n  context.TODO(),\n  \"/books/42\",\n  eventsourcingdb.ObserveEventsOptions{\n    Recursive: true,\n  },\n) {\n  // ...\n}\n```\n\nThis 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.\n\n#### Specifying Bounds\n\nSometimes you do not want to observe all events, but only a range of events. For that, you can specify the `LowerBound` option.\n\nSpecify the ID and whether to include or exclude it:\n\n```golang\nfor event, err := range client.ObserveEvents(\n  context.TODO(),\n  \"/books/42\",\n  eventsourcingdb.ObserveEventsOptions{\n    Recursive:  false,\n    LowerBound: \u0026eventsourcingdb.Bound{\n      ID:   \"100\",\n      Type: eventsourcingdb.BoundTypeInclusive,\n    },\n  },\n) {\n  // ...\n}\n```\n\n#### Starting From the Latest Event of a Given Type\n\nTo 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.\n\nPossible options are `WaitForEventIfEventIsMissing`, which waits for an event of the given type to happen, or `ObserveEverythingIfEventIsMissing`, which effectively behaves as if `FromLatestEvent` was not specified:\n\n```golang\nfor event, err := range client.ObserveEvents(\n  context.TODO(),\n  \"/books/42\",\n  eventsourcingdb.ObserveEventsOptions{\n    Recursive:  false,\n    FromLatestEvent: \u0026eventsourcingdb.ObserveFromLatestEvent{\n      Subject:          \"/books/42\",\n      Type:             \"io.eventsourcingdb.library.book-borrowed\",\n      IfEventIsMissing: eventsourcingdb.ObserveEverythingIfEventIsMissing,\n    },\n  },\n) {\n  // ...\n}\n```\n\n*Note that `FromLatestEvent` and `LowerBound` can not be provided at the same time.*\n\n#### Aborting Observing\n\nIf 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.\n\nTo abort observing independently of that, cancel the context you provided:\n\n```golang\nctx, cancel := context.WithCancel(context.TODO())\n\nfor event, err := range client.ObserveEvents(\n  ctx,\n  \"/books/42\",\n  eventsourcingdb.ObserveEventsOptions{\n    Recursive:  false,\n  },\n) {\n  // ...\n}\n\n// Somewhere else, cancel the context, which will cause\n// observing to end.\ncancel()\n```\n\n### Registering an Event Schema\n\nTo register an event schema, call the `RegisterEventSchema` function and hand over an event type and the desired schema:\n\n```golang\nclient.RegisterEventSchema(\n  \"io.eventsourcingdb.library.book-acquired\",\n  map[string]any{\n    \"type\": \"object\",\n    \"properties\": map[string]any{\n      \"title\":  map[string]any{ \"type\": \"string\" },\n      \"author\": map[string]any{ \"type\": \"string\" },\n      \"isbn\":   map[string]any{ \"type\": \"string\" },\n    },\n    \"required\": []string{\n      \"title\",\n      \"author\",\n      \"isbn\",\n    },\n    \"additionalProperties\": false,\n  },\n)\n```\n\n### Listing Subjects\n\nTo 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:\n\n```golang\nfor subject, err := range client.ReadSubjects(\n  context.TODO(),\n  \"/\",\n) {\n  // ...\n}\n```\n\nIf you only want to list subjects within a specific branch, provide the desired base subject instead:\n\n```golang\nfor subject, err := range client.ReadSubjects(\n  context.TODO(),\n  \"/books\",\n) {\n  // ...\n}\n```\n\n#### Aborting Listing\n\nIf 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.\n\nTo abort listing independently of that, cancel the context you provided:\n\n```golang\nctx, cancel := context.WithCancel(context.TODO())\n\nfor subject, err := range client.ReadSubjects(\n  ctx,\n  \"/\",\n) {\n  // ...\n}\n\n// Somewhere else, cancel the context, which will cause\n// reading to end.\ncancel()\n```\n\n### Listing Event Types\n\nTo list all event types, call the `ReadEventTypes` function. The function returns an iterator, which you can use e.g. inside a `for range` loop:\n\n```golang\nfor eventType, err := range client.ReadEventTypes(\n  context.TODO(),\n) {\n  // ...\n}\n```\n\n#### Aborting Listing\n\nIf 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.\n\nTo abort listing independently of that, cancel the context you provided:\n\n```golang\nctx, cancel := context.WithCancel(context.TODO())\n\nfor eventType, err := range client.ReadEventTypes(\n  context.TODO(),\n) {\n  // ...\n}\n\n// Somewhere else, cancel the context, which will cause\n// reading to end.\ncancel()\n```\n\n### Listing a Specific Event Type\n\nTo 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:\n\n```golang\neventType, err := client.ReadEventType(\n  \"io.eventsourcingdb.library.book-acquired\",\n)\n```\n\n### Verifying an Event's Hash\n\nTo 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:\n\n```golang\nerr := event.VerifyHash()\nif err != nil {\n  // ...\n}\n```\n\n*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.*\n\n### Verifying an Event's Signature\n\nTo 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.\n\nThe function first verifies the event's hash, and then checks the signature. If any verification step fails, it returns an error:\n\n```golang\nimport \"crypto/ed25519\"\n\n// ...\n\nverificationKey := /* public key as ed25519.PublicKey */\n\nerr := event.VerifySignature(verificationKey)\nif err != nil {\n  // ...\n}\n```\n\n### Using Testcontainers\n\nCall the `NewContainer` function, start the test container, defer stopping it, get a client, and run your test code:\n\n```go\nctx := context.TODO()\n\ncontainer := eventsourcingdb.NewContainer()\ncontainer.Start(ctx)\ndefer container.Stop(ctx)\n\nclient, err := container.GetClient(ctx)\nif err != nil {\n  // ...\n}\n\n// ...\n```\n\nTo check if the test container is running, call the `IsRunning` function:\n\n```go\nisRunning := container.IsRunning()\n```\n\n#### Configuring the Container Instance\n\nBy default, `Container` uses the `latest` tag of the official EventSourcingDB Docker image. To change that, call the `WithImageTag` function:\n\n```go\ncontainer := eventsourcingdb.NewContainer().\n  WithImageTag(\"1.0.0\")\n```\n\nSimilarly, you can configure the port to use and the API token. Call the `WithPort` or the `WithAPIToken` function respectively:\n\n```go\ncontainer := eventsourcingdb.NewContainer().\n  WithPort(4000).\n  WithAPIToken(\"secret\")\n```\n\nIf you want to sign events, call the `WithSigningKey` function. This generates a new signing and verification key pair inside the container:\n\n```go\ncontainer := eventsourcingdb.NewContainer().\n  WithSigningKey()\n```\n\nYou can retrieve the private key (for signing) and the public key (for verifying signatures) once the container has been started:\n\n```go\nsigningKey, err := container.GetSigningKey()\nverificationKey, err := container.GetVerificationKey()\n```\n\nThe `signingKey` can be used when configuring the container to sign outgoing events. The `verificationKey` can be passed to `VerifySignature` when verifying events read from the database.\n\n#### Configuring the Client Manually\n\nIn case you need to set up the client yourself, use the following functions to get details on the container:\n\n- `GetHost()` returns the host name\n- `GetMappedPort()` returns the port\n- `GetBaseURL()` returns the full URL of the container\n- `GetAPIToken()` returns the API token\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthenativeweb%2Feventsourcingdb-client-golang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthenativeweb%2Feventsourcingdb-client-golang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthenativeweb%2Feventsourcingdb-client-golang/lists"}