pgoutput-client 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4b5412d12b81f8e787d00975419c7478af45fb47d0fa0f616876a9141f47396
-  data.tar.gz: 9a77f1cbb0c438312fdefa4045f89f2359829751a96e6131f20ffc9ce4ccc6b2
+  metadata.gz: e4f6889c573693726868891513ab942b96ea305cef6c70407216a0fdf9046a32
+  data.tar.gz: 6ae8423d421ba51472c3f777451bc970f986c2b2b52c9cf6a234f97491c0ea70
 SHA512:
-  metadata.gz: e067f71e70ade6f7cf25d543edbfac7f79058e6a8b79a35457a6320365e574d7c8c12ecbdecd74355eff1aa641eabde1c926e74dc52513e7a1ad101461a7375d
-  data.tar.gz: e66ed2183b869dc7074595fc2509763d5da468ddd7f21a5ed10617990405da21b720df5131de01771beaed5532970073eed56bbbd1517a40bb271019b34f8af9
+  metadata.gz: 57d9bdda60c19cfc8c09e403d998af9f26bfcdf9ddb6dd81874f22142c00b8fd1e20cea7120fcbc7484886490870f1c3efe4fcab20a0e0a52283a2d456332977
+  data.tar.gz: 2840604c443d755c6850154284dfe412d60821adac80428b76fa3569f8db986109ee0457a695938b6e051f224e1b5bb69923cea13934a95184836595bfad6b4f

data/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 ## Unreleased
 
+## 0.2.4 - 2026-06-17
+
+### Added
+
+- Added socket-aware replication stream polling.
+- Added E2E coverage for PostgreSQL restart and replication stream recovery.
+- Added connection readiness checks to E2E infrastructure.
+
+### Changed
+
+- Improved replication stream handling during idle periods.
+- Improved reconnect behavior after PostgreSQL restarts.
+- Improved standby feedback reliability during long-running streams.
+- Improved E2E test stability across PostgreSQL startup and restart scenarios.
+- Normalized `PG#get_copy_data` idle responses to simplify stream processing.
+
+### Fixed
+
+- Fixed replication stream recovery after PostgreSQL restart.
+- Fixed handling of idle COPY stream reads.
+- Fixed reconnect loops triggered by PostgreSQL replication timeouts.
+- Fixed E2E race conditions during PostgreSQL initialization.
+- Fixed replication slot creation behavior when a slot already exists.
+- Fixed several edge cases uncovered by Mammoth integration testing.
+
+### Documentation
+
+- Expanded YARD documentation coverage to 98.95%.
+
+## 0.2.3 - 2026-06-17
+
+### Fixed
+
+* Fixed automatic replication slot creation when `auto_create_slot` is enabled.
+* Fixed startup failure when the configured replication slot already exists.
+* Improved logical replication restart behavior for persistent replication slots.
+* Improved lifecycle management of existing replication slots across process and container restarts.
+
+### Changed
+
+* `auto_create_slot` now follows **ensure slot exists** semantics.
+* Existing replication slots are treated as valid and reusable when automatic slot creation is enabled.
+* Slot creation remains automatic for missing slots and idempotent for existing slots.
+
+### Internal
+
+* Hardened replication slot lifecycle handling.
+* Expanded coverage around automatic slot creation scenarios.
+* Updated signatures and tests for slot creation behavior.
+
+
 ## 0.2.2 - 2026-06-17
 
 ### Added

data/README.md

