# Events Store (/sdks/elixir/reference/events-store)



Events Store provides persistent messaging where events are stored on the server and can be replayed. Subscribers specify a starting position to control which events they receive.

## Structs [#structs]

### KubeMQ.EventStore [#kubemqeventstore]

Used to publish persistent events.

| Field       | Type                     | Description                       |
| ----------- | ------------------------ | --------------------------------- |
| `id`        | `String.t()`             | Auto-generated message ID         |
| `channel`   | `String.t()`             | Target channel name               |
| `metadata`  | `String.t()`             | Optional metadata string          |
| `body`      | `String.t() \| binary()` | Message payload                   |
| `client_id` | `String.t()`             | Sender client ID (auto-populated) |
| `tags`      | `map()`                  | Optional key-value tags           |

### KubeMQ.EventStoreReceive [#kubemqeventstorereceive]

Received by subscribers during replay or live delivery.

| Field       | Type                     | Description      |
| ----------- | ------------------------ | ---------------- |
| `id`        | `String.t()`             | Message ID       |
| `channel`   | `String.t()`             | Source channel   |
| `metadata`  | `String.t()`             | Metadata string  |
| `body`      | `String.t() \| binary()` | Message payload  |
| `timestamp` | `integer()`              | Server timestamp |
| `sequence`  | `integer()`              | Sequence number  |
| `tags`      | `map()`                  | Key-value tags   |

### KubeMQ.EventStoreResult [#kubemqeventstoreresult]

Confirmation returned after storing an event.

| Field   | Type         | Description                  |
| ------- | ------------ | ---------------------------- |
| `id`    | `String.t()` | Message ID                   |
| `sent`  | `boolean()`  | Whether the event was stored |
| `error` | `String.t()` | Error message if failed      |

## Start Positions [#start-positions]

| Position    | Value                            | Description                                 |
| ----------- | -------------------------------- | ------------------------------------------- |
| New only    | `:start_new_only`                | Only events published after subscribing     |
| From first  | `:start_from_first`              | Replay all stored events from the beginning |
| From last   | `:start_from_last`               | Start from the most recent stored event     |
| At sequence | `{:start_at_sequence, n}`        | Start from a specific sequence number       |
| At time     | `{:start_at_time, unix_seconds}` | Start from a specific Unix timestamp        |
| Time delta  | `{:start_at_time_delta, ms}`     | Start from N milliseconds ago               |

## Publishing [#publishing]

```elixir
event = KubeMQ.EventStore.new(
  channel: "audit-log",
  body: "user.login",
  metadata: "audit"
)

{:ok, result} = KubeMQ.Client.send_event_store(client, event)
IO.puts("Stored: #{result.sent}")
```

## Subscribing with Replay [#subscribing-with-replay]

```elixir
{:ok, sub} = KubeMQ.Client.subscribe_to_events_store(client, "audit-log",
  start_at: :start_from_first,
  group: "processors",
  on_event: fn event ->
    IO.puts("Seq #{event.sequence}: #{event.body}")
  end
)

KubeMQ.Subscription.cancel(sub)
```

## See Also [#see-also]

* [Events Store Examples](/sdks/elixir/how-to/events-store/)
* [Events Store Pattern Overview](/learn/events-store/)