pgoutput-source-adapter 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96fa814d19258cf12c3f2d6398f72f21f1a2dfab59e89562b880f26fbb7bf1cd
-  data.tar.gz: 300f6a751391ee90ba84dfdbe743839e605fb6655aafc5057f9b87a1e25c3faf
+  metadata.gz: 025fc15b43b2a30151173ec6279c863a5ba458efb9d9da71e5ecd96905be6792
+  data.tar.gz: 265309ad03d49658717d8f147a01c8833baa87e22283d0cab8a3adae3d2f03fa
 SHA512:
-  metadata.gz: 314c92d8ec4d3853056f4c69d99eefb6794aaefbc58a1b5f9e0b2de25c372cce1e8c4864210ade04400d23feb60fc47d68d535c1df901d7ef60a373bc4c735b8
-  data.tar.gz: 88c5f21bc01667b196a1b347e176cca6aa7caa655a058fa1550bdee3bcb3b88c511fd9371225f5a95fe585dac572a219b46a14a7135e956c97ac47fd8466e986
+  metadata.gz: ddb9db7349022b0843871b4a23aebb8399ea3ba74820651f4de44e58b5fd0d5d7f89ab69ee2af64fe3f048c097defa3f2247d910254f75f0fa956d286436d8d5
+  data.tar.gz: 3f16c11504e312e0c6a771af39991b456f8128ed197dfce608ca28f027f1dd5ddc5722175244ef889fd2bba36b0429ef811b450cfe8ada6e3697ccf6978bbcff

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.3.1] - 2026-07-19
+
+### Fixed
+
+- Assign stable, zero-based `ChangeEvent#sequence_number` values to row events
+  within each transaction so otherwise identical changes remain distinct.
+
+### Quality
+
+- Added coverage for identical-event uniqueness, replay determinism, and
+  sequence reset between transactions.
+
+### Documentation
+
+- Documented transaction-local sequence-number semantics for downstream
+  deterministic event IDs.
+
 ## [0.3.0] - 2026-07-17
 
 ### Added

data/README.md

@@ -105,6 +105,13 @@ transaction are yielded immediately; changes between `Begin` and `Commit` are
 yielded as a `CDC::Core::TransactionEnvelope`. `normalize_many` uses the same
 normalization path for finite batches.
 
+Each change inside a transaction receives a stable, zero-based
+`sequence_number`. The ordinal follows decoded row-event order, resets at each
+`Begin`, and is reproduced when the same transaction input is replayed. Changes
+normalized outside transaction boundaries retain a `nil` sequence number.
+Downstream consumers can include this discriminator in deterministic event IDs
+so otherwise identical changes in the same transaction remain distinct.
+
 ## Primary keys
 
 For update and delete events, pgoutput may provide an old-key tuple. When it

data/lib/pgoutput/source_adapter/cdc.rb

@@ -83,12 +83,14 @@ module Pgoutput
       # envelopes are desired.
       #
       # @param event [Object] a Pgoutput::Decoder::Events object.
+      # @param sequence_number [Integer, nil] stable zero-based ordinal within
+      #   the event's transaction.
       # @return [CDC::Core::ChangeEvent, nil] normalized row change event, or
       #   nil for transaction boundary events.
       # @raise [Pgoutput::SourceAdapter::Error] when the decoded event type is
       #   unsupported.
       # rubocop:disable Metrics/MethodLength
-      def normalize(event, source_position: nil)
+      def normalize(event, source_position: nil, sequence_number: nil)
         case event_name(event)
         when 'Insert'
           change_event(
@@ -97,7 +99,8 @@ module Pgoutput
             old_values: nil,
             new_values: event.values,
             primary_key: primary_key_for(event, event.values),
-            source_position: source_position
+            source_position: source_position,
+            sequence_number: sequence_number
           )
         when 'Update'
           old_values = event.old_values || event.old_key
@@ -108,7 +111,8 @@ module Pgoutput
             old_values: old_values,
             new_values: event.new_values,
             primary_key: primary_key_for(event, event.new_values),
-            source_position: source_position
+            source_position: source_position,
+            sequence_number: sequence_number
           )
         when 'Delete'
           old_values = event.old_values || event.old_key
@@ -119,7 +123,8 @@ module Pgoutput
             old_values: old_values,
             new_values: nil,
             primary_key: primary_key_for(event, old_values),
-            source_position: source_position
+            source_position: source_position,
+            sequence_number: sequence_number
           )
         when 'Begin', 'Commit'
           nil
@@ -212,7 +217,12 @@ module Pgoutput
             transaction_events = []
             transaction_metadata = {}
           else
-            normalized = normalize(event, source_position: source_position)
+            normalized = if transaction_id
+                           normalize(event, source_position: source_position,
+                                            sequence_number: transaction_events.length)
+                         else
+                           normalize(event, source_position: source_position)
+                         end
             next if normalized.nil?
 
             if transaction_id
@@ -231,7 +241,8 @@ module Pgoutput
       # rubocop:enable Metrics/CyclomaticComplexity
       # rubocop:enable Metrics/MethodLength
 
-      def change_event(event, operation:, old_values:, new_values:, primary_key:, source_position:)
+      def change_event(event, operation:, old_values:, new_values:, primary_key:, source_position:,
+                       sequence_number:)
         share(
           CDC::Core::ChangeEvent.new(
             operation: operation,
@@ -242,6 +253,7 @@ module Pgoutput
             primary_key: primary_key,
             transaction_id: event.transaction_id,
             commit_lsn: lsn_string(source_position),
+            sequence_number: sequence_number,
             metadata: metadata_for(event)
           )
         )

data/lib/pgoutput/source_adapter/version.rb

@@ -5,6 +5,6 @@ module Pgoutput
     # Current pgoutput-source-adapter gem version.
     #
     # @return [String] semantic version published to RubyGems.
-    VERSION = '0.3.0'
+    VERSION = '0.3.1'
   end
 end

data/sig/pgoutput/source_adapter/cdc.rbs

@@ -46,7 +46,7 @@ module Pgoutput
       #
       # @param event [Object] a Pgoutput::Decoder::Events object.
       # @return [CDC::Core::ChangeEvent, nil]
-      def normalize: (untyped event, ?source_position: untyped) -> untyped
+      def normalize: (untyped event, ?source_position: untyped, ?sequence_number: Integer?) -> untyped
 
       # Pair a decoded event with its transport-level source position.
       def stream_event: (untyped event, ?source_position: untyped) -> StreamEvent
@@ -72,7 +72,7 @@ module Pgoutput
 
       def normalize_stream: (untyped events, flush_incomplete: bool) { (untyped work) -> untyped } -> void
 
-      def change_event: (untyped event, operation: untyped, old_values: untyped, new_values: untyped, primary_key: untyped, source_position: untyped) -> untyped
+      def change_event: (untyped event, operation: untyped, old_values: untyped, new_values: untyped, primary_key: untyped, source_position: untyped, sequence_number: Integer?) -> untyped
 
       def transaction_envelope: (untyped event, transaction_id: untyped, events: untyped, metadata: untyped, ?source_position: untyped) -> untyped
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgoutput-source-adapter
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Ken C. Demanawa