@@ -363,6 +363,57 @@ Equivalent Rake task:
 bundle exec rake e2e:run
 ```
 
+## Transport lifecycle behavior
+
+`pgoutput-client` owns PostgreSQL logical replication transport and lifecycle
+management. It opens the replication connection, optionally creates the logical
+replication slot, starts streaming, sends standby status feedback, and retries
+reconnectable failures.
+
+### Idle standby feedback
+
+Long-running replication streams can be quiet for long periods when no WAL
+changes are produced. During those idle periods the client wakes periodically
+and sends standby status feedback so PostgreSQL does not terminate the walsender
+for replication timeout.
+
+Control the feedback cadence with `feedback_interval`:
+
+```ruby
+runner = Pgoutput::Client::Runner.new(
+  database_url: ENV.fetch("DATABASE_URL"),
+  slot_name: "mammoth_live",
+  publication_names: ["mammoth_publication"],
+  feedback_interval: 10.0
+)
+```
+
+### Idempotent automatic slot creation
+
+When `auto_create_slot` is enabled, the client treats slot creation as
+"ensure this slot exists". Missing slots are created before streaming; existing
+slots are reused and do not cause startup failure.
+
+```ruby
+runner = Pgoutput::Client::Runner.new(
+  database_url: ENV.fetch("DATABASE_URL"),
+  slot_name: "mammoth_live",
+  publication_names: ["mammoth_publication"],
+  auto_create_slot: true,
+  temporary_slot: false
+)
+```
+
+Publication creation remains outside this gem. Create publications through
+application migrations, database bootstrap SQL, or infrastructure tooling.
+
+### Restart recovery
+
+After a stream has connected successfully, transient PostgreSQL outages are
+retried through the reconnect lifecycle. This includes ordinary container or
+process restart windows where PostgreSQL temporarily refuses connections or
+reports that the database system is starting up.
+
 ---
 
 ## License

data/lib/pgoutput/client/connection.rb

@@ -76,14 +76,19 @@ module Pgoutput
 
       # Receive one CopyData payload from the server.
       #
-      # The call is non-blocking because the underlying `pg` call receives
-      # `false` for its blocking argument. `nil` means no complete CopyData
-      # payload is currently available.
+      # The stream must not block forever while PostgreSQL is idle, because the
+      # caller needs opportunities to send periodic standby feedback. Wait
+      # briefly for socket readability, then use the pg driver's blocking
+      # CopyData read only when data is available. `nil` means the stream is
+      # currently idle.
       #
       # @return [String, nil] raw CopyData payload or `nil`
       # @raise [ConnectionError] if receiving fails
       def get_copy_data # rubocop:disable Naming/AccessorMethodName
-        @pg_connection.get_copy_data(false)
+        return nil unless copy_data_readable?
+
+        copy_data = @pg_connection.get_copy_data(false)
+        copy_data == false ? nil : copy_data
       rescue PG::Error => e
         raise ConnectionError, e.message
       end
@@ -110,6 +115,15 @@ module Pgoutput
 
       private
 
+      def copy_data_readable?
+        return true unless @pg_connection.respond_to?(:socket_io)
+
+        socket = @pg_connection.socket_io
+        return true unless socket
+
+        !!IO.select([socket], nil, nil, 0.1)
+      end
+
       def exec(sql)
         @pg_connection.exec(sql)
       rescue PG::Error => e

data/lib/pgoutput/client/feedback.rb

@@ -2,6 +2,9 @@
 
 module Pgoutput
   module Client
+    # Internal immutable base class generated by `Data.define` for {Feedback}.
+    #
+    # @api private
     FeedbackData = Data.define(:received_lsn, :flushed_lsn, :applied_lsn, :client_clock, :reply_requested)
 
     # Standby status feedback message builder.

data/lib/pgoutput/client/keepalive.rb

@@ -2,6 +2,9 @@
 
 module Pgoutput
   module Client
+    # Internal immutable base class generated by `Data.define` for {Keepalive}.
+    #
+    # @api private
     KeepaliveData = Data.define(:wal_end, :server_clock, :reply_requested)
 
     # Immutable primary keepalive replication message.

data/lib/pgoutput/client/runner.rb

@@ -37,7 +37,17 @@ module Pgoutput
     # @see Stream
     # @api public
     class Runner
+      # Default number of reconnect attempts after a previously healthy stream
+      # fails. The default is intentionally large enough to survive ordinary
+      # PostgreSQL restart windows.
+      #
+      # @return [Integer]
       DEFAULT_RECONNECT_ATTEMPTS = 30
+
+      # Base reconnect backoff, in seconds. Attempt `n` sleeps for
+      # `n * DEFAULT_RECONNECT_BACKOFF`.
+      #
+      # @return [Float]
       DEFAULT_RECONNECT_BACKOFF = 0.5
 
       # Configuration used by this runner.
@@ -194,14 +204,24 @@ module Pgoutput
       private
 
       def setup_connection(connection)
-        if configuration.auto_create_slot && !@slot_created
-          connection.create_replication_slot
-          @slot_created = true
-        end
+        ensure_replication_slot(connection) if configuration.auto_create_slot && !@slot_created
 
         connection.start_replication
       end
 
+      def ensure_replication_slot(connection)
+        connection.create_replication_slot
+        @slot_created = true
+      rescue ConnectionError => e
+        raise unless replication_slot_already_exists?(e)
+
+        @slot_created = true
+      end
+
+      def replication_slot_already_exists?(error)
+        error.message.match?(/replication slot .* already exists/i)
+      end
+
       def run_stream_cycle(configuration, &block)
         connection = Connection.open(configuration)
         setup_connection(connection)

data/lib/pgoutput/client/state.rb

@@ -2,6 +2,9 @@
 
 module Pgoutput
   module Client
+    # Internal immutable base class generated by `Data.define` for {RunnerState}.
+    #
+    # @api private
     RunnerStateData = Data.define(
       :running,
       :stop_requested,

data/lib/pgoutput/client/version.rb

@@ -5,6 +5,6 @@ module Pgoutput
     # Current pgoutput-client gem version.
     #
     # @return [String]
-    VERSION = "0.2.2"
+    VERSION = "0.2.4"
   end
 end

data/lib/pgoutput/client/xlog_data.rb

@@ -2,6 +2,9 @@
 
 module Pgoutput
   module Client
+    # Internal immutable base class generated by `Data.define` for {XLogData}.
+    #
+    # @api private
     ReplicationXLogData = Data.define(:wal_start, :wal_end, :server_clock, :payload)
 
     # Immutable XLogData replication envelope.

data/lib/pgoutput/client.rb

@@ -13,6 +13,13 @@ require_relative "client/connection"
 require_relative "client/stream"
 require_relative "client/runner"
 
+# Namespace for PostgreSQL pgoutput logical replication components.
+#
+# The top-level namespace is shared by pgoutput ecosystem gems. This gem
+# defines only the `Pgoutput::Client` transport namespace and leaves protocol
+# parsing, value decoding, and CDC normalization to sibling libraries.
+#
+# @api public
 module Pgoutput
   # Namespace for PostgreSQL logical replication transport support.
   #

data/sig/pgoutput/client/connection.rbs

@@ -61,9 +61,11 @@ module Pgoutput
 
       # Receive one CopyData payload from the server.
       #
-      # The call is non-blocking because the underlying `pg` call receives
-      # `false` for its blocking argument. `nil` means no complete CopyData
-      # payload is currently available.
+      # The stream must not block forever while PostgreSQL is idle, because the
+      # caller needs opportunities to send periodic standby feedback. Wait
+      # briefly for socket readability, then use the pg driver's blocking
+      # CopyData read only when data is available. `nil` means the stream is
+      # currently idle.
       #
       # @return [String, nil] raw CopyData payload or `nil`
       # @raise [ConnectionError] if receiving fails
@@ -85,6 +87,8 @@ module Pgoutput
 
       private
 
+      def copy_data_readable?: () -> bool
+
       def exec: (untyped sql) -> untyped
     end
   end

data/sig/pgoutput/client/runner.rbs

@@ -83,6 +83,10 @@ module Pgoutput
 
       def setup_connection: (untyped connection) -> untyped
 
+      def ensure_replication_slot: (untyped connection) -> untyped
+
+      def replication_slot_already_exists?: (untyped error) -> bool
+
       def run_stream_cycle: (untyped configuration) { (?) -> untyped } -> untyped
 
       def configuration_for_resume: () -> untyped

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgoutput-client
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Ken C. Demanawa