ros-apartment 4.0.0.alpha8 → 4.0.0.alpha9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58a2c1795ee20c09d5ffa99ece8bb18d8697f981f6a6292750941775ee81738b
-  data.tar.gz: fb37448602b18043aee5f2d49d4f037c82b9b744917eeafb33de7e1099bdec6d
+  metadata.gz: 5b4b1a4532066ffd3ebfdfa8c43b0f0cdd4e304f31f9905af8a91550e71c44a6
+  data.tar.gz: 75868c2063131bc20022d35142d87aff2c15f7c8b65b7fa3d8cbee43be4f11d1
 SHA512:
-  metadata.gz: 9913b7e11919a0a2fb39398a67cab8a5dad0dda6d637df954bec0222bcc83c93b1e71dc36469316d2a50fbdf07996d665903b24f17c87cf99191fea009661ffa
-  data.tar.gz: f1128508d59269eec5ed3c5f2a684b0a8205049242c53b0729b461502ae2d7e2b8613519e4e0cb949896f10468011c6684d0ceca266961ced545fba5e3242885
+  metadata.gz: 1f3c98442bf8ea826918440071a3a702615494d8761ef20f990135a10697650e05b72926f28a6cf1053b2aa969b67aee1b8c43249efe73ff58e8802c916f92a3
+  data.tar.gz: f23fd1d357e9b5b598516960a0d480f22512b0c8b4481827bb137cc074589a73d4684e4879dc1b2355a12a108fe1b25eaf54eff283aa6c89557c823d91a3e13a

data/README.md

@@ -338,6 +338,36 @@ Platform notes: parallel migrations use threads. On macOS, libpq has known fork-
 
 ## Known Limitations
 
