hecks 2.8.0 → 3.0.0

data/lib/hecks/adapters/driven/postgres/codec.rb

@@ -3,15 +3,8 @@ require_relative "../../../runtime/value"
 module Hecks
   module Adapters
     class Postgres
-      # How a state crosses the column boundary: which fields persist, and
-      # how each one encodes into (and decodes out of) its column. Same
-      # shape as Sqlite::Codec (one column per attribute, JSON for
-      # nested/list) — not its mechanics. Sqlite's own columns carry no
-      # type affinity worth trusting on the way back out (SQLite gives it
-      # back typed anyway via the driver), but `pg` hands every column
-      # back as text unless a type map says otherwise, so a real `bigint`/
-      # `double precision` column needs its own coercion on decode that
-      # Sqlite never had to write.
+      # Encodes and decodes a state to and from its columns, coercing `pg`'s text back to
+      # numbers.
       module Codec
         private
 
@@ -23,9 +16,7 @@ module Hecks
           fields << { name: lifecycle.field, attribute: nil, sql_type: "text" } if lifecycle && fields.none? do |field|
             field[:name] == lifecycle.field
           end
-          # `projects` fields (S12, ADR 0025) are a local column too — see
-          # Sqlite::Codec#persisted_fields' own comment; identical reasoning,
-          # `text` to match this file's own lowercase SQL type spelling.
+          # `projects` fields are local columns too (ADR 0025).
           @aggregate.projected_fields.each do |field|
             next if fields.any? { |f| f[:name] == field.name }
 
@@ -35,10 +26,7 @@ module Hecks
         end
 
         def encode(attr, value)
-          # **Never set is not empty** — same reasoning as Sqlite::Codec's own
-          # comment: a list attribute nothing has ever appended to has to
-          # stay NULL to answer the same as Memory does, not become `[]`
-          # invented by this adapter's own storage.
+          # A never-set list stays NULL rather than becoming `[]`, matching Memory.
           return (value.nil? ? nil : state_json(value)) if attr.list?
           return state_json(value) if value.is_a?(Hash) || value.is_a?(Runtime::Value)
 
@@ -51,13 +39,9 @@ module Hecks
           encode(field[:attribute], value)
         end
 
-        # Every jsonb column's text goes through the state codec's `encode`
-        # (PR A3) — see Sqlite::Codec#state_json.
         def state_json(value) = JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, value))
 
-        # Columns reassembled, then decoded once through the state codec
-        # (PR A3) — see Sqlite::Codec#decode, including why a NULL
-        # projected-only column reads back absent.
+        # A NULL projected-only column reads back absent.
         def decode(row)
           state = persisted_fields.each_with_object({}) do |field, raw_state|
             attr = field[:attribute]
@@ -84,13 +68,7 @@ module Hecks
             @aggregate.projected_fields.any? { |projected| projected.name.to_sym == field[:name].to_sym }
         end
 
-        # `pg` returns every column as a Ruby String by default (no type
-        # map installed) — a `bigint`/`double precision` column has to be
-        # coerced back on the way out, unlike Sqlite3's own driver, which
-        # already types a row by the column's declared affinity. Mirrors
-        # SQL_TYPES' own mapping: whatever gets a real numeric column here
-        # gets converted back here, everything else (String, references,
-        # enums, ...) passes through as the text it already is.
+        # `pg` returns every column as a String, so numeric columns are coerced back.
         def coerce_scalar(attr, raw)
           return nil if raw.nil?
 

data/lib/hecks/adapters/driven/postgres/outbox.rb

@@ -3,21 +3,12 @@ require_relative "../../../runtime/outbox"
 
 module Hecks
   module Adapters
-    # **The outbox, Postgres-shaped** — shared verbatim by `Postgres` and the
-    # era plugin's `PostgresEra`, the same way their `events` and
-    # `hecks_saga_instances` DDL is copied between them: nothing here is
-    # lineage-specific. Needs `@db` (a `PG::Connection`) and `table`
-    # (the aggregate's storage name) from the including class. See
-    # `Runtime::Outbox` for what the four verbs mean, and Sqlite's copy
-    # for the SQL idioms (`ON CONFLICT DO NOTHING` = idempotent enqueue,
-    # `WHERE status = 'pending'` = the compare-and-set claim).
+    # Outbox storage shared by `Postgres` and `PostgresEra`; needs `@db` and `table`.
+    # See `Runtime::Outbox` for the four verbs.
     module PostgresOutbox
       # Runs the block inside one Postgres transaction, joining an already-open one.
       #
-      # **Re-entrant** — `Interpreting#run_dispatch_order` opens one
-      # transaction around save+emit+outbox and the adapter's own
-      # `append`/`atomic_put`/`delete` each open theirs; PG refuses
-      # BEGIN inside BEGIN, so an inner call joins the open one.
+      # Re-entrant: PG refuses BEGIN inside BEGIN, so an inner call joins the open one.
       #
       # @yield the writes to commit together; an exception raised inside rolls the
       #   outermost transaction back

data/lib/hecks/adapters/driven/postgres/reconnect.rb

@@ -1,28 +1,7 @@
 module Hecks
   module Adapters
-    # **Self-healing connection** — shared verbatim by `Postgres` and the era
-    # plugin's `PostgresEra`, the same way `PostgresOutbox` (outbox.rb) is:
-    # nothing here is lineage-specific, and `PostgresOutbox`'s own
-    # `@db.exec*` calls route through this module's `pg_exec`/
-    # `pg_exec_params` too, since both classes mix it in. Needs `@db` (a
-    # `PG::Connection`), `@aggregate`, and `@settings` from the including
-    # class — the same three `self.class.connect_for(@aggregate.name,
-    # @settings)` already needs to build one in the first place.
-    #
-    # A backend killed out from under an adapter (a DBA's own
-    # `pg_terminate_backend`, a load balancer's failover, a restart) —
-    # chaos-tested against the plain `Postgres` adapter: `PG::ConnectionBad`
-    # on the query that hit it, and permanently on every query after,
-    # since nothing ever replaced `@db` with a live connection.
-    # `pg_exec`/`pg_exec_params` are the two primitives every other method
-    # in either class funnels through — wrapping them here, once,
-    # self-heals `@db` for the next caller. The current call still
-    # raises — reconnecting cannot tell a caller whether its own write
-    # reached the server before the connection died, so silently
-    # retrying it here could silently double it; that ambiguity is
-    # exactly why `Runtime::SagaInterpreter`'s own defect-retry exists
-    # one layer up, where a dispatch is retried as a whole (fresh
-    # hydrate, fresh `given`s), not as a lone SQL statement.
+    # Replaces a dead `@db` after `PG::ConnectionBad`; shared by `Postgres` and `PostgresEra`.
+    # Needs `@db`, `@aggregate` and `@settings`.
     module PostgresReconnect
       # Runs one parameterless statement, replacing a dead connection before re-raising.
       #
@@ -56,16 +35,15 @@ module Hecks
 
       private
 
-      # **Best-effort** — a reconnect attempt that itself fails (the server
-      # is actually down, not just this one backend) leaves `@db`
-      # unchanged; the `PG::ConnectionBad` already being re-raised by
-      # `pg_exec`/`pg_exec_params` above still reaches the caller either
-      # way, so swallowing a failed reconnect attempt here loses no
-      # information — it only avoids masking the original error with a
-      # second one.
+      # The failing call still raises and is never retried: it may have reached the server.
+      # A failed reconnect is swallowed so it does not mask the original error.
       def reconnect!
-        @db = self.class.connect_for(@aggregate.name, @settings)
-      rescue PG::Error
+        if @db.respond_to?(:reconnect!)
+          @db.reconnect!
+        else
+          @db = self.class.connect_for(@aggregate.name, @settings)
+        end
+      rescue PG::Error, Runtime::WiringError
         nil
       end
     end

data/lib/hecks/adapters/driven/postgres/schema_builder.rb

@@ -3,14 +3,8 @@ require "digest"
 module Hecks
   module Adapters
     class Postgres
-      # The DDL: one table per aggregate, a real column per attribute (a
-      # jsonb column per nested/list attribute), an append-only entry
-      # table beside it, the shared events/saga tables — and the automatic
-      # indexing this adapter carries that `PostgresEra` does not (see
-      # docs/implemented/postgres-era-adapter-split-plan.md, governing principle 3:
-      # every field a declared query filters or sorts on is safe to index
-      # directly here, since there is no `head_view` reduction to route
-      # around the way `PostgresEra`'s own cache-table story exists for).
+      # DDL for the aggregate, entry, event and saga tables, plus the automatic
+      # indexes derived from declared queries.
       module SchemaBuilder
         private
 
