pg_eventstore 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e22bb2356955ece89a16f5d43b803670d0304eaf27d2fedbf1daf12aa908812
-  data.tar.gz: 31d95e0380be2ad8dd7306a1b04a8a14e6f4f32f6bcdb8864e42205c0a1fe9bc
+  metadata.gz: e1716f5a502b55d670c94cd1950f03dfa1e307050a665435840004e1eb6e2158
+  data.tar.gz: d76b116150c351e00fa72b88c03472dbe987140c88b00e1211e81e7eb580a8cb
 SHA512:
-  metadata.gz: 8cda13e213beec47c83818301b415d1dbf5b80e0659e548c6d166a3e136172c38802b697353f13344bb0d6b15b99b54f59e950ab9fb2f07e7bf494adedb2c280
-  data.tar.gz: 5f0743afb46b2dcd00c9c164b51beb6f4ea6284b839a0036418d46e60e7d7b8a53d378a1eb265fc063364970ae6fb2b0091fabae51429775bec2f8c1c2e843fa
+  metadata.gz: 131c82d96b36d105a8b5f90829864ceca96209a5dfd09ed56b27e55f7f6dc755f30fffc10c837f62017ee557a7611518f5550b43d21af00112399e7f0fe3ede1
+  data.tar.gz: ce52feba0bee2e4737a9e8edae5fa880ca1d66cd15e07045bd6bd965713a7f5aed0370e119d3edf63760340f369c18c242555ae0ef0d3c94cec9447791d39ec0

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [Unreleased]
+
+## [0.5.0] - 2024-02-05
+
+- Fix event class resolving when providing `resolve_link_tos: true` option
+- Return correct stream revision of the `Event#stream` object of the appended event
+- Implement events linking feature
+- Implement paginated read
+- Remove duplicated `idx_events_event_type_id` index
+
+## [0.4.0] - 2024-01-29
+
+- Implement asynchronous subscriptions. Refer to the documentation for more info
+
 ## [0.3.0] - 2024-01-24
 
 - Log SQL queries when `PgEvenstore.logger` is set and it is in `:debug` mode 

data/CODE_OF_CONDUCT.md

@@ -39,7 +39,7 @@ This Code of Conduct applies within all community spaces, and also applies when
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at intale.a@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at ivan.dzyzenko@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the reporter of any incident.
 

data/README.md

@@ -52,7 +52,9 @@ Documentation chapters:
 - [Configuration](docs/configuration.md)
 - [Events and streams definitions](docs/events_and_streams.md)
 - [Appending events](docs/appending_events.md)
+- [Linking events](docs/linking_events.md)
 - [Reading events](docs/reading_events.md)
+- [Subscriptions](docs/subscriptions.md)
 - [Writing middlewares](docs/writing_middleware.md)
 - [How to make multiple commands atomic](docs/multiple_commands.md)
 

data/db/migrations/10_create_subscription_commands.sql

@@ -0,0 +1,15 @@
+CREATE TABLE public.subscription_commands
+(
+    id              bigserial                   NOT NULL,
+    name            character varying           NOT NULL,
+    subscription_id bigint                      NOT NULL,
+    created_at      timestamp without time zone NOT NULL DEFAULT now()
+);
+
+ALTER TABLE ONLY public.subscription_commands
+    ADD CONSTRAINT subscription_commands_pkey PRIMARY KEY (id);
+
+CREATE UNIQUE INDEX idx_subscription_commands_subscription_id_and_name ON public.subscription_commands USING btree (subscription_id, name);
+
+ALTER TABLE ONLY public.subscription_commands
+    ADD CONSTRAINT subscription_commands_subscription_fk FOREIGN KEY (subscription_id) REFERENCES public.subscriptions (id) ON DELETE CASCADE;

data/db/migrations/11_create_subscriptions_set_commands.sql

@@ -0,0 +1,15 @@
+CREATE TABLE public.subscriptions_set_commands
+(
+    id                   bigserial                   NOT NULL,
+    name                 character varying           NOT NULL,
+    subscriptions_set_id uuid                        NOT NULL,
+    created_at           timestamp without time zone NOT NULL DEFAULT now()
+);
+
+ALTER TABLE ONLY public.subscriptions_set_commands
+    ADD CONSTRAINT subscriptions_set_commands_pkey PRIMARY KEY (id);
+
+CREATE UNIQUE INDEX idx_subscr_set_commands_subscriptions_set_id_and_name ON public.subscriptions_set_commands USING btree (subscriptions_set_id, name);
+
+ALTER TABLE ONLY public.subscriptions_set_commands
+    ADD CONSTRAINT subscriptions_set_commands_subscriptions_set_fk FOREIGN KEY (subscriptions_set_id) REFERENCES public.subscriptions_set (id) ON DELETE CASCADE;

data/db/migrations/12_improve_events_indexes.sql

@@ -0,0 +1 @@
+CREATE INDEX idx_events_event_type_id_and_global_position ON public.events USING btree (event_type_id, global_position);

data/db/migrations/13_remove_duplicated_index.sql

@@ -0,0 +1 @@
+DROP INDEX idx_events_event_type_id;

data/db/migrations/9_create_subscriptions.sql

@@ -0,0 +1,46 @@
+CREATE TABLE public.subscriptions_set
+(
+    id                     uuid                                 DEFAULT public.gen_random_uuid() NOT NULL,
+    name                   character varying           NOT NULL,
+    state                  character varying           NOT NULL DEFAULT 'initial',
+    restart_count          integer                     NOT NULL DEFAULT 0,
+    max_restarts_number    int2                        NOT NULL DEFAULT 10,
+    time_between_restarts  int2                        NOT NULL DEFAULT 1,
+    last_restarted_at      timestamp without time zone,
+    last_error             jsonb,
+    last_error_occurred_at timestamp without time zone,
+    created_at             timestamp without time zone NOT NULL DEFAULT now(),
+    updated_at             timestamp without time zone NOT NULL DEFAULT now()
+);
+
+ALTER TABLE ONLY public.subscriptions_set
+    ADD CONSTRAINT subscriptions_set_pkey PRIMARY KEY (id);
+
+CREATE TABLE public.subscriptions
+(
+    id                            bigserial                   NOT NULL,
+    set                           character varying           NOT NULL,
+    name                          character varying           NOT NULL,
+    options                       jsonb                       NOT NULL DEFAULT '{}'::jsonb,
+    total_processed_events        bigint                      NOT NULL DEFAULT 0,
+    current_position              bigint,
+    average_event_processing_time float4,
+    state                         character varying           NOT NULL DEFAULT 'initial',
+    restart_count                 integer                     NOT NULL DEFAULT 0,
+    max_restarts_number           int2                        NOT NULL DEFAULT 100,
+    time_between_restarts         int2                        NOT NULL DEFAULT 1,
+    last_restarted_at             timestamp without time zone,
+    last_error                    jsonb,
+    last_error_occurred_at        timestamp without time zone,
+    chunk_query_interval          int2                        NOT NULL DEFAULT 5,
+    last_chunk_fed_at             timestamp without time zone NOT NULL DEFAULT to_timestamp(0),
+    last_chunk_greatest_position  bigint,
+    locked_by                     uuid,
+    created_at                    timestamp without time zone NOT NULL DEFAULT now(),
+    updated_at                    timestamp without time zone NOT NULL DEFAULT now()
+);
+
+ALTER TABLE ONLY public.subscriptions
+    ADD CONSTRAINT subscriptions_pkey PRIMARY KEY (id);
+
+CREATE UNIQUE INDEX idx_subscriptions_set_and_name ON public.subscriptions USING btree (set, name);

data/docs/configuration.md

@@ -2,21 +2,23 @@
 
 Configuration options:
 