+### Connection poolers in transaction mode (PgBouncer, RDS Proxy)
+
+> [!WARNING]
+> With the PostgreSQL `:schema` strategy, **PgBouncer in `transaction` pooling mode can
+> silently serve one tenant another tenant's data.** No error is raised — queries return the
+> wrong tenant's rows. It is safe only on **PostgreSQL 18+** with
+> `track_extra_parameters = IntervalStyle,search_path`; on PostgreSQL 17 and older,
+> transaction mode cannot be made safe and you must use `session` mode.
+
+Tenant isolation under `:schema` rests on `search_path`, which is session-scoped state.
+Transaction-mode pooling hands a different backend to each transaction, so a `search_path`
+set by one client is not guaranteed to be the one in effect for the next query. This affects
+v3 and v4 alike; v4 reduces the number of `SET search_path` statements to one per connection
+but does not eliminate them, and one is enough.
+
+**Which pooler to use:** PgBouncer on **PostgreSQL 18+** with
+`track_extra_parameters = IntervalStyle,search_path` is the only setup that safely multiplexes
+a schema-per-tenant app — and it needs no changes to Apartment or your application. **RDS Proxy
+is safe but reduces no connections**: a Rails app pins on it *with or without Apartment* (three
+unconditional `SET`s in `configure_connection`, plus the extended query protocol even at
+`prepared_statements: false` — [rails/rails#40207](https://github.com/rails/rails/issues/40207)),
+and AWS offers no session-pinning filters for PostgreSQL. Keep RDS Proxy if you use it for
+failover or IAM; don't adopt it to cut connections.
+
+Database-per-tenant (`:database_name`) is not affected.
+
+**Read [Connection Poolers](docs/connection-poolers.md) before putting a pooler in front of a
+schema-per-tenant app**, and verify your configuration rather than assuming it: the failure
+is silent, so a working app proves nothing.
+
 ### `connects_to` with Separate Databases
 
 If a model (or its abstract base class) uses `connects_to` to point at a completely different database (not just different roles on the same DB), Apartment's `connection_pool` patch will attempt to create a tenant pool for it.

data/lib/apartment/adapters/abstract_adapter.rb

@@ -68,15 +68,13 @@ module Apartment
       end
 
       # Drop a tenant.
-      def drop(tenant) # rubocop:disable Metrics/CyclomaticComplexity
+      def drop(tenant)
         drop_tenant(tenant)
         removed_pools = Apartment.pool_manager&.remove_tenant(tenant) || []
         removed_pools.each do |pool_key, pool|
-          begin
-            pool&.disconnect! if pool.respond_to?(:disconnect!)
-          rescue StandardError => e
-            warn "[Apartment] Pool disconnect failed for '#{pool_key}': #{e.class}: #{e.message}"
-          end
+          # remove_tenant already took these out of the manager, so deregister_shard's
+          # own removal returns nil and cannot disconnect them — we close them here.
+          Apartment.disconnect_removed_pool(pool, pool_key)
           begin
             deregister_shard_from_ar_handler(pool_key)
           rescue StandardError => e
@@ -118,6 +116,16 @@ module Apartment
         false
       end
 
+      # Whether +conn+ sits in an aborted-transaction state that every subsequent
+      # statement will fail against until the transaction ends. PostgreSQL is the
+      # only supported engine with such a state (PQTRANS_INERROR); MySQL fails the
+      # statement and leaves the transaction usable, and its raw connection has no
+      # transaction_status at all. Base is conservative: never reclassify.
+      # See docs/designs/transaction-taint-detection.md (Evidence E).
+      def aborted_transaction?(_conn)
+        false
+      end
+
       # Request-path fail-safe contract. The elevator wraps the
       # tenant switch; on one of these error classes it asks
       # #tenant_container_gone? whether the tenant's storage actually vanished (a

data/lib/apartment/adapters/postgresql_database_adapter.rb

@@ -10,6 +10,8 @@ module Apartment
     # to the environmentified tenant name. Lifecycle operations (create/drop)
     # execute DDL against the default connection.
     class PostgresqlDatabaseAdapter < AbstractAdapter
+      include PostgresqlTransactionState
+
       def resolve_connection_config(tenant, base_config: nil)
         config = base_config || send(:base_config)
         config.merge('database' => environmentify(tenant))

data/lib/apartment/adapters/postgresql_schema_adapter.rb

@@ -12,6 +12,8 @@ module Apartment
     # Apartment.config.postgres_config. Lifecycle operations (create/drop)
     # execute DDL against the default connection.
     class PostgresqlSchemaAdapter < AbstractAdapter
+      include PostgresqlTransactionState
+
       def shared_pinned_connection?
         !Apartment.config.force_separate_pinned_pool
       end

data/lib/apartment/adapters/postgresql_transaction_state.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Apartment
+  module Adapters
+    # PostgreSQL's aborted-transaction state, shared by both PG adapters
+    # (schema-per-tenant and database-per-tenant). Their implementations are
+    # identical, so this is the DRY seam rather than two copies.
+    #
+    # A failed statement inside a transaction moves the connection to
+    # PQTRANS_INERROR, where every subsequent statement raises
+    # PG::InFailedSqlTransaction until the transaction ends. Apartment heals this
+    # at pool checkin; see docs/designs/transaction-taint-detection.md.
+    module PostgresqlTransactionState
+      def aborted_transaction?(conn)
+        # NOT conn.raw_connection. That is the escape hatch for code about to *use*
+        # the driver, so it materializes lazy transactions, marks the connection
+        # dirty, and CONNECTS one that was never connected — at every checkin, on
+        # every pooled connection, which defeats Rails' lazy connect and burns a
+        # backend per tenant pool. We only read a status flag, so we take the handle
+        # directly. `connected?` keeps us off the never-connected path.
+        return false unless conn.connected?
+
+        raw = conn.instance_variable_get(:@raw_connection)
+        return false unless raw.respond_to?(:transaction_status)
+
+        raw.transaction_status == ::PG::PQTRANS_INERROR
+      rescue StandardError
+        # A connection too broken to report its own status is not ours to classify;
+        # AR's own verify!/reconnect path owns that case.
+        false
+      end
+    end
+  end
+end

data/lib/apartment/config.rb

@@ -27,7 +27,8 @@ module Apartment
                   :active_record_log, :sql_query_tags,
                   :shard_key_prefix,
                   :migration_role, :app_role, :schema_cache_per_tenant, :check_pending_migrations,
-                  :force_separate_pinned_pool, :test_fixture_cleanup, :reap_in_test
+                  :force_separate_pinned_pool, :test_fixture_cleanup, :reap_in_test,
+                  :heal_tainted_connections
 
     def initialize # rubocop:disable Metrics/AbcSize
       @tenant_strategy = nil
@@ -63,6 +64,13 @@ module Apartment
       @check_pending_migrations = true
       @force_separate_pinned_pool = false
       @reap_in_test = false
+      # Reset a tenant connection left in an aborted transaction when it is checked
+      # back into its pool. On by default: without it the poisoned connection is
+      # served to the next caller, and under pool-per-tenant that connection is the
+      # tenant's ONLY connection, so the tenant is dead on that worker until the
+      # process restarts. ActiveRecord's active? cannot detect the state.
+      # PostgreSQL-only in effect. See docs/designs/transaction-taint-detection.md.
+      @heal_tainted_connections = true
       @test_fixture_cleanup = true
     end
 
@@ -258,6 +266,12 @@ module Apartment
               "reap_in_test must be true or false, got: #{@reap_in_test.inspect}")
       end
 
+      unless [true, false].include?(@heal_tainted_connections)
+        raise(ConfigurationError,
+              'heal_tainted_connections must be true or false, ' \
+              "got: #{@heal_tainted_connections.inspect}")
+      end
+
       unless @tenant_validator.nil? || @tenant_validator == false || @tenant_validator.respond_to?(:call)
         raise(ConfigurationError,
               'tenant_validator must be nil, false, or a callable, ' \

data/lib/apartment/migrator.rb

@@ -222,7 +222,11 @@ module Apartment
       role = Apartment.config.migration_role
       return unless role && Apartment.pool_manager
 
-      Apartment.pool_manager.evict_by_role(role).each do |pool_key, _pool| # rubocop:disable Style/HashEachMethods
+      Apartment.pool_manager.evict_by_role(role).each do |pool_key, pool|
+        # evict_by_role already removed it from the manager, so deregister_shard has
+        # nothing left to disconnect; close it here or a pool AR no longer registers
+        # leaks its backend. See docs/designs/out-of-band-tenant-ddl.md.
+        Apartment.disconnect_removed_pool(pool, pool_key)
         Apartment.deregister_shard(pool_key)
       end
     rescue StandardError => e

data/lib/apartment/patches/connection_handling.rb

@@ -86,15 +86,34 @@ module Apartment
           # to the reaper and to max_total accounting (a connection leak that also
           # undercounts the cap). Deregister it before re-raising so AR and the
           # manager stay consistent. The next request re-establishes cleanly.
+          #
+          # deregister_ar_shard, NOT deregister_shard: we are running inside
+          # PoolManager's create block, and the full form removes from PoolManager's
+          # Concurrent::Map — whose MRI backend guards compute_if_absent and delete
+          # with the same non-reentrant mutex, so that would raise ThreadError
+          # ("deadlock; recursive locking") and skip this deregistration entirely,
+          # orphaning the very pool this rescue exists to reclaim. There is nothing
+          # to remove from the manager here regardless: the pool is not stored until
+          # this block returns.
+          #
+          # Reached with +send+ because the AR-only half is private: it is a
+          # half-operation, and leaving one publicly reachable is the exact footgun
+          # this seam exists to close. This is the one place it is correct.
           begin
             raise(Apartment::PendingMigrationError, tenant) if check_pending_migrations?(pool)
 
             load_tenant_schema_cache(tenant, pool) if cfg.schema_cache_per_tenant
           rescue StandardError
-            Apartment.deregister_shard(pool_key)
+            Apartment.send(:deregister_ar_shard, pool_key)
             raise
           end
 
+          # After the post-establish checks (a pool that fails them is discarded, so
+          # extending it would be wasted), and before the pool is handed out (so the
+          # very first checkin is already covered).
+          # See docs/designs/transaction-taint-detection.md.
+          Apartment::TransactionTaint.install(pool, tenant: tenant, pool_key: pool_key)
+
           pool
         end
       rescue Apartment::ApartmentError

data/lib/apartment/pool_manager.rb

@@ -40,12 +40,22 @@ module Apartment
 
     # Delete pool first, then timestamp. This ordering prevents a concurrent
     # #get from orphaning a timestamp (get checks @pools, skips touch if absent).
+    #
+    # @api private
+    # Forgetting a pool here is only HALF of discarding it — the pool stays
+    # registered in AR's ConnectionHandler, leaking the registration and a live
+    # backend if the tenant is never re-accessed. Callers outside the gem want
+    # Apartment.deregister_shard (one pool) or Apartment.reset_tenant_pools! (all).
+    # These mutators also bypass PoolReaper's in-use guard: they will drop a pool
+    # with a checked-out connection or an open transaction.
+    # See docs/designs/out-of-band-tenant-ddl.md.
     def remove(tenant_key)
       pool = @pools.delete(tenant_key)
       @timestamps.delete(tenant_key)
       pool
     end
 
+    # @api private — see #remove.
     def remove_tenant(tenant)
       prefix = "#{tenant}:"
       removed = []
@@ -58,6 +68,7 @@ module Apartment
       removed
     end
 
+    # @api private — see #remove.
     def evict_by_role(role)
       suffix = ":#{role}"
       removed = []

data/lib/apartment/pool_reaper.rb

@@ -142,6 +142,11 @@ module Apartment
       # on_evict with a nil pool.
       return nil unless (pool = @pool_manager.remove(tenant))
 
+      # We removed the pool ourselves, so deregister_shard's own removal returns nil
+      # and it has nothing left to disconnect. AR disconnects only a pool it still
+      # finds registered, so a pool that has drifted out of AR's handler would leak
+      # its backend unless we close it here. See docs/designs/out-of-band-tenant-ddl.md.
+      Apartment.disconnect_removed_pool(pool, tenant)
       deregister_from_ar_handler(tenant)
       Instrumentation.instrument(:evict, tenant: tenant, reason: reason)
       @on_evict&.call(tenant, pool)

data/lib/apartment/transaction_taint.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Apartment
+  # Heals a tenant connection left in an aborted transaction (PostgreSQL's
+  # PQTRANS_INERROR) at the moment it is checked back into its pool.
+  #
+  # WHY CHECKIN. ActiveRecord's +active?+ probes with an empty query, which does
+  # NOT error in an aborted transaction, so +verify!+ pronounces a poisoned
+  # connection healthy and +checkin+ does not reset it. The pool then serves it to
+  # the next caller. Under pool-per-tenant that connection is the ONLY connection
+  # for its tenant, so the tenant is dead on that worker until the process
+  # restarts, while every other tenant looks fine and nothing in the logs explains
+  # it. That amplification is what makes this ours to fix: the defect is generic
+  # Rails/PG, the consequence is specific to pool-per-tenant.
+  #
+  # Checkin is also the one seam that serves both populations correctly. A
+  # FIXTURE-PINNED connection must KEEP its transaction (teardown_fixtures owns the
+  # rollback) and never reaches ConnectionPool#checkin's body; a production
+  # connection must be reset before reuse. We still test +pinned+ explicitly,
+  # because this override runs BEFORE the early return in AR's own +checkin+.
+  #
+  # NEVER issue a raw ROLLBACK here. It destroys the ENCLOSING transaction while
+  # ActiveRecord still believes its stack is intact, raises nothing, and lets
+  # subsequent writes autocommit — turning a loud failure into silent, permanent
+  # database pollution. +reset!+ is ActiveRecord's own primitive: it rolls back,
+  # DISCARDs session state, and resets AR's transaction bookkeeping together. It
+  # also re-applies the pool's schema_search_path, so a healed tenant connection
+  # still points at its own schema (verified — the alternative would be a
+  # cross-tenant leak, which is strictly worse than the bug being fixed).
+  #
+  # Design: docs/designs/transaction-taint-detection.md
+  module TransactionTaint
+    # Extended onto Apartment-owned tenant pools only. The primary pool and every
+    # app-owned pool are left alone: the same Rails defect reaches them, but they
+    # are not ours, and the blast radius there is one connection of N rather than a
+    # dead tenant. That gap is reported upstream, not patched here.
+    module PoolHeal
+      attr_accessor :apartment_tenant, :apartment_pool_key, :apartment_taint_warned
+
+      def checkin(conn)
+        TransactionTaint.heal(conn, self)
+        super
+      end
+    end
+
+    class << self
+      # Extend +pool+ with the heal. Called once, at tenant-pool creation.
+      def install(pool, tenant:, pool_key:)
+        return pool unless Apartment.config&.heal_tainted_connections
+
+        pool.extend(PoolHeal)
+        pool.apartment_tenant = tenant.to_s
+        pool.apartment_pool_key = pool_key
+        pool
+      end
+
+      # Best-effort, and it must never raise: an exception here would abort
+      # ConnectionPool#checkin and leak the connection out of the pool permanently,
+      # which is worse than the taint we came to fix.
+      def heal(conn, pool)
+        return if conn.pinned
+        return unless Apartment.adapter&.aborted_transaction?(conn)
+
+        open_transactions = conn.open_transactions
+        conn.reset!
+        warn_once(pool)
+        instrument(pool, open_transactions: open_transactions, healed: true)
+      rescue StandardError => e
+        discard(conn, pool, e)
+      end
+
+      private
+
+      # reset! failed, and +super+ is about to put this connection back in the pool's
+      # available list. Checking a STILL-POISONED connection back in would rebuild the
+      # exact outage we came to fix — the next lease gets it and the tenant stays dead.
+      # So drop the handle instead: disconnect! sends no SQL and cannot fail to nil out
+      # @raw_connection, so the pool keeps a dead shell that Rails transparently
+      # reconnects, fresh, on the next checkout. Checking in a disconnected connection
+      # is normal Rails (it is what flush/reap leave behind).
+      def discard(conn, pool, error)
+        conn.disconnect!
+        warn('[Apartment] could not reset the tainted connection for tenant ' \
+             "'#{pool.apartment_tenant}' (#{error.class}: #{error.message}); the connection " \
+             'was dropped and will be reopened on next use.')
+        instrument(pool, open_transactions: nil, healed: false, error: error.class.name)
+      rescue StandardError
+        nil # Nothing further is safe to attempt inside checkin.
+      end
+
+      def instrument(pool, open_transactions:, healed:, error: nil)
+        Instrumentation.instrument(
+          'transaction_taint',
+          tenant: pool.apartment_tenant,
+          pool_key: pool.apartment_pool_key,
+          open_transactions: open_transactions,
+          healed: healed,
+          error: error
+        )
+      end
+
+      # Once per pool per process. Healing means each taint is a distinct incident
+      # rather than a cascade, but an app that poisons on every request would still
+      # warn on every request — flooding the log during the exact incident where the
+      # signal matters. The notification fires every time; it is the countable
+      # channel, and the one to alert on.
+      def warn_once(pool)
+        return if pool.apartment_taint_warned
+
+        pool.apartment_taint_warned = true
+        warn(
+          "[Apartment] the connection for tenant '#{pool.apartment_tenant}' was checked in " \
+          'while in an aborted transaction (PostgreSQL PQTRANS_INERROR) and has been reset. ' \
+          'Something ran a statement that failed inside a transaction Rails did not unwind. ' \
+          'Contain it by wrapping the failing call in ' \
+          'ActiveRecord::Base.transaction(requires_new: true); subscribe to ' \
+          'transaction_taint.apartment to find the call site. Do NOT add a raw ROLLBACK loop — ' \
+          'see docs/testing.md.'
+        )
+      end
+    end
+  end
+end

data/lib/apartment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apartment
-  VERSION = '4.0.0.alpha8'
+  VERSION = '4.0.0.alpha9'
 end

data/lib/apartment.rb

@@ -213,23 +213,81 @@ module Apartment # rubocop:disable Metrics/ModuleLength
       ActiveRecord::QueryLogs.tags = ActiveRecord::QueryLogs.tags + [:tenant]
     end
 
-    # Deregister a single tenant's shard from AR's ConnectionHandler.
+    # Discard one tenant pool, whole: deregister its shard from AR's ConnectionHandler
+    # and forget it in PoolManager, disconnecting it either way.
     # Safe to call when AR is not loaded or config is not set (no-op).
     # Used by PoolReaper eviction, AbstractAdapter#drop, and teardown.
+    #
+    # Both registries are updated because either one alone is wrong: deregistering
+    # from AR while the manager still holds the pool wedges the tenant permanently
+    # (the manager keeps handing back a pool AR has forgotten), and forgetting it in
+    # the manager alone leaks the AR registration and a live backend when the tenant
+    # is never re-accessed. Every internal caller already removes from the manager
+    # first, so the removal here is a no-op for them.
+    #
+    # The pool is disconnected here rather than left to AR, which disconnects only a
+    # pool it actually finds registered (ConnectionHandler#disconnect_pool_from_pool_manager
+    # guards `pool_config.disconnect!` behind `if pool_config`). A manager-held pool
+    # with no matching AR registration is reachable — the integration suite swaps the
+    # ConnectionHandler per example — and since we have just removed it from the
+    # manager, no later `PoolManager#clear` will disconnect it either. Mirrors
+    # AbstractAdapter#drop, which already removes, disconnects, then deregisters.
+    # (Callers that remove the pool from the manager THEMSELVES must disconnect it
+    # themselves too — the removal here returns nil for them, so there is nothing left
+    # for us to disconnect. PoolReaper#evict_tenant and Migrator#evict_migration_pools
+    # do exactly that.)
+    # See docs/designs/out-of-band-tenant-ddl.md.
+    #
+    # NOT SAFE inside a PoolManager create block — use +deregister_ar_shard+ there.
+    # PoolManager's @pools is a Concurrent::Map whose MRI backend guards
+    # +compute_if_absent+ and +delete+ with the SAME non-reentrant mutex, so removing
+    # a pool from inside the create block raises ThreadError ("deadlock; recursive
+    # locking"). The manager removal below is exactly that call.
+    #
+    # ORDER: AR first, manager removal in an +ensure+. The manager removal is an
+    # in-memory delete that cannot meaningfully fail, so it is the step that may run
+    # unconditionally; AR's removal does IO and is the one that can raise. Running the
+    # fallible step first, with the infallible one guaranteed after, means the call
+    # always ends with BOTH registries clear.
+    #
+    # Manager-first would be a race: between the manager delete and AR's removal, a
+    # concurrent tenant switch misses the manager, calls establish_connection — which
+    # RETURNS THE STILL-REGISTERED OLD POOL (ConnectionHandler#establish_connection
+    # reuses a pool whose db_config is equal) — and stores that doomed pool back in
+    # the manager. AR then unregisters and disconnects it, leaving the manager holding
+    # a dead pool: the permanent wedge this method exists to prevent, reintroduced.
+    # In this order the same interleaving costs at most one failed request, and the
+    # ensure clears the manager so the next switch rebuilds cleanly.
+    #
+    # Deliberately un-rescued at this level: both steps rescue their own failures, and
+    # swallowing everything here is what once hid a ThreadError, silently orphaning the
+    # pool the caller asked us to discard. Misuse should be loud.
     def deregister_shard(pool_key)
       return unless @config && defined?(ActiveRecord::Base)
 
-      _, separator, role_str = pool_key.to_s.rpartition(':')
-      role = separator.empty? || role_str.empty? ? ActiveRecord.writing_role : role_str.to_sym
+      begin
+        deregister_ar_shard(pool_key)
+      ensure
+        disconnect_removed_pool(@pool_manager&.remove(pool_key), pool_key)
+      end
+    end
 
-      shard_key = :"#{@config.shard_key_prefix}_#{pool_key}"
-      ActiveRecord::Base.connection_handler.remove_connection_pool(
-        'ActiveRecord::Base',
-        role: role,
-        shard: shard_key
-      )
+    # @api private
+    # Disconnect a pool that has been removed from PoolManager. Idempotent with AR's
+    # own disconnect on the happy path (ConnectionPool#disconnect! empties @connections,
+    # so a second call has nothing left to close); load-bearing only when AR has no
+    # matching registration to disconnect, in which case nothing else will close it.
+    #
+    # Public because the callers that remove a pool from the manager THEMSELVES — and
+    # therefore get nil back from deregister_shard's own removal — must disconnect what
+    # they removed: PoolReaper#evict_tenant, Migrator#evict_migration_pools,
+    # AbstractAdapter#drop. Rescued so one broken pool cannot abort the caller.
+    def disconnect_removed_pool(pool, pool_key)
+      return unless pool.respond_to?(:disconnect!)
+
+      pool.disconnect!
     rescue StandardError => e
-      warn "[Apartment] Failed to deregister AR pool for #{pool_key}: #{e.class}: #{e.message}"
+      warn "[Apartment] Failed to disconnect pool for #{pool_key}: #{e.class}: #{e.message}"
     end
 
     # Deregister all tenant pools from AR's ConnectionHandler and clear the
@@ -255,6 +313,32 @@ module Apartment # rubocop:disable Metrics/ModuleLength
 
     private
 
+    # The ActiveRecord half of a discard: deregister the shard (which disconnects the
+    # pool AR holds), leaving PoolManager untouched. The ONLY form that is safe inside
+    # a PoolManager create block — see the re-entrancy note on +deregister_shard+ —
+    # and correct there anyway: compute_if_absent does not store the pool until the
+    # block returns, so there is no manager entry to remove.
+    #
+    # PRIVATE ON PURPOSE. This is a half-operation, and a reachable half-operation is
+    # the bug this whole seam exists to eliminate: called on its own, it leaves AR
+    # without the pool while PoolManager keeps handing it out, wedging the tenant for
+    # the life of the process. The one legitimate caller reaches it with +send+.
+    def deregister_ar_shard(pool_key)
+      return unless @config && defined?(ActiveRecord::Base)
+
+      _, separator, role_str = pool_key.to_s.rpartition(':')
+      role = separator.empty? || role_str.empty? ? ActiveRecord.writing_role : role_str.to_sym
+
+      shard_key = :"#{@config.shard_key_prefix}_#{pool_key}"
+      ActiveRecord::Base.connection_handler.remove_connection_pool(
+        'ActiveRecord::Base',
+        role: role,
+        shard: shard_key
+      )
+    rescue StandardError => e
+      warn "[Apartment] Failed to deregister AR pool for #{pool_key}: #{e.class}: #{e.message}"
+    end
+
     # Double-checked locking: the common path (already built) skips the mutex;
     # concurrent first callers serialize so exactly one validator is built.
     # TenantValidator.new subscribes to ActiveSupport::Notifications, so a

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ros-apartment
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha8
+  version: 4.0.0.alpha9
 platform: ruby
 authors:
 - Ryan Brunner
@@ -168,6 +168,7 @@ files:
 - lib/apartment/adapters/mysql2_adapter.rb
 - lib/apartment/adapters/postgresql_database_adapter.rb
 - lib/apartment/adapters/postgresql_schema_adapter.rb
+- lib/apartment/adapters/postgresql_transaction_state.rb
 - lib/apartment/adapters/sqlite3_adapter.rb
 - lib/apartment/adapters/trilogy_adapter.rb
 - lib/apartment/cli.rb
@@ -207,6 +208,7 @@ files:
 - lib/apartment/tenant_name_validator.rb
 - lib/apartment/tenant_validator.rb
 - lib/apartment/test_fixtures.rb
+- lib/apartment/transaction_taint.rb
 - lib/apartment/version.rb
 - lib/generators/apartment/install/USAGE
 - lib/generators/apartment/install/install_generator.rb