@@ -19,40 +13,15 @@ module Hecks
           @db.exec(
             "CREATE TABLE IF NOT EXISTS #{quoted_table} (id text PRIMARY KEY#{', ' unless columns.empty?}#{columns.join(', ')})"
           )
-          # **Self-healing, same idiom as `ensure_indexes!` below** —
-          # `CREATE TABLE IF NOT EXISTS` above does not retroactively add a
-          # column to an already-existing table (a committed database from
-          # before optimistic-concurrency CAS existed), so this runs
-          # unconditionally on every boot and no-ops once the column is
-          # there. Adapter bookkeeping only — never listed in
-          # `persisted_fields` (Codec), so it never appears in `decode`'s
-          # domain-state hash or `Instance#to_h`.
+          # CREATE TABLE IF NOT EXISTS never adds a column to an existing table, so
+          # the bookkeeping column is healed on every boot.
           @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS hecks_version bigint NOT NULL DEFAULT 1")
-          # Same self-healing shape, for domain attributes themselves —
-          # `hecks_version` above only heals the adapter's own bookkeeping
-          # column; a bluebook attribute added (or, via `translations/`,
-          # renamed) after this table already exists is not bookkeeping,
-          # but the identical gap applies: `CREATE TABLE IF NOT EXISTS`
-          # is a no-op against the existing table, so without this a new
-          # attribute boots clean and then dies `PG::UndefinedColumn` on
-          # the first `project` — discovered chaos-testing a live rename
-          # against this adapter (no era, no translation prompt; those
-          # live in `PostgresEra` — this is the plain adapter's own,
-          # simpler contract: "the table always has every column the
-          # bluebook currently declares"). No `NOT NULL`, no `DEFAULT` —
-          # existing rows get SQL NULL for a column they never had a
-          # value for, exactly what a fresh row would get for an unset
-          # optional attribute (`encode_field`'s own nil handling).
+          # Same healing for declared attributes: existing rows get NULL, as an unset
+          # optional attribute would.
           persisted_fields.each do |field|
             @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS " \
                      "#{quote_ident(field[:name])} #{field[:sql_type]}")
           end
-          # Right here, not a separate step in `Postgres#initialize` —
-          # same idiom Sqlite::SchemaBuilder's own `create_aggregate_table!`
-          # uses: index creation runs unconditionally, right after the
-          # table it indexes exists, the same self-healing shape
-          # `ensure_head_snapshot!`/`ensure_first_head!` already use on
-          # `PostgresEra`'s side.
           ensure_indexes!
         end
 
@@ -68,8 +37,6 @@ module Hecks
           SQL
         end
 
-        # Same DDL as `PostgresEra`'s own — not lineage-specific, copied
-        # verbatim (see docs/implemented/postgres-era-adapter-split-plan.md).
         def create_event_table!
           @db.exec(<<~SQL)
             CREATE TABLE IF NOT EXISTS events (
@@ -81,10 +48,27 @@ module Hecks
               occurred_at  text
             )
           SQL
+          # Backs #events_for's per-record lookup (a `corrects` command's history read).
+          @db.exec(
+            "CREATE INDEX IF NOT EXISTS hecks_events_aggregate_id_idx ON events (aggregate, aggregate_id)"
+          )
+        end
+
+        # One row per aggregate table, naming the highest entry `sequence` this table has
+        # already had projected into it — shared across every aggregate, since it is keyed
+        # by table name rather than declared per aggregate.
+        def create_checkpoint_table!
+          @db.exec(<<~SQL)
+            CREATE TABLE IF NOT EXISTS hecks_checkpoints (
+              aggregate_table text PRIMARY KEY,
+              last_sequence   bigint NOT NULL DEFAULT 0
+            )
+          SQL
+          # CREATE TABLE IF NOT EXISTS never adds a column to an existing table, so
+          # the bookkeeping column is healed on every boot, same as create_aggregate_table!.
+          @db.exec("ALTER TABLE hecks_checkpoints ADD COLUMN IF NOT EXISTS compacted_through bigint NOT NULL DEFAULT 0")
         end
 
-        # Same DDL as `PostgresEra`'s own — not lineage-specific, copied
-        # verbatim (see docs/implemented/postgres-era-adapter-split-plan.md).
         def create_saga_table!
           @db.exec(<<~SQL)
             CREATE TABLE IF NOT EXISTS hecks_saga_instances (
@@ -98,11 +82,7 @@ module Hecks
               PRIMARY KEY (domain, process_manager, correlation)
             )
           SQL
