pg_eventstore 0.10.1 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9426880dd6354875d896f5bf37abeac180c4f04b26905db0efc035fec316e6b9
-  data.tar.gz: 355a6c370451fff9e391aa0ecb1c6abf105c6fc537d99f6b7371359067dd2ee4
+  metadata.gz: fbcfe058d0769d031f29580fdd79e899a73987a3108b0b96ad154a5bb913a7d2
+  data.tar.gz: 0f071621693bca4b597defc2be13fbde054be06448648ace7324e8ce14e4e512
 SHA512:
-  metadata.gz: fc96e847b892e375115a08985678328d166742e5f6be3ee967f67dc808c80166a58f010555567b05fbac172b31c7d98276d1e898de6889d5d53d3ccf0ab2be47
-  data.tar.gz: cba82b0c20d4104cd6878fd2471e5c4d0c70e60991f573cd5aa1a845e7e5b443cf9f15448b81754888a84883c6bfbaf932e452c13fd7d5d229b03185741f1dbd
+  metadata.gz: fa8828e002dab641f15b8ed3756c822899b3937929482a8fb9dcbac4bb5c10b7283427fa462a627ee47209d4476157396749ced15d50b64892683b1309e897a8
+  data.tar.gz: 3482263831bc256851999a0093be615cf4e238ceeae5c27f209f2fcc3d8b666db8b4c68bc388e5ef0c52de8f52a65e6abfe4db864042161f823b867f4996e750

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [1.0.0.rc1]
+
+- Improve performance of loading original events when resolve_link_tos: true option is provided
+- Adjust `partitions` table indexes
+- Implement admin web UI. So far two pages were implemented - events search and subscriptions
+
+## [0.10.2] - 2024-03-13
+
+- Review the approach to resolve link events 
+- Fix subscriptions restart interval option not being processed correctly
+
 ## [0.10.1] - 2024-03-12
 
 - Handle edge case when creating partitions

data/README.md

@@ -47,6 +47,32 @@ Documentation chapters:
 - [Writing middlewares](docs/writing_middleware.md)
 - [How to make multiple commands atomic](docs/multiple_commands.md)
 
+## Admin web UI
+
+`pg_eventstore` implements admin UI where you can browse various database objects. It is implemented as rack application. It doesn't have any authentication/authorization mechanism - it is your responsibility to take care of it.
+
+### Rails integration
+
+In your `config/routes.rb`:
+
+```ruby
+require 'pg_eventstore/web'
+
+mount PgEventstore::Web::Application, at: '/eventstore'
+```
+
+### Standalone application
+
+Create `config.ru` file and place next content in there:
+
+```ruby
+require 'pg_eventstore/web'
+
+run PgEventstore::Web::Application
+```
+
+Now you can use any web server to run it.
+
 ## Development
 
 After checking out the repo, run:

data/db/migrations/1_create_events.sql

@@ -1,16 +1,17 @@
 CREATE TABLE public.events
 (
-    id              uuid                        DEFAULT public.gen_random_uuid() NOT NULL,
-    context         character varying COLLATE "POSIX"                            NOT NULL,
-    stream_name     character varying COLLATE "POSIX"                            NOT NULL,
-    stream_id       character varying COLLATE "POSIX"                            NOT NULL,
-    global_position bigserial                                                    NOT NULL,
-    stream_revision integer                                                      NOT NULL,
-    data            jsonb                       DEFAULT '{}'::jsonb              NOT NULL,
-    metadata        jsonb                       DEFAULT '{}'::jsonb              NOT NULL,
-    link_id         uuid,
-    created_at      timestamp without time zone DEFAULT now()                    NOT NULL,
-    type            character varying COLLATE "POSIX"                            NOT NULL
+    id                uuid                        DEFAULT public.gen_random_uuid() NOT NULL,
+    context           character varying COLLATE "POSIX"                            NOT NULL,
+    stream_name       character varying COLLATE "POSIX"                            NOT NULL,
+    stream_id         character varying COLLATE "POSIX"                            NOT NULL,
+    global_position   bigserial                                                    NOT NULL,
+    stream_revision   integer                                                      NOT NULL,
+    data              jsonb                       DEFAULT '{}'::jsonb              NOT NULL,
+    metadata          jsonb                       DEFAULT '{}'::jsonb              NOT NULL,
+    link_id           uuid,
+    link_partition_id bigint,
+    created_at        timestamp without time zone DEFAULT now()                    NOT NULL,
+    type              character varying COLLATE "POSIX"                            NOT NULL
 ) PARTITION BY LIST (context);
 
 ALTER TABLE ONLY public.events

