<commit_before>---
title: Event serialization formats
---

By default RailsEventStore will use `YAML` as a
serialization format. The reason is that `YAML` is available out of box
and can serialize and deserialize data types which are not easily
handled in other formats. 

However, if you don't like `YAML` or you have different needs you can
choose to use different serializers or even replace mappers entirely.

## Configuring a different serializer

You can pass a different `serializer` as a dependency when [instantiating
the client](/docs/install).

Here is an example on how to configure RailsEventStore to serialize
events' `data` and `metadata` using `Marshal`.

```ruby
# config/environments/*.rb

Rails.application.configure do
  config.to_prepare do
    Rails.configuration.event_store = RailsEventStore::Client.new(
      mapper: RubyEventStore::Mappers::Default.new(
        serializer: Marshal
      )
    )
  end
end
```

The provided `serializer` must respond to `load` and `dump`.


## Configuring a different mapper

JSON is a popular serialization choice when paired with JSON/JSONB storage on Potgres. To make full use of it, set:

```ruby
# config/environments/*.rb

Rails.application.configure do
  config.to_prepare do
    Rails.configuration.event_store = RailsEventStore::Client.new(
      mapper: RubyEventStore::Mappers::JSONMapper.new
    )
  end
end

```

Additionally, if you are using Postgres, you can tell the migration to use JSON or JSONB data types for the `data` and `metadata` fields by
passing in a `--data-type` to the generator.

```console
$ rails generate rails_event_store_active_record:migration --data-type=jsonb
```

<div class="bg-blue-100 border-l-4 border-blue-500 text-blue-600 px-4" role="alert">
  <p class="text-base font-bold">Bear in mind that <code>JSON</code> will convert symbols to strings and you have to prepare for that when retrieving events.</p>
  <p class="text-base inline-block">
<code>
JSON.load(JSON.dump({foo: :bar}))
=> {"foo"=>"bar"}
</code>

One way to approach this is to have your own event adapter, specific for the project you're working on.

<code>
class MyEvent < RailsEventStore::Event
  def data
    ActiveSupport::HashWithIndifferentAccess.new(super)
  end
end

OrderPlaced = Class.new(MyEvent)
</code>

That shields you from data keys being transformed from symbols into strings. It doesn't do anything with data values associated to those keys.

<code>
event_store.publish(OrderPlaced.new(event_id: 'e34fc19a-a92f-4c21-8932-a10f6fb2602b', data: { foo: :bar }))
event = event_store.read.event('e34fc19a-a92f-4c21-8932-a10f6fb2602b')

event.data[:foo]
# => "bar"

event.data['foo']
# => "bar"
</code>

  <p class="text-base inline-block">
    Another way to achive that could be define your own <a href="https://railseventstore.org/docs/mapping_serialization/#custom-mapper">custom mapper and transformation</a>
  </p>
</div>






### Available mappers

- [`RubyEventStore::Mappers::Default`](https://github.com/RailsEventStore/rails_event_store/blob/master/ruby_event_store/lib/ruby_event_store/mappers/default.rb)
  - works with `RubyEventStore::Event` or `RailsEventStore::Event`
  - constructor takes named arguments:<commit_msg>Update mapping_serialization.html.md.erb<commit_after>---
title: Event serialization formats
---

By default RailsEventStore will use `YAML` as a
serialization format. The reason is that `YAML` is available out of box
and can serialize and deserialize data types which are not easily
handled in other formats. 

However, if you don't like `YAML` or you have different needs you can
choose to use different serializers or even replace mappers entirely.

## Configuring a different serializer

You can pass a different `serializer` as a dependency when [instantiating
the client](/docs/install).

Here is an example on how to configure RailsEventStore to serialize
events' `data` and `metadata` using `Marshal`.

```ruby
# config/environments/*.rb

Rails.application.configure do
  config.to_prepare do
    Rails.configuration.event_store = RailsEventStore::Client.new(
      mapper: RubyEventStore::Mappers::Default.new(
        serializer: Marshal
      )
    )
  end
end
```

The provided `serializer` must respond to `load` and `dump`.


## Configuring a different mapper

JSON is a popular serialization choice when paired with JSON/JSONB storage on Potgres. To make full use of it, set:

```ruby
# config/environments/*.rb

Rails.application.configure do
  config.to_prepare do
    Rails.configuration.event_store = RailsEventStore::Client.new(
      mapper: RubyEventStore::Mappers::JSONMapper.new
    )
  end
end

```

Additionally, if you are using Postgres, you can tell the migration to use JSON or JSONB data types for the `data` and `metadata` fields by
passing in a `--data-type` to the generator.

```console
$ rails generate rails_event_store_active_record:migration --data-type=jsonb
```

<div class="bg-blue-100 border-l-4 border-blue-500 text-blue-600 px-4" role="alert">
  <p class="text-base font-bold">Bear in mind that <code>JSON</code> will convert symbols to strings and you have to prepare for that when retrieving events.</p>
  <p class="text-base inline-block">
    <pre class="syntax-highlight ruby">
<code>
JSON.load(JSON.dump({foo: :bar}))
=> {"foo"=>"bar"}
</code>
    </pre></div>

One way to approach this is to have your own event adapter, specific for the project you're working on.

  <p class="text-base inline-block">
    <pre class="syntax-highlight ruby">
<code>
class MyEvent < RailsEventStore::Event
  def data
    ActiveSupport::HashWithIndifferentAccess.new(super)
  end
end

OrderPlaced = Class.new(MyEvent)
</code>
    </pre></div>

That shields you from data keys being transformed from symbols into strings. It doesn't do anything with data values associated to those keys.

  <p class="text-base inline-block">
    <pre class="syntax-highlight ruby">
<code>
event_store.publish(OrderPlaced.new(event_id: 'e34fc19a-a92f-4c21-8932-a10f6fb2602b', data: { foo: :bar }))
event = event_store.read.event('e34fc19a-a92f-4c21-8932-a10f6fb2602b')

event.data[:foo]
# => "bar"

event.data['foo']
# => "bar"
</code>
    </pre></div>

  <p class="text-base inline-block">
    Another way to achive that could be define your own <a href="https://railseventstore.org/docs/mapping_serialization/#custom-mapper">custom mapper and transformation</a>
  </p>
</div>






### Available mappers

- [`RubyEventStore::Mappers::Default`](https://github.com/RailsEventStore/rails_event_store/blob/master/ruby_event_store/lib/ruby_event_store/mappers/default.rb)
  - works with `RubyEventStore::Event` or `RailsEventStore::Event`
  - constructor takes named arguments:
{'fraction_non_alphanumeric': 0.11135957066189624, 'fraction_numerical': 0.01520572450805009, 'mean_word_length': 4.535478547854786, 'pattern_counts': {'":': 0, '<': 50, '<?xml version=': 0, '>': 56, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4670718', 'n_tokens_mistral': 2203, 'n_tokens_neox': 2071, 'n_words': 676}