-| name                    | value    | default value                                                | description                                                                                                                                                                                                                                                            |
-|-------------------------|----------|--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| pg_uri                  | String   | `'postgresql://postgres:postgres@localhost:5432/eventstore'` | PostgreSQL connection string. See PostgreSQL [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS) for more information.                                                                                                            |
-| max_count               | Integer  | `1000`                                                       | Number of events to return in one response when reading from a stream.                                                                                                                                                                                                 |
-| middlewares             | Array    | `{}`                                                         | A hash where a key is a name of your middleware and value is an object that respond to `#serialize` and `#deserialize` methods. See [**Writing middleware**](writing_middleware.md) chapter.                                                                           |
-| event_class_resolver    | `#call`  | `PgEventstore::EventClassResolver.new`                       | A `#call`-able object that accepts a string and returns an event's class. See **Resolving events classes** chapter bellow for more info.                                                                                                                               |
-| logger                  | `Logger` | `nil`                                                        | A logger that logs messages from `pg_eventstore` gem.                                                                                                                                                                                                                  |
-| connection_pool_size    | Integer  | `5`                                                          | Max number of connections per ruby process. It must equal the number of threads of your application.                                                                                                                                                                   |
-| connection_pool_timeout | Integer  | `5`                                                          | Time in seconds to wait for the connection in pool to be released. If no connections are available during this time - `ConnectionPool::TimeoutError` will be raised. See `connection_pool` gem [docs](https://github.com/mperham/connection_pool#usage) for more info. |
+| name                               | value   | default value                                                | description                                                                                                                                                                                                                                                                                                            |
+|------------------------------------|---------|--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| pg_uri                             | String  | `'postgresql://postgres:postgres@localhost:5432/eventstore'` | PostgreSQL connection string. See PostgreSQL [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS) for more information.                                                                                                                                                            |
+| max_count                          | Integer | `1000`                                                       | Number of events to return in one response when reading from a stream.                                                                                                                                                                                                                                                 |
+| middlewares                        | Array   | `{}`                                                         | A hash where a key is a name of your middleware and value is an object that respond to `#serialize` and `#deserialize` methods. See [**Writing middleware**](writing_middleware.md) chapter.                                                                                                                           |
+| event_class_resolver               | `#call` | `PgEventstore::EventClassResolver.new`                       | A `#call`-able object that accepts a string and returns an event's class. See **Resolving events classes** chapter bellow for more info.                                                                                                                                                                               |
+| connection_pool_size               | Integer | `5`                                                          | Max number of connections per ruby process. It must equal the number of threads of your application. When using subscriptions it is recommended to set it to the number of subscriptions divided by two or greater. See [**Picking max connections number**](#picking-max-connections-number) chapter of this section. |
+| connection_pool_timeout            | Integer | `5`                                                          | Time in seconds to wait for a connection in the pool to be released. If no connections are available during this time - `ConnectionPool::TimeoutError` will be raised. See `connection_pool` gem [docs](https://github.com/mperham/connection_pool#usage) for more info.                                               |
+| subscription_pull_interval         | Integer | `2`                                                          | How often to pull new subscription events in seconds.                                                                                                                                                                                                                                                                  |
+| subscription_max_retries           | Integer | `5`                                                          | Max number of retries of failed subscription.                                                                                                                                                                                                                                                                          |
+| subscription_retries_interval      | Integer | `1`                                                          | Interval in seconds between retries of failed subscriptions.                                                                                                                                                                                                                                                           |
+| subscriptions_set_max_retries      | Integer | `10`                                                         | Max number of retries for failed subscription sets.                                                                                                                                                                                                                                                                    |
+| subscriptions_set_retries_interval | Integer | `1`                                                          | interval in seconds between retries of failed subscription sets.                                                                                                                                                                                                                                                       |
 
 ## Multiple configurations
 
-`pg_eventstore` allows you to have as many configs as you want. This allows you, for example, to have different
-databases, or to have a different set of middlewares for specific cases only. To do so, you have to name your
-configuration, and later provide that name to `PgEventstore` client.
+`pg_eventstore` allows you to have as many configs as you want. This allows you, for example, to have different databases, or to have a different set of middlewares for specific cases only. To do so, you have to name your configuration, and later provide that name to `PgEventstore` client.
 
 Setup your configs:
 
@@ -42,8 +44,7 @@ PgEventstore.client(:pg_db_2).read(PgEventstore::Stream.all_stream)
 
 ### Default config
 
-If you have one config only - you don't have to bother naming it or passing a config name to the client when performing
-any operations. You can configure it as usual.
+If you have one config only - you don't have to bother naming it or passing a config name to the client when performing any operations. You can configure it as usual.
 
 Setup your default config:
 
@@ -64,19 +65,39 @@ EventStoreClient.client.read(PgEventstore::Stream.all_stream)
 
 ## Resolving event classes
 
-During the deserialization process `pg_eventstore` tries to pick the correct class for an event. By default it does it
-using the `PgEventstore::EventClassResolver` class. All it does is `Object.const_get(event_type)`. By default, if you
-don't provide the `type` attribute for an event explicitly, it will grab the event's class name, meaning by default:
+During the deserialization process `pg_eventstore` tries to pick the correct class for an event. By default it does it using the `PgEventstore::EventClassResolver` class. All it does is `Object.const_get(event_type)`. By default, if you don't provide the `type` attribute for an event explicitly, it will grab the event's class name, meaning by default:
 
 - event's type is event's class name
-- when instantiating an event - `pg_eventstore` tries to lookup an event class based on the value of event's `type`
-  attribute with a fallback to `PgEventstore::Event` class
+- when instantiating an event - `pg_eventstore` tries to lookup an event class based on the value of event's `type` attribute with a fallback to `PgEventstore::Event` class
 
-You can override the default event class resolver by providing any `#call`-able object. It should accept event's type
-and return event's class based on it. Example:
+You can override the default event class resolver by providing any `#call`-able object. It should accept event's type and return event's class based on it. Example:
 
 ```ruby
 PgEventstore.configure do |config|
   config.event_class_resolver = proc { |event_type| Object.const_get(event_type.gsub('Foo', 'Bar')) rescue PgEventstore::Event }
 end
 ```
+
+## Picking max connections number
+
+A connection is hold from the connection pool to perform the request and it is released back to the connection pool once the request is finished. If you run into the (theoretical) edge case, when all your application's threads (or subscriptions) are performing `pg_eventstore` queries at the same time and all those queries take more than `connection_pool_timeout` seconds to complete, you have to have `connection_pool_size` set to the exact amount of your application's threads (or to the number of subscriptions when using subscriptions) to prevent timeout errors. Practically this is not the case, as all `pg_eventstore` queries are pretty fast. So, a good value for the `connection_pool_size` option is **half the number ** of your application's threads(or half the number of Subscriptions).
+
+### Exception scenario
+
+If you are using the [`#multiple`](multiple_commands.md) method - you have to take into account the execution time of the whole block you pass in it. This is because the connection will be released only after the block's execution is finished. So, for example, if you perform several commands within the block, as well as some API request, the connection will be release only after all those steps:
+
+```ruby
+PgEventstore.client.multiple do
+  # Connection is hold from the connection pool
+  PgEventstore.client.read(some_stream)
+  Stripe::Payment.create(some_attrs)
+  PgEventstore.client.append_to_stream(some_stream, some_event)
+  # Connection is released
+end
+```
+
+Taking this into account you may want to increase `connection_pool_size` up to the number of your application's threads(or subscriptions).
+
+### Usage of external connection pooler
+
+`pg_eventstore` does not use any session-specific features of PostgreSQL. You can use any PostgreSQL connection pooler you like, such as [PgBouncer](https://www.pgbouncer.org/) for example. 

data/docs/linking_events.md

@@ -0,0 +1,96 @@
+# Linking Events
+
+## Linking single event
+
+You can create a link to an existing event. Next example demonstrates how you can link an existing event from another stream:
+
+```ruby
+class SomethingHappened < PgEventstore::Event
+end
+
+event = SomethingHappened.new(
+  type: 'some-event', data: { title: 'Something happened' }
+)
+
+events_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+projection_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeProjection', stream_id: '1')
+# Persist our event
+event = PgEventstore.client.append_to_stream(events_stream, event)
+
+# Link event into your projection
+PgEventstore.client.link_to(projection_stream, event)
+```
+
+The linked event can later be fetched by providing the `:resolve_link_tos` option when reading from the stream:
+
+```ruby
+projection_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeProjection', stream_id: '1')
+PgEventstore.client.read(projection_stream, options: { resolve_link_tos: true })
+```
+
+If you don't provide the `:resolve_link_tos` option, the linked event will be returned instead of the original one.
+
+## Linking multiple events
+
+You can provide an array of events to link to the target stream:
+
+```ruby
+class SomethingHappened < PgEventstore::Event
+end
+
+events = 3.times.map { |i| SomethingHappened.new(type: 'some-event', data: { title: "Something happened-#{i}" }) }
+events_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+projection_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeProjection', stream_id: '1')
+events = PgEventstore.client.append_to_stream(events_stream, events)
+# Link events
+PgEventstore.client.link_to(projection_stream, events)
+```
+
+## Handling concurrency
+
+Linking concurrency is implemented the same way as appending concurrency. You can check [**Handling concurrency**](appending_events.md#handling-concurrency) chapter of **Appending Events** section.
+
+Example:
+
+```ruby
+require 'securerandom'
+class SomethingHappened < PgEventstore::Event
+end
+
+event1 = SomethingHappened.new
+event2 = SomethingHappened.new
+
+events_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+projection_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeProjection', stream_id: SecureRandom.uuid)
+
+event1, event2 = PgEventstore.client.append_to_stream(events_stream, [event1, event2])
+
+# Links first event
+PgEventstore.client.link_to(projection_stream, event1, options: { expected_revision: :no_stream })
+# Raises PgEventstore::WrongExpectedVersionError error because stream already exists
+PgEventstore.client.link_to(projection_stream, event2, options: { expected_revision: :no_stream })
+```
+
+## Middlewares
+
+If you would like to modify your link events before they get persisted - you should use the `:middlewares` argument which allows you to pass the list of middlewares you would like to use. **By default no middlewares will be applied to the link event despite on `config.middlewares` option**.
+
+Let's say you have these registered middlewares:
+
+```ruby
+PgEventstore.configure do |config|
+  config.middlewares = { foo: FooMiddleware.new, bar: BarMiddleware.new, baz: BazMiddleware.new }
+end
+```
+
+And you want to use `FooMiddleware` and `BazMiddleware`. You simply have to provide an array of corresponding middleware keys you would like to use:
+
+```ruby
+events_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+projection_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeProjection', stream_id: '1')
+
+event = PgEventstore.client.append_to_stream(events_stream, PgEventstore::Event.new)
+PgEventstore.client.link_to(projection_stream, event, middlewares: %i[foo baz])
+```
+
+See [Writing middleware](writing_middleware.md) chapter for info about what is middleware and how to implement it.

data/docs/reading_events.md

@@ -159,3 +159,59 @@ You can also mix filtering by stream's attributes and event types. The result wi
 ```ruby
 PgEventstore.client.read(PgEventstore::Stream.all_stream, options: { filter: { streams: [{ context: 'MyAwesomeContext' }], event_types: %w[Foo Bar] } })
 ```
+
+
+## Pagination
+
+You can use `#read_paginated` to iterate over all (filtered) events. It yields each batch of records that was found according to the filter options:
+
+```ruby
+# Read from the specific stream
+stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'User', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')
+PgEventstore.client.read_paginated(stream).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+
+# Read from "all" stream
+PgEventstore.client.read_paginated(PgEventstore::Stream.all_stream).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+```
+
+Options are the same as for `#read` method. Several examples:
+
+```ruby
+# Read "Foo" events only from the specific stream
+stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'User', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')
+PgEventstore.client.read_paginated(stream, options: { filter: { event_types: ['Foo'] } }).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+
+# Backwards read from "all" stream
+PgEventstore.client.read_paginated(PgEventstore::Stream.all_stream, options: { direction: 'Backwards' }).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+
+# Set batch size to 100
+PgEventstore.client.read_paginated(PgEventstore::Stream.all_stream, options: { max_count: 100 }).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+
+# Reading from projection stream
+projection_stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'MyAwesomeProjection', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae') 
+PgEventstore.client.read_paginated(projection_stream, options: { resolve_link_tos: true }).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+```

data/docs/subscriptions.md

@@ -0,0 +1,170 @@
+# Subscriptions
+
+In order to process new events in your microservices you have to have the ability to listen for them. `pg_eventstore` implements a subscription feature for this matter. It is implemented as a background thread that pulls new events according to your filters from time to time (see `subscription_pull_interval` setting option under [**Configuration**](configuration.md) chapter).
+
+## PgEventstore::Subscription
+
+`pg_eventstore` stores various subscription information in the database. The corresponding object that describes the database records is the `PgEventstore::Subscription` object. It is used in the `config.subscription_restart_terminator` setting for example. You can find its attributes summary [here](https://rubydoc.info/gems/pg_eventstore/PgEventstore/Subscription).  
+
+## PgEventstore::SubscriptionsSet
+
+`pg_eventstore` also stores information about which subscriptions are set. The corresponding object that describes the database records is `PgEventstore::SubscriptionsSet`. You can find its attributes summary [here](https://rubydoc.info/gems/pg_eventstore/PgEventstore/SubscriptionsSet).
+
+This record is created when you start your subscriptions. All subscriptions created using a single subscriptions manager instance are locked using a single `PgEventstore::SubscriptionsSet`. When subscriptions are locked, they can't be managed anywhere else. When you stop your subscriptions, the `PgEventstore::SubscriptionsSet` is deleted, unlocking the subscriptions. The `SubscriptionSet` also holds information about the state, number of restarts, the restart interval and last error of the background runner which is responsible for pulling the subscription's events. You can set the max number of restarts and the restarts interval of your subscriptions set via `config.subscriptions_set_max_retries` and `config.subscriptions_set_retries_interval` settings. See [**Configuration**](configuration.md) chapter for more info.
+
+## Creating a subscription
+
+First step you need to do is to create a `PgEventstore::SubscriptionsManager` object and provide the `subscription_set` keyword argument. Optionally you can provide a config name to use, override the `config.subscriptions_set_max_retries` and `config.subscriptions_set_retries_interval` settings:
+
+```ruby
+subscriptions_manager = PgEventstore.subscriptions_manager(subscription_set: 'SubscriptionsOfMyAwesomeMicroservice')
+another_subscriptions_manager = PgEventstore.subscriptions_manager(:my_custom_config, subscription_set: 'SubscriptionsOfMyAwesomeMicroservice', max_retries: 5, retries_interval: 2)
+```
+
+The required `subscription_set` option groups your subscriptions into a set. For example, you could refer to your service's name in the subscription set name.
+
+Now we can use the `#subscribe` method to create the subscription:
+
+```ruby
+subscriptions_manager.subscribe('MyAwesomeSubscription', handler: proc { |event| puts event })
+```
+
+First argument is the subscription's name. **It must be unique within the subscription set**. Second argument is your subscription's handler where you will be processing your events as they arrive. The example shows the minimum set of arguments required to create the subscription. 
+
+In the given state it will be listening to all events from all streams. You can define various filters by providing the `:filter` key of `options` argument:
+
+```ruby
+subscriptions_manager.subscribe(
+  'MyAwesomeSubscription', 
+  handler: proc { |event| puts event }, 
+  options: { filter: { streams: [{ context: 'MyAwesomeContext' }], event_types: ['Foo', 'Bar'] } }
+)
+```
+
+`:filter` supports the same options as the `#read` method supports when reading from the `"all"` stream. See [*"all" stream filtering*](reading_events.md#all-stream-filtering) section of **Reading events** chapter.
+
+After you added all necessary subscriptions, it is time to start them:
+
+```ruby
+subscriptions_manager.start
+```
+
+After calling `#start` all subscriptions are locked behind the given subscription set and can't be locked by any other subscription set. This measure is needed to prevent running the same subscription under the same subscription set using different processes/subscription managers. Such situation will lead to a malformed subscription state and will break its position, meaning the same event will be processed several times.
+
+To "unlock" the subscription you should gracefully stop the subscription manager:
+
+```ruby
+subscriptions_manager.stop
+```
+
+If you shut down the process which runs your subscriptions without calling the `#stop` method, subscriptions will remain locked, and the only way to unlock them will be to call the `#force_lock!` method before calling the `#start` method:
+
+```ruby
+subscriptions_manager.force_lock!
+subscriptions_manager.start
+```
+
+A complete example of the subscription setup process looks like this:
+
+```ruby
+require 'pg_eventstore'
+
+PgEventstore.configure do |config|
+  config.pg_uri = ENV.fetch('PG_EVENTSTORE_URI') { 'postgresql://postgres:postgres@localhost:5532/eventstore' }  
+end
+
+subscriptions_manager = PgEventstore.subscriptions_manager(subscription_set: 'MyAwesomeSubscriptions')
+subscriptions_manager.subscribe(
+  'Foo events Subscription', 
+  handler: proc { |event| p "Foo events Subscription: #{event.inspect}" }, 
+  options: { filter: { event_types: ['Foo'] } }
+)
+subscriptions_manager.subscribe(
+  '"BarCtx" context Subscription',
+  handler: proc { |event| p "'BarCtx' context Subscription: #{event.inspect}" }, 
+  options: { filter: { streams: [{ context: 'BarCtx' }] } 
+  }
+)
+subscriptions_manager.force_lock! if ENV['FORCE_LOCK'] == 'true'
+subscriptions_manager.start
+
+Kernel.trap('TERM') do
+  puts "Received TERM signal. Stopping Subscriptions Manager and exiting..."
+  # It is important to wrap subscriptions_manager.stop into another Thread, because it uses Thread::Mutex#synchronize
+  # internally, but its usage is not allowed inside Kernel.trap block
+  Thread.new { subscriptions_manager.stop }.join
+  exit
+end
+
+loop do
+  sleep 5
+  subscriptions_manager.subscriptions.each do |subscription|
+    puts <<~TEXT
+      Subscription <<#{subscription.name.inspect}>> is at position #{subscription.current_position}. \
+      Events processed: #{subscription.total_processed_events}
+    TEXT
+  end
+  puts "Current SubscriptionsSet: #{subscriptions_manager.subscriptions_set}"
+  puts ""
+end
+```
+
+You can save this script in `subscriptions.rb`, run it with `bundle exec ruby subscriptions.rb`, open another ruby console and test posting different events:
+
+```ruby
+require 'pg_eventstore'
+
+PgEventstore.configure do |config|
+  config.pg_uri = ENV.fetch('PG_EVENTSTORE_URI') { 'postgresql://postgres:postgres@localhost:5532/eventstore' }
+end
+
+foo_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+bar_stream = PgEventstore::Stream.new(context: 'BarCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+PgEventstore.client.append_to_stream(foo_stream, PgEventstore::Event.new(type: 'Foo', data: { foo: :bar }))
+PgEventstore.client.append_to_stream(bar_stream, PgEventstore::Event.new(type: 'Foo', data: { foo: :bar }))
+```
+
+You will then see the output of your subscription handlers. To gracefully stop the subscriptions process, use `kill -TERM <pid>` command.
+
+## Overriding Subscription config values
+
+You can override `subscription_pull_interval`, `subscription_max_retries`, `subscription_retries_interval` and `subscription_restart_terminator` config values (see [**Configuration**](configuration.md) chapter for details) for the specific subscription by providing the corresponding arguments. Example:
+
+```ruby
+subscriptions_manager.subscribe(
+  'MyAwesomeSubscription', 
+  handler: proc { |event| puts event },
+  # overrides config.subscription_pull_interval
+  pull_interval: 1,
+  # overrides config.subscription_max_retries
+  max_retries: 10,
+  # overrides config.subscription_retries_interval
+  retries_interval: 2,
+  # overrides config.subscription_restart_terminator
+  restart_terminator: proc { |subscription| subscription.last_error['class'] == 'NoMethodError' }, 
+)
+```
+
+## Middlewares
+
+If you would like to skip some of your registered middlewares from processing events after they are being pulled by the subscription, you should use the `:middlewares` argument which allows you to override the list of middlewares you would like to use.
+
+Let's say you have these registered middlewares:
+
+```ruby
+PgEventstore.configure do |config|
+  config.middlewares = { foo: FooMiddleware.new, bar: BarMiddleware.new, baz: BazMiddleware.new }
+end
+```
+
+And you want to skip `FooMiddleware` and `BazMiddleware`. You simply have to provide an array of corresponding middleware keys you would like to use when creating the subscription:
+
+```ruby
+subscriptions_manager.subscribe('MyAwesomeSubscription', handler: proc { |event| puts event }, middlewares: %i[bar])
+```
+
+See the [Writing middleware](writing_middleware.md) chapter for info about what is middleware and how to implement it.
+
+## How many subscriptions I should put in one process?
+
+It depends on the nature of your subscription handlers. If they spend more time on ruby code execution than on IO operations, you should limit the number of subscriptions per single process. This can be especially noticed when you rebuild the read models of your microservice, processing all events from the start.