data/db/migrations/2_create_subscriptions.sql

@@ -1,6 +1,6 @@
 CREATE TABLE public.subscriptions_set
 (
-    id                     uuid                                 DEFAULT public.gen_random_uuid() NOT NULL,
+    id                     bigserial                   NOT NULL,
     name                   character varying           NOT NULL,
     state                  character varying           NOT NULL DEFAULT 'initial',
     restart_count          integer                     NOT NULL DEFAULT 0,
@@ -35,7 +35,7 @@ CREATE TABLE public.subscriptions
     chunk_query_interval          float4                      NOT NULL DEFAULT 1.0,
     last_chunk_fed_at             timestamp without time zone NOT NULL DEFAULT to_timestamp(0),
     last_chunk_greatest_position  bigint,
-    locked_by                     uuid,
+    locked_by                     bigint,
     created_at                    timestamp without time zone NOT NULL DEFAULT now(),
     updated_at                    timestamp without time zone NOT NULL DEFAULT now()
 );
@@ -44,3 +44,7 @@ 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);
+CREATE INDEX idx_subscriptions_locked_by ON public.subscriptions USING btree (locked_by);
+
+ALTER TABLE ONLY public.subscriptions
+    ADD CONSTRAINT subscriptions_subscriptions_set_fk FOREIGN KEY (locked_by) REFERENCES public.subscriptions_set (id) ON DELETE SET NULL (locked_by);

data/db/migrations/3_create_subscription_commands.sql

@@ -1,15 +1,19 @@
 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()