-          # `CREATE TABLE IF NOT EXISTS` above is a no-op against a table
-          # this same domain already created before this column existed
-          # — the same idiom `rust/host/src/journal.rs`'s own
-          # `sagas_backfilled` column addition already uses, for the
-          # identical reason.
+          # Heals a table created before this column existed.
           @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb " \
                    "NOT NULL DEFAULT '[]'::jsonb")
         end
@@ -113,24 +93,8 @@ module Hecks
           SQL_TYPES.fetch(attr.type, "text")
         end
 
-        # ── automatic indexing ───────────────────────────────────────
-        #
-        # Derived from every declared query's `where`/`order_by` fields —
-        # no bluebook author opts in, matching every other self-healing
-        # schema move this adapter makes. Walks the aggregate's own
-        # queries and each entity's own queries — the same enumeration
-        # `dsl/aggregate_builder.rb`'s own `query_surfaces` walks at
-        # declaration-seal time — but an entity's own fields never
-        # produce an index below: an entity has no table of its own, its
-        # rows live inside a list-typed attribute on the aggregate's own
-        # table (`QueryInterpreter#entity_rows` resolves it that way, and
-        # answers an entity query entirely in memory over `repository.all`
-        # — it never reaches this adapter's own `query` method at all).
-        # Every list-typed attribute is excluded below regardless (see
-        # `index_field!`), so an entity's own field would always resolve
-        # to "skip" anyway. Walked explicitly rather than silently
-        # dropped, so a reader can see entities were considered here, not
-        # forgotten.
+        # Indexes every field a declared query filters or sorts on. Entity queries are
+        # skipped: entities have no table, and their queries run in memory.
         def ensure_indexes!
           query_surfaces.each do |owner, queries|
             next unless owner.equal?(@aggregate)
@@ -149,50 +113,18 @@ module Hecks
           index_field!(query.order_by.field) if query.order_by
         end
 
-        # A `list_of` attribute is never indexed here — this adapter's
-        # own `contains` on a list field compiles to `EXISTS (SELECT 1
-        # FROM jsonb_array_elements(...) ...)` (see `list_contains_clause`
-        # below), a SQL shape neither a plain btree on the raw jsonb
-        # column nor even a GIN jsonb index (`@>`, `?`) accelerates —
-        # Postgres's own GIN jsonb operators match a different SQL shape
-        # than the `EXISTS` + `jsonb_array_elements` this codebase always
-        # compiles a list `contains` to. An index here would be dead
-        # weight, not free correctness, so none is attempted.
+        # A list attribute is never indexed: `contains` compiles to EXISTS over
+        # jsonb_array_elements, which neither a btree nor a GIN jsonb index accelerates.
         def index_field!(field)
-          # A hop path ("owner/field" — `Bluebook::AggregateBuilder`'s own
-          # convention for a field reached by crossing a reference,
-          # `aggregate_builder.rb`'s own `field.to_s.include?("/")`
-          # checks) is never indexed here — same reasoning as `list_of`
-          # below: `query_expression`/`nested_expression` below have no
-          # dialect for this shape at all (they'd compile the whole
-          # "owner/field" string as one bare column/jsonb-path segment,
-          # which is not a real column and errors PG::UndefinedColumn on
-          # `CREATE INDEX`, discovered fuzzing a real Postgres boot of
-          # `examples/banking` — Account's own `projects :customer_status,
-          # from: :"customer.status"` compiles to exactly this shape).
-          # Skipping the index is always safe, the same way skipping a
-          # `list_of` index is: an index is a perf optimization, not
-          # correctness, so "never built" beats "built wrong." Whether a
-          # hop-path field can be queried at all against this adapter is
-          # a separate, still-open question this skip does not answer —
-          # see docs/future-features.md's fuzzer-adapter entry, and
-          # docs/1.0-readiness.md item 2 for this gap's other two
-          # independent failure points (Postgres querying, Rust codegen's
-          # `OpenForSuspendedCustomers` — bin/rust_coverage's own
-          # allowlist) — tracked together, not as three unrelated bugs.
+          # A hop path ("owner/field") has no column or jsonb path to index; it would
+          # fail CREATE INDEX with PG::UndefinedColumn.
           return if field.to_s.include?("/")
 
           name, *_path = field.to_s.split(".")
           attribute = @aggregate.attribute(name)
           return if attribute&.list?
 
-          # The same expression the query itself compiles to — calling
-          # `query_expression`/`plain_column`, the real dialect methods,
-          # rather than a second, hand-rolled derivation of the same
-          # path that could silently drift from it. An index whose
-          # expression doesn't match the planner's own candidate
-          # expression byte-for-byte is invisible to the planner,
-          # created or not.
+          # Built from the query's own expression so the planner can match it byte for byte.
           expression = query_expression(field.to_s)
           if expression == plain_column(name)
             create_plain_index!(name)
@@ -211,13 +143,7 @@ module Hecks
           @db.exec("CREATE INDEX IF NOT EXISTS #{quote_ident(name)} ON #{quoted_table} ((#{expression}))")
         end
 
-        # Postgres identifiers cap at 63 bytes. Hashing table + field
-        # together keeps every generated index name well under that no
-        # matter how long an aggregate or attribute name gets, and keeps
-        # two distinct fields — on the same table or different ones —
-        # from ever colliding, or truncating into the same name the way
-        # a naive `"idx_#{table}_#{field}"` could once either got long
-        # enough.
+        # Hashed so the name stays under Postgres's 63-byte identifier limit and never collides.
         def index_name(field)
           "hecks_idx_#{Digest::SHA256.hexdigest("#{table}:#{field}")[0, 40]}"
         end

data/lib/hecks/adapters/driven/postgres/shared_connection.rb

