pgoutput-source-adapter 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96f17f6324e61545be066327df21f021a9b00a1c8a77f5868d74f87ec716e5f2
-  data.tar.gz: e56b9ff8c51ca0952acf5ce00663c9fd406caf9a1e1c9439f6f58caf19c28d41
+  metadata.gz: 96fa814d19258cf12c3f2d6398f72f21f1a2dfab59e89562b880f26fbb7bf1cd
+  data.tar.gz: 300f6a751391ee90ba84dfdbe743839e605fb6655aafc5057f9b87a1e25c3faf
 SHA512:
-  metadata.gz: 8c4868ad4effe15ace70dae52991e7c45f64116cbe6ea613df77d494bdfd9486a9bbcbcabcd31873d5e474655edfde50588563e498f2a11ef0e9bf9d8ab1e76e
-  data.tar.gz: de92c820e593d5d5f05e41885f002333df1aa0d16d00af1f5c4d5f05df8f8655571d8261cf05192a7807830d263db65e6e94908af61c786efd9b1a2a01053443
+  metadata.gz: 314c92d8ec4d3853056f4c69d99eefb6794aaefbc58a1b5f9e0b2de25c372cce1e8c4864210ade04400d23feb60fc47d68d535c1df901d7ef60a373bc4c735b8
+  data.tar.gz: 88c5f21bc01667b196a1b347e176cca6aa7caa655a058fa1550bdee3bcb3b88c511fd9371225f5a95fe585dac572a219b46a14a7135e956c97ac47fd8466e986

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-17
+
+### Added
+
+- Added `ReplicaIdentityResolver` for schema-aware non-`id` and composite keys,
+  keyed by relation id, schema/table pair, or qualified relation name.
+- Added default extraction from decoded relation key-column metadata when
+  events expose replica-identity columns or flagged relation columns.
+
+### Fixed
+
+- Preserved complete composite and non-`id` old-key tuples for normalized
+  UPDATE and DELETE events.
+- Fail closed when configured replica-key columns are absent instead of
+  emitting an incomplete `ChangeEvent#primary_key`.
+
+### Documentation
+
+- Documented relation metadata, schema-aware resolver configuration, and the
+  legacy `id` compatibility fallback.
+
 ## [0.2.0] - 2026-07-17
 
 ### Added

data/README.md

@@ -107,18 +107,35 @@ normalization path for finite batches.
 
 ## Primary keys
 
-For update and delete events, pgoutput may provide an old-key tuple. When it does, that tuple is used as the `CDC::Core::ChangeEvent#primary_key`.
+For update and delete events, pgoutput may provide an old-key tuple. When it
+does, the complete tuple is used as `CDC::Core::ChangeEvent#primary_key`,
+including composite and non-`id` replica keys.
 
-For insert events, or for sources without old-key tuples, the adapter defaults to `id` / `"id"` when present.
+For inserts and events without an old-key tuple, the default resolver uses
+relation key-column metadata when the decoded event exposes
+`replica_identity_columns`, `key_columns`, or a relation whose column flags mark
+replica-key columns. The adapter extracts every declared column and raises
+`Pgoutput::SourceAdapter::Error` rather than returning a partial key.
 
-You can provide your own resolver:
+When decoded events do not carry relation key metadata, configure the reusable
+schema-aware resolver. Relations may be keyed by relation id,
+`[schema, table]`, or a qualified name:
 
 ```ruby
+resolver = Pgoutput::SourceAdapter::ReplicaIdentityResolver.new(
+  ["public", "memberships"] => ["tenant_id", "member_uuid"],
+  "public.accounts" => ["account_uuid"]
+)
+
 adapter = Pgoutput::SourceAdapter::Cdc.new(
-  primary_key_resolver: ->(_event, values) { { "uuid" => values.fetch("uuid") } }
+  primary_key_resolver: resolver
 )
 ```
 