+    id                   bigserial                   NOT NULL,
+    name                 character varying           NOT NULL,
+    subscription_id      bigint                      NOT NULL,
+    subscriptions_set_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);
+CREATE UNIQUE INDEX idx_subscription_commands_subscription_id_and_set_id_and_name ON public.subscription_commands USING btree (subscription_id, subscriptions_set_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;
+
+ALTER TABLE ONLY public.subscription_commands
+    ADD CONSTRAINT subscription_commands_subscriptions_set_fk FOREIGN KEY (subscriptions_set_id) REFERENCES public.subscriptions_set (id) ON DELETE CASCADE;

data/db/migrations/4_create_subscriptions_set_commands.sql

@@ -2,7 +2,7 @@ CREATE TABLE public.subscriptions_set_commands
 (
     id                   bigserial                   NOT NULL,
     name                 character varying           NOT NULL,
-    subscriptions_set_id uuid                        NOT NULL,
+    subscriptions_set_id bigint                      NOT NULL,
     created_at           timestamp without time zone NOT NULL DEFAULT now()
 );
 

data/db/migrations/5_partitions.sql

@@ -14,3 +14,4 @@ CREATE UNIQUE INDEX idx_partitions_by_context ON public.partitions USING btree (
 CREATE UNIQUE INDEX idx_partitions_by_context_and_stream_name ON public.partitions USING btree (context, stream_name) WHERE event_type IS NULL;
 CREATE UNIQUE INDEX idx_partitions_by_context_and_stream_name_and_event_type ON public.partitions USING btree (context, stream_name, event_type);
 CREATE UNIQUE INDEX idx_partitions_by_partition_table_name ON public.partitions USING btree (table_name);
+CREATE INDEX idx_partitions_by_event_type ON public.partitions USING btree (event_type);

data/docs/configuration.md

@@ -10,7 +10,7 @@ Configuration options:
 | 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         | Float   | `1.0`                                                        | How often to pull new subscription events in seconds.                                                                                                                                                                                                                                                                  |
+| subscription_pull_interval         | Float   | `1.0`                                                        | How often to pull new subscription events in seconds. The minimum meaningful value is `0.2`. Values less than `0.2` will act as it is `0.2`.                                                                                                                                                                           |
 | 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.                                                                                                                                                                                                                                                                    |

data/docs/how_it_works.md

@@ -8,7 +8,7 @@ The database is designed specifically for Eventsourcing using Domain-Driven Desi
 - For each `Stream#stream_name` there is a subpartition of `contexts_` table. Those tables have `stream_names_` prefix.
 - For each `Event#type` there is a subpartition of `stream_names_` table. Those tables have `event_types_` prefix.
 
-To implement partitions - Declarative Partitioning is used. Partitioning means that you should not have any random values in the combination of `Stream#context`, `Stream#stream_name` and `Event#type`. A combination of those values must have low cardinality(low distinct values number) and must be pre-defined in your application. Otherwise it will lead to the performance degradation. More about PostgreSQL partitions is [here](https://www.postgresql.org/docs/current/ddl-partitioning.html),
+To implement partitions - Declarative Partitioning is used. Partitioning means that you should not have any random values in the combination of `Stream#context`, `Stream#stream_name` and `Event#type`. A combination of those values must have low cardinality(low distinct values number) and must be pre-defined in your application. Otherwise it will lead to the performance degradation. More about PostgreSQL partitions is [here](https://www.postgresql.org/docs/current/ddl-partitioning.html).
 
 So, let's say you want to publish next event:
 
@@ -36,6 +36,19 @@ end.to_a
 #    {"id"=>3, "context"=>"SomeCtx", "stream_name"=>"SomeStream", "event_type"=>"SomethingChanged", "table_name"=>"event_types_aeadd5"}]
 ```
 
+### PostgreSQL settings
+
+The more partitions you have, the more locks are required for operations that affect multiple partitions. Especially it concerns the case when you are [reading events from "all" stream](reading_events.md#reading-from-the-all-stream) without providing any filters. It may lead to the next error:
+
+```
+ERROR:  out of shared memory (PG::OutOfMemory)
+HINT:  You might need to increase max_locks_per_transaction.
+```
+
+PostgreSQL suggests to increase the `max_locks_per_transaction`(the description of it is [here](https://www.postgresql.org/docs/current/runtime-config-locks.html)). The default value is `64`. The good value of this setting really depends on your queries, the number of concurrent transactions, the values of `shared_buffers` and `work_mem` settings. In case you have several thousands of partitions - you may want to set it to `128` or event to `256` from the start. On the other hand - you may want to increase it even earlier(e.g. when having several hundreds of partitions) in case you involve high number of partitions into a single transaction(for example, when using [#multiple](multiple_commands.md)).
+
+Conclusion: monitor db logs, monitor exceptions and adjust your db settings accordingly.
+
 ## Appending events and multiple commands
 
 You may want to get familiar with [Appending events](appending_events.md) and [multiple commands](multiple_commands.md) first.

data/lib/pg_eventstore/commands/append.rb

@@ -12,7 +12,7 @@ module PgEventstore
       # @param event_modifier [#call]
       # @return [Array<PgEventstore::Event>] persisted events
       # @raise [PgEventstore::WrongExpectedRevisionError]
-      def call(stream, *events, options: {}, event_modifier: EventModifiers::PrepareRegularEvent)
+      def call(stream, *events, options: {}, event_modifier: EventModifiers::PrepareRegularEvent.new)
         raise SystemStreamError, stream if stream.system?
 
         queries.transactions.transaction do

data/lib/pg_eventstore/commands/event_modifiers/prepare_link_event.rb

@@ -6,16 +6,38 @@ module PgEventstore
       # Defines how to transform regular event into a link event
       # @!visibility private
       class PrepareLinkEvent
-        class << self
-          # @param event [PgEventstore::Event]
-          # @param revision [Integer]
-          # @return [PgEventstore::Event]
-          def call(event, revision)
-            Event.new(link_id: event.id, type: Event::LINK_TYPE, stream_revision: revision).tap do |e|
-              %i[link_id type stream_revision].each { |attr| e.readonly!(attr) }
-            end
+        attr_reader :partition_queries, :partitions
+
+        # @param partition_queries [PgEventstore::PartitionQueries]
+        def initialize(partition_queries)
+          @partitions = {}
+          @partition_queries = partition_queries
+        end
+        # @param event [PgEventstore::Event]
+        # @param revision [Integer]
+        # @return [PgEventstore::Event]
+        def call(event, revision)
+          Event.new(
+            link_id: event.id, link_partition_id: partition_id(event), type: Event::LINK_TYPE, stream_revision: revision
+          ).tap do |e|
+            %i[link_id link_partition_id type stream_revision].each { |attr| e.readonly!(attr) }
           end
         end
+
+        private
+
+        # @param event [PgEventstore::Event] persisted event
+        # @return [Integer] partition id
+        # @raise [PgEventstore::MissingPartitionError]
+        def partition_id(event)
+          partition_id = @partitions.dig(event.stream.context, event.stream.stream_name, event.type)
+          return partition_id if partition_id
+
+          partition_id = partition_queries.event_type_partition(event.stream, event.type)['id']
+          @partitions[event.stream.context] ||= {}
+          @partitions[event.stream.context][event.stream.stream_name] ||= {}
+          @partitions[event.stream.context][event.stream.stream_name][event.type] = partition_id
+        end
       end
     end
   end

data/lib/pg_eventstore/commands/event_modifiers/prepare_regular_event.rb

@@ -6,16 +6,14 @@ module PgEventstore
       # Defines how to transform regular event before appending it to the stream
       # @!visibility private
       class PrepareRegularEvent
-        class << self
-          # @param event [PgEventstore::Event]
-          # @param revision [Integer]
-          # @return [PgEventstore::Event]
-          def call(event, revision)
-            event.class.new(
-              id: event.id, data: event.data, metadata: event.metadata, type: event.type, stream_revision: revision
-            ).tap do |e|
-              %i[link_id stream_revision].each { |attr| e.readonly!(attr) }
-            end
+        # @param event [PgEventstore::Event]
+        # @param revision [Integer]
+        # @return [PgEventstore::Event]
+        def call(event, revision)
+          event.class.new(
+            id: event.id, data: event.data, metadata: event.metadata, type: event.type, stream_revision: revision
+          ).tap do |e|
+            %i[link_id link_partition_id stream_revision].each { |attr| e.readonly!(attr) }
           end
         end
       end

data/lib/pg_eventstore/commands/link_to.rb

@@ -13,20 +13,27 @@ module PgEventstore
       # @raise [PgEventstore::WrongExpectedRevisionError]
       # @raise [PgEventstore::NotPersistedEventError]
       def call(stream, *events, options: {})
-        events.each(&method(:check_event_presence))
+        check_events_presence(events)
         append_cmd = Append.new(queries)
-        append_cmd.call(stream, *events, options: options, event_modifier: EventModifiers::PrepareLinkEvent)
+        append_cmd.call(
+          stream, *events, options: options, event_modifier: EventModifiers::PrepareLinkEvent.new(queries.partitions)
+        )
       end
 
       private
 
-      # Checks if Event#id is present. An event must have the #id value in order to be linked.
-      # @param event [PgEventstore::Event]
+      # Checks if the given events are persisted events. This is needed to prevent potentially non-existing id valuess
+      # from appearing in #link_id column.
+      # @param events [Array<PgEventstore::Event>]
       # @return [void]
-      def check_event_presence(event)
-        return if queries.events.event_exists?(event.id)
+      def check_events_presence(events)
+        ids_from_db = queries.events.ids_from_db(events)
+        (events.map(&:id) - ids_from_db).tap do |missing_ids|
+          return if missing_ids.empty?
 
-        raise NotPersistedEventError, event
+          missing_event = events.find { |event| event.id == missing_ids.first }
+          raise NotPersistedEventError, missing_event
+        end
       end
     end
   end

data/lib/pg_eventstore/errors.rb

@@ -139,7 +139,7 @@ module PgEventstore
 
     # @param set [String] subscriptions set name
     # @param name [String] subscription's name
-    # @param lock_id [String] UUIDv4
+    # @param lock_id [Integer]
     def initialize(set, name, lock_id)
       @set = set
       @name = name
@@ -151,31 +151,29 @@ module PgEventstore
     def user_friendly_message
       <<~TEXT.strip
         Could not lock subscription from #{set.inspect} set with #{name.inspect} name. It is already locked by \
-        #{lock_id.inspect} set.
+        ##{lock_id.inspect} set.
       TEXT
     end
   end
 
-  class SubscriptionUnlockError < Error
-    attr_reader :set, :name, :expected_locked_by, :actual_locked_by
+  class WrongLockIdError < Error
+    attr_reader :set, :name, :lock_id
 
-    # @param set [String] subscription's set name
+    # @param set [String] subscriptions set name
     # @param name [String] subscription's name
-    # @param expected_locked_by [String] UUIDv4
-    # @param actual_locked_by [String, nil] UUIDv4
-    def initialize(set, name, expected_locked_by, actual_locked_by)
+    # @param lock_id [Integer]
+    def initialize(set, name, lock_id)
       @set = set
       @name = name
-      @expected_locked_by = expected_locked_by
-      @actual_locked_by = actual_locked_by
+      @lock_id = lock_id
       super(user_friendly_message)
     end
 
     # @return [String]
     def user_friendly_message
       <<~TEXT.strip
-        Failed to unlock subscription from #{set.inspect} set with #{name.inspect} name by \
-        #{expected_locked_by.inspect} lock id. It is currently locked by #{actual_locked_by.inspect} lock id.
+        Could not update subscription from #{set.inspect} set with #{name.inspect} name. It is locked by \
+        ##{lock_id.inspect} set suddenly.
       TEXT
     end
   end

data/lib/pg_eventstore/event.rb

@@ -31,6 +31,14 @@ module PgEventstore
     #   @return [String, nil] UUIDv4 of an event the current event points to. If it is not nil, then the current
     #     event is a link
     attribute(:link_id)
+    # @!attribute link_partition_id
+    #   @return [Integer, nil] a partition id of an event the link event points to. It is used to load original event
+    #     when resolve_link_tos: true option is provided when reading events.
+    attribute(:link_partition_id)
+    # @!attribute link
+    #   @return [PgEventstore::Event, nil] when resolve_link_tos: true option is provided during the read of events and
+    #     event is a link event - this attribute will be pointing on that link
+    attribute(:link)
     # @!attribute created_at
     #   @return [Time, nil] a timestamp an event was created at
     attribute(:created_at)
@@ -41,7 +49,7 @@ module PgEventstore
     def ==(other)
       return false unless other.is_a?(PgEventstore::Event)
 
-      attributes_hash == other.attributes_hash
+      attributes_hash.except(:link) == other.attributes_hash.except(:link)
     end
 
     # Detect whether an event is a link event

data/lib/pg_eventstore/event_deserializer.rb

@@ -27,6 +27,7 @@ module PgEventstore
       event.stream = PgEventstore::Stream.new(
         **attrs.slice('context', 'stream_name', 'stream_id').transform_keys(&:to_sym)
       )
+      event.link = without_middlewares.deserialize(attrs['link']) if attrs.key?('link')
       event
     end
 

data/lib/pg_eventstore/queries/event_queries.rb

@@ -15,17 +15,36 @@ module PgEventstore
       @deserializer = deserializer
     end
 
-    # @param id [String, nil]
+    # @param event [PgEventstore::Event]
     # @return [Boolean]
-    def event_exists?(id)
-      return false if id.nil?
+    def event_exists?(event)
+      return false if event.id.nil? || event.stream.nil?
 
-      sql_builder = SQLBuilder.new.select('1 as exists').from('events').where('id = ?', id).limit(1)
+      sql_builder = SQLBuilder.new.select('1 as exists').from('events').where('id = ?', event.id).limit(1)
+      sql_builder.where(
+        'context = ? and stream_name = ? and type = ?', event.stream.context, event.stream.stream_name, event.type
+      )
       connection.with do |conn|
         conn.exec_params(*sql_builder.to_exec_params)
       end.to_a.dig(0, 'exists') == 1
     end
 
+    # Takes an array of potentially persisted events and loads their ids from db. Those ids can be later used to check
+    # whether events are actually existing events.
+    # @param events [Array<PgEventstore::Event>]
+    # @return [Array<Integer>]
+    def ids_from_db(events)
+      sql_builder = SQLBuilder.new.from('events').select('id')
+      partition_attrs = events.map { |event| [event.stream&.context, event.stream&.stream_name, event.type] }.uniq
+      partition_attrs.each do |context, stream_name, event_type|
+        sql_builder.where_or('context = ? and stream_name = ? and type = ?', context, stream_name, event_type)
+      end
+      sql_builder.where('id = ANY(?::uuid[])', events.map(&:id))
+      PgEventstore.connection.with do |conn|
+        conn.exec_params(*sql_builder.to_exec_params)
+      end.to_a.map { |attrs| attrs['id'] }
+    end
+
     # @param stream [PgEventstore::Stream]
     # @return [Integer, nil]
     def stream_revision(stream)
@@ -47,6 +66,7 @@ module PgEventstore
       raw_events = connection.with do |conn|
         conn.exec_params(*exec_params)
       end.to_a
+      raw_events = links_resolver.resolve(raw_events) if options[:resolve_link_tos]
       deserializer.deserialize_many(raw_events)
     end
 
@@ -55,7 +75,7 @@ module PgEventstore
     # @return [PgEventstore::Event]
     def insert(stream, events)
       sql_rows_for_insert, values = prepared_statements(stream, events)
-      columns = %w[id data metadata stream_revision link_id type context stream_name stream_id]
+      columns = %w[id data metadata stream_revision link_id link_partition_id type context stream_name stream_id]
 
       sql = <<~SQL
         INSERT INTO events (#{columns.join(', ')}) 
@@ -80,7 +100,9 @@ module PgEventstore
       values = []
       sql_rows_for_insert = events.map do |event|
         event = serializer.serialize(event)
-        attributes = event.options_hash.slice(:id, :data, :metadata, :stream_revision, :link_id, :type)
+        attributes = event.options_hash.slice(
+          :id, :data, :metadata, :stream_revision, :link_id, :link_partition_id, :type
+        )
 
         attributes = attributes.merge(stream.to_hash)
         prepared = attributes.values.map do |value|
@@ -106,5 +128,10 @@ module PgEventstore
 
       QueryBuilders::EventsFiltering.specific_stream_filtering(stream, options)
     end
+
+    # @return [PgEventstore::LinksResolver]
+    def links_resolver
+      LinksResolver.new(connection)
+    end
   end
 end

data/lib/pg_eventstore/queries/links_resolver.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  # @!visibility private
+  class LinksResolver
+    attr_reader :connection
+    private :connection
+
+    # @param connection [PgEventstore::Connection]
+    def initialize(connection)
+      @connection = connection
+    end
+
+    # Takes an array of events, look for link events in there and replaces link events with original events
+    # @param raw_events [Array<Hash>]
+    # @return [Array<Hash>]
+    def resolve(raw_events)
+      link_events = raw_events.select { _1['link_partition_id'] }.group_by { _1['link_partition_id'] }
+      return raw_events if link_events.empty?
+
+      original_events = load_original_events(link_events).to_h { |attrs| [attrs['id'], attrs] }
+      raw_events.map do |attrs|
+        original_event = original_events[attrs['link_id']]
+        next attrs unless original_event
+
+        original_event.merge('link' => attrs).merge(attrs.except(*original_event.keys))
+      end
+    end
+
+    private
+
+    # @param link_events [Hash{Integer => Array<Hash>}] partition id to link events association
+    # @return [Array<Hash>] original events
+    def load_original_events(link_events)
+      partitions = partition_queries.find_by_ids(link_events.keys)
+      sql_builders = partitions.map do |partition|
+        sql_builder = SQLBuilder.new.select('*').from(partition['table_name'])
+        sql_builder.where('id  = ANY(?::uuid[])', link_events[partition['id']].map { _1['link_id'] })
+      end
+      sql_builder = sql_builders[1..].each_with_object(sql_builders.first) do |builder, top_builder|
+        top_builder.union(builder)
+      end
+
+      connection.with do |conn|
+        conn.exec_params(*sql_builder.to_exec_params)
+      end.to_a
+    end
+
+    def partition_queries
+      PartitionQueries.new(connection)
+    end
+  end
+end

data/lib/pg_eventstore/queries/partition_queries.rb

@@ -165,6 +165,14 @@ module PgEventstore
       end.to_a.dig(0, 'exists') == 1
     end
 
+    # @param ids [Array<Integer>]
+    # @return [Array<Hash>]
+    def find_by_ids(ids)
+      connection.with do |conn|
+        conn.exec_params('select * from partitions where id = ANY($1::bigint[])', [ids])
+      end.to_a
+    end
+
     # @param stream [PgEventstore::Stream]
     # @return [String]
     def context_partition_name(stream)

data/lib/pg_eventstore/queries/subscription_command_queries.rb

@@ -11,15 +11,27 @@ module PgEventstore
       @connection = connection
     end
 
+    # @see #find_by or #create for available arguments
+    # @return [Hash]
+    def find_or_create_by(...)
+      transaction_queries.transaction do
+        find_by(...) || create(...)
+      end
+    end
+
     # @param subscription_id [Integer]
+    # @param subscriptions_set_id [Integer]
     # @param command_name [String]
     # @return [Hash, nil]
-    def find_by(subscription_id:, command_name:)
+    def find_by(subscription_id:, subscriptions_set_id:, command_name:)
       sql_builder =
         SQLBuilder.new.
           select('*').
           from('subscription_commands').
-          where('subscription_id = ? AND name = ?', subscription_id, command_name)
+          where(
+            'subscription_id = ? AND subscriptions_set_id = ? AND name = ?',
+            subscription_id, subscriptions_set_id, command_name
+          )
       pg_result = connection.with do |conn|
         conn.exec_params(*sql_builder.to_exec_params)
       end
@@ -29,23 +41,25 @@ module PgEventstore
     end
 
     # @param subscription_id [Integer]
+    # @param subscriptions_set_id [Integer]
     # @param command_name [String]
     # @return [Hash]
-    def create_by(subscription_id:, command_name:)
+    def create(subscription_id:, subscriptions_set_id:, command_name:)
       sql = <<~SQL
-        INSERT INTO subscription_commands (name, subscription_id) 
-          VALUES ($1, $2)
+        INSERT INTO subscription_commands (name, subscription_id, subscriptions_set_id) 
+          VALUES ($1, $2, $3)
           RETURNING *
       SQL
       pg_result = connection.with do |conn|
-        conn.exec_params(sql, [command_name, subscription_id])
+        conn.exec_params(sql, [command_name, subscription_id, subscriptions_set_id])
       end
       deserialize(pg_result.to_a.first)
     end
 
     # @param subscription_ids [Array<Integer>]
+    # @param subscriptions_set_id [Integer]
     # @return [Array<Hash>]
-    def find_commands(subscription_ids)
+    def find_commands(subscription_ids, subscriptions_set_id:)
       return [] if subscription_ids.empty?
 
       sql = subscription_ids.size.times.map do
@@ -55,6 +69,7 @@ module PgEventstore
         SQLBuilder.new.select('*').
           from('subscription_commands').
           where("subscription_id IN (#{sql})", *subscription_ids).
+          where("subscriptions_set_id = ?", subscriptions_set_id).
           order('id ASC')
       pg_result = connection.with do |conn|
         conn.exec_params(*sql_builder.to_exec_params)
@@ -72,6 +87,11 @@ module PgEventstore
 
     private
 
+    # @return [PgEventstore::TransactionQueries]
+    def transaction_queries
+      TransactionQueries.new(connection)
+    end
+
     # @param hash [Hash]
     # @return [Hash]
     def deserialize(hash)