@@ -0,0 +1,180 @@
+require "monitor"
+
+module Hecks
+  module Adapters
+    # One Postgres connection shared by every `Postgres` or `PostgresEra` adapter of a process
+    # that targets the same database and schema, so a domain's connection count does not grow
+    # with its aggregates. Each adapter class shares only with its own kind, because each opens
+    # its connection its own way.
+    #
+    # Every call runs under one re-entrant monitor, and a transaction holds it from BEGIN to
+    # COMMIT, so a second thread's statements never interleave into another thread's
+    # transaction. The owning thread re-enters freely, so a nested `transaction` joins the open
+    # one, whichever aggregate's adapter opened it.
+    class PostgresSharedConnection
+      REGISTRY = {} # rubocop:disable Style/MutableConstant
+      REGISTRY_LOCK = Mutex.new
+      private_constant :REGISTRY, :REGISTRY_LOCK
+
+      # Runs in a forked child right after the fork, before any of its code.
+      #
+      # A child inherits its parent's sockets, and libpq sends a Terminate on the socket when
+      # the child's copy of the connection is finalized at exit, which would end the parent's
+      # session. The child's copy of each socket fd is pointed at the null device, so that
+      # Terminate goes nowhere, and the child forgets the handles without `finish`.
+      #
+      # @return [void]
+      def self.disown_inherited!
+        REGISTRY.each_value(&:disown!)
+        REGISTRY.clear
+      end
+
+      # Prepended to `Process` so every `fork`, `Process.fork` and `Kernel#fork` disowns the
+      # shared connections in the child.
+      module ForkGuard
+        # @return [Integer, nil] the child's pid in the parent, nil in the child
+        def _fork
+          pid = super
+          PostgresSharedConnection.disown_inherited! if pid.zero?
+          pid
+        end
+      end
+      Process.singleton_class.prepend(ForkGuard)
+
+      # Returns the process's shared connection for a database and schema, opening it on first use.
+      #
+      # The key includes the pid, so a forked child opens its own instead of sharing its
+      # parent's socket.
+      #
+      # @param name [String] the domain or aggregate name, used only in refusal messages
+      # @param settings [Hash{Symbol, String => Object}] `database` and optional `schema`
+      # @param connector [#connect_for] the adapter class that opens the connection
+      # @return [PostgresSharedConnection] the shared handle, connected
+      # @raise [Runtime::WiringError] if `database` is missing or the connection is refused
+      def self.for(name, settings, connector:)
+        key = [Process.pid, connector, setting(settings, :database), setting(settings, :schema)]
+        REGISTRY_LOCK.synchronize do
+          handle = REGISTRY[key] ||= new(name, settings, connector: connector)
+          handle.reconnect! if handle.dead?
+          handle
+        end
+      end
+
+      # Reads one setting under its Symbol or String spelling as a string.
+      #
+      # @param settings [Hash{Symbol, String => Object}] the binding's settings
+      # @param key [Symbol] the setting's name
+      # @return [String] the value, empty when absent
+      def self.setting(settings, key)
+        (settings.key?(key) ? settings[key] : settings[key.to_s]).to_s
+      end
+      private_class_method :setting
+
+      # Counts the shared connections this process holds open.
+      #
+      # @return [Integer] how many database and schema pairs have a live shared connection
+      def self.open_count = REGISTRY_LOCK.synchronize { REGISTRY.values.count { |handle| !handle.dead? } }
+
+      # Closes every shared connection and forgets it; the next `for` opens a fresh one.
+      #
+      # @return [void]
+      def self.close_all!
+        REGISTRY_LOCK.synchronize do
+          REGISTRY.each_value(&:close)
+          REGISTRY.clear
+        end
+      end
+
+      # @param name [String] the domain or aggregate name, used only in refusal messages
+      # @param settings [Hash{Symbol, String => Object}] `database` and optional `schema`
+      # @param connector [#connect_for] the adapter class that opens the connection
+      # @raise [Runtime::WiringError] if `database` is missing or the connection is refused
+      def initialize(name, settings, connector:)
+        @name = name
+        @settings = settings
+        @connector = connector
+        @monitor = Monitor.new
+        @conn = connector.connect_for(name, settings)
+      end
+
+      # Runs one parameterless statement under the connection's monitor.
+      #
+      # @param sql [String] the statement
+      # @return [PG::Result] the statement's result
+      def exec(sql, &) = @monitor.synchronize { @conn.exec(sql, &) }
+
+      # Runs one statement with bind parameters under the connection's monitor.
+      #
+      # @param sql [String] the statement, with `$1`-style placeholders
+      # @param binds [Array<Object>] one value per placeholder
+      # @return [PG::Result] the statement's result
+      def exec_params(sql, binds = [], *rest, &) = @monitor.synchronize { @conn.exec_params(sql, binds, *rest, &) }
+
+      # Reports the server-side transaction state; blocks while another thread's transaction
+      # holds the connection, so a caller never mistakes it for its own.
+      #
+      # @return [Integer] a `PG::PQTRANS_*` constant
+      def transaction_status = @monitor.synchronize { @conn.transaction_status }
+
+      # Runs the block in one transaction, joining one the calling thread already holds.
+      #
+      # @yield the writes to commit together; an exception rolls the outermost one back
+      # @return [Object] the block's own value
+      def transaction(&block)
+        @monitor.synchronize do
+          next yield if @conn.transaction_status != PG::PQTRANS_IDLE
+
+          @conn.transaction(&block)
+        end
+      end
+
+      # Reports the server process id serving the connection.
+      #
+      # @return [Integer] the backend pid
+      def backend_pid = @monitor.synchronize { @conn.backend_pid }
+
+      # Quotes an identifier; needs no connection round trip.
+      #
+      # @param name [String, Symbol] the identifier
+      # @return [String] the double-quoted identifier
+      def quote_ident(name) = PG::Connection.quote_ident(name.to_s)
+
+      # Reports whether the underlying socket is closed or broken.
+      #
+      # @return [Boolean] true when the connection cannot run statements
+      def dead? = @monitor.synchronize { @conn.finished? || @conn.status != PG::CONNECTION_OK }
+
+      # Replaces the connection when it is dead; a no-op when another caller already did.
+      #
+      # @return [void]
+      # @raise [Runtime::WiringError] if the new connection is refused
+      def reconnect!
+        @monitor.synchronize do
+          next unless dead?
+
+          @conn.close unless @conn.finished?
+          @conn = @connector.connect_for(@name, @settings)
+        end
+      end
+
+      # Detaches this handle's socket from the parent's session in a forked child: the child's
+      # fd is repointed at the null device, so nothing the child's copy of the connection writes
+      # (statements, Terminate) reaches the parent's server session. Takes no lock, since the
+      # child holds none of the parent's monitors.
+      #
+      # @return [void]
+      def disown!
+        return if @conn.finished?
+
+        IO.for_fd(@conn.socket, autoclose: false).reopen(File::NULL, "r+")
+      rescue StandardError
+        nil
+      end
+
+      # Closes the underlying connection.
+      #
+      # @return [void]
+      def close = @monitor.synchronize { @conn.close unless @conn.finished? }
+    end
+  end
+end