+The legacy `id` / `"id"` inference remains as a compatibility fallback only
+when neither relation metadata nor an explicit resolver is available. Custom
+callables remain supported through `primary_key_resolver:`.
+
 ## Metadata
 
 Each normalized event includes pgoutput metadata:
@@ -144,6 +161,7 @@ adapter = Pgoutput::SourceAdapter::Cdc.new(
 ```ruby
 Pgoutput::SourceAdapter
 Pgoutput::SourceAdapter::Cdc
+Pgoutput::SourceAdapter::ReplicaIdentityResolver
 ```
 
 A compatibility alias is also provided for the generated gem path:

data/lib/pgoutput/source_adapter/cdc.rb

@@ -274,7 +274,9 @@ module Pgoutput
         [input, nil]
       end
 
-      def default_primary_key(_event, values)
+      def default_primary_key(event, values)
+        key_columns = replica_identity_columns_for(event)
+        return key_from_columns(event, values, key_columns) unless key_columns.nil?
         return nil unless values.respond_to?(:key?)
 
         if values.key?('id')
@@ -284,6 +286,27 @@ module Pgoutput
         end
       end
 
+      def replica_identity_columns_for(event)
+        return normalize_key_columns(event.replica_identity_columns) if event.respond_to?(:replica_identity_columns)
+        return normalize_key_columns(event.key_columns) if event.respond_to?(:key_columns)
+        return unless event.respond_to?(:relation) && event.relation.respond_to?(:columns)
+
+        normalize_key_columns(
+          event.relation.columns.select { |column| column.flags.allbits?(1) }.map(&:name)
+        )
+      end
+
+      def normalize_key_columns(columns)
+        column_list = Array(columns) # : Array[untyped]
+        column_list.map(&:to_s)
+      end
+
+      def key_from_columns(event, values, columns)
+        return nil if columns.empty?
+
+        ReplicaIdentityResolver.extract(event, values, columns)
+      end
+
       def metadata_for(event)
         metadata = {
           'source' => SOURCE_NAME,

data/lib/pgoutput/source_adapter/replica_identity_resolver.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Pgoutput
+  module SourceAdapter
+    # Resolves schema-aware replica keys from decoded row values.
+    #
+    # Relations may be keyed by pgoutput relation id, `[schema, table]`, or a
+    # `"schema.table"` string. Each value is the ordered list of replica-key
+    # columns. Relation-id mappings take precedence because they identify the
+    # exact relation metadata seen by the replication stream.
+    #
+    # @example Resolve a composite key
+    #   resolver = ReplicaIdentityResolver.new(
+    #     ["public", "memberships"] => ["tenant_id", "member_uuid"]
+    #   )
+    #
+    # @api public
+    class ReplicaIdentityResolver
+      # Normalized relation keys mapped to ordered replica-identity columns.
+      #
+      # @return [Hash]
+      attr_reader :relations
+
+      # Extract a complete replica key from an ordered column list.
+      #
+      # @param event [Object] decoded row event with schema/table metadata
+      # @param values [Hash, nil] decoded row values
+      # @param columns [Array<String>] ordered replica-key column names
+      # @return [Hash{String=>Object}] complete replica key
+      # @raise [Error] when values or any configured column are unavailable
+      def self.extract(event, values, columns)
+        unless values.respond_to?(:key?)
+          raise Error, "replica identity values are unavailable for #{qualified_name(event)}"
+        end
+
+        columns.to_h do |column|
+          [column, fetch_column(event, values, column)]
+        end
+      end
+
+      # @param relations [Hash{Integer, Array<String>, Array<String>=>Array<String>}]
+      #   relation identity to ordered replica-key column names
+      # @return [void]
+      def initialize(relations)
+        @relations = relations.to_h.transform_values { |columns| normalize_columns(columns) }.freeze
+        freeze
+      end
+
+      # Extract the configured replica key for a decoded row event.
+      #
+      # @param event [Object] decoded row event with relation/schema/table metadata
+      # @param values [Hash, nil] decoded row values
+      # @return [Hash{String=>Object}, nil] complete replica key, or `nil` when
+      #   the relation is not configured
+      # @raise [Error] when a configured key column is absent from row values
+      def call(event, values)
+        columns = columns_for(event)
+        return nil unless columns
+
+        self.class.extract(event, values, columns)
+      end
+
+      def self.fetch_column(event, values, column)
+        return values[column] if values.key?(column)
+
+        symbol = column.to_sym
+        return values[symbol] if values.key?(symbol)
+
+        raise Error, "replica identity column #{column.inspect} is missing from #{qualified_name(event)} values"
+      end
+      private_class_method :fetch_column
+
+      def self.qualified_name(event)
+        [event.schema, event.table].compact.join('.')
+      end
+      private_class_method :qualified_name
+
+      private
+
+      def normalize_columns(columns)
+        column_list = Array(columns) # : Array[untyped]
+        names = column_list.map(&:to_s)
+        raise ArgumentError, 'replica identity columns must not be empty' if names.empty?
+        raise ArgumentError, 'replica identity columns must be unique' unless names.uniq.length == names.length
+
+        names.freeze
+      end
+
+      def columns_for(event)
+        relation_id = event.relation_id if event.respond_to?(:relation_id)
+        return relations[relation_id] if relation_id && relations.key?(relation_id)
+
+        schema = event.schema
+        table = event.table
+        relations[[schema.to_s, table.to_s]] || relations["#{schema}.#{table}"]
+      end
+    end
+  end
+end

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.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/pgoutput/source_adapter.rb

@@ -24,4 +24,5 @@ module Pgoutput
   end
 end
 
+require_relative 'source_adapter/replica_identity_resolver'
 require_relative 'source_adapter/cdc'

data/sig/pgoutput/source_adapter/cdc.rbs

@@ -80,7 +80,13 @@ module Pgoutput
 
       def stream_input: (untyped input) -> [untyped, untyped]
 
-      def default_primary_key: (untyped _event, untyped values) -> (nil | untyped)
+      def default_primary_key: (untyped event, untyped values) -> (nil | untyped)
+
+      def replica_identity_columns_for: (untyped event) -> untyped
+
+      def normalize_key_columns: (untyped columns) -> Array[String]
+
+      def key_from_columns: (untyped event, untyped values, Array[String] columns) -> untyped
 
       def metadata_for: (untyped event) -> untyped
 

data/sig/pgoutput/source_adapter/replica_identity_resolver.rbs

@@ -0,0 +1,20 @@
+module Pgoutput
+  module SourceAdapter
+    class ReplicaIdentityResolver
+      @relations: untyped
+
+      attr_reader relations: untyped
+
+      def self.extract: (untyped event, untyped values, Array[String] columns) -> Hash[String, untyped]
+      def initialize: (untyped relations) -> void
+      def call: (untyped event, untyped values) -> untyped
+
+      private
+
+      def self.fetch_column: (untyped event, untyped values, String column) -> untyped
+      def self.qualified_name: (untyped event) -> String
+      def normalize_columns: (untyped columns) -> Array[String]
+      def columns_for: (untyped event) -> untyped
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgoutput-source-adapter
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -64,11 +64,13 @@ files:
 - lib/pgoutput/source/adapter.rb
 - lib/pgoutput/source_adapter.rb
 - lib/pgoutput/source_adapter/cdc.rb
+- lib/pgoutput/source_adapter/replica_identity_resolver.rb
 - lib/pgoutput/source_adapter/version.rb
 - mise.toml
 - sig/pgoutput/source/adapter.rbs
 - sig/pgoutput/source_adapter.rbs
 - sig/pgoutput/source_adapter/cdc.rbs
+- sig/pgoutput/source_adapter/replica_identity_resolver.rbs
 - sig/pgoutput/source_adapter/version.rbs
 homepage: https://github.com/kanutocd/pgoutput-source-adapter
 licenses: