ros-apartment 4.0.0.alpha7 → 4.0.0.alpha9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '093f09466c1e39d4344764096cec982394980fb08c8b72712c96bd8ad30fdcc7'
-  data.tar.gz: 402f7ef009203bb95296a90d7c6ff3dd34eeebca2d70c7da86cdb398ecc6fa60
+  metadata.gz: 5b4b1a4532066ffd3ebfdfa8c43b0f0cdd4e304f31f9905af8a91550e71c44a6
+  data.tar.gz: 75868c2063131bc20022d35142d87aff2c15f7c8b65b7fa3d8cbee43be4f11d1
 SHA512:
-  metadata.gz: 99343f0efe17d444cc23b244581c56135a293371c97ee3fc5d2d2931e51c688c50d9d3d93d8ae55489ec36d3a6a43a910cacdc85d22c43a6c7e80a1bad189faa
-  data.tar.gz: 2ccd4c456cf1a5ce190d4b50dedfc131231cd1f02518c0444313987ef0a5fda8acc00c1376bfc5daac791768f1b13685d0bb47a08ae5ba755943a2cd6eb5d04b
+  metadata.gz: 1f3c98442bf8ea826918440071a3a702615494d8761ef20f990135a10697650e05b72926f28a6cf1053b2aa969b67aee1b8c43249efe73ff58e8802c916f92a3
+  data.tar.gz: f23fd1d357e9b5b598516960a0d480f22512b0c8b4481827bb137cc074589a73d4684e4879dc1b2355a12a108fe1b25eaf54eff283aa6c89557c823d91a3e13a

data/README.md

@@ -118,15 +118,19 @@ All options are set in `config/initializers/apartment.rb` inside an `Apartment.c
 
 ### Pool Settings
 
-`tenant_pool_size`: max connections per tenant pool. Default `nil` — each tenant pool inherits the app's base pool size (`DB_POOL_SIZE` / `pool:` in `database.yml`). Set it to size tenant pools independently of the app pool (e.g. to bound total connections across many schema-per-tenant pools).
+`tenant_pool_size`: max connections per tenant pool. Default `nil` — each tenant pool inherits the app's base pool size (`DB_POOL_SIZE` / `pool:` in `database.yml`). **Set it to at least the peak number of threads/fibers in one process that can touch the _same_ tenant at once** (e.g. a Sidekiq role's concurrency for a same-tenant job fan-out); a smaller pool makes those threads block on connection checkout. It is a lazy ceiling — connections are created on demand and idle pools are reaped — so sizing for peak does not hold that many connections open at steady state.
 
 `pool_idle_timeout`: seconds an idle tenant pool must exceed before it is eligible for reaping (default: 300).
 
 `reaper_interval`: seconds between background reap passes. Default `nil` — derives from `pool_idle_timeout`. Set it lower to reap more often without shrinking the idle window.
 
-`max_total_connections`: ceiling on the number of live tenant pools; `nil` for unlimited (default: `nil`). Enforced synchronously at pool-creation time (see `pool_overflow_policy`) and trimmed continuously by the background reaper. Total backend connections ≈ `max_total_connections × tenant_pool_size`.
+`max_tenant_pools`: ceiling on the number of live tenant pools per process; `nil` for unlimited (default: `nil`). Enforced synchronously at pool-creation time (see `pool_overflow_policy`) and trimmed continuously by the background reaper.
 
-`pool_overflow_policy`: behavior when a new pool would breach `max_total_connections` and every existing pool is pinned or in use (no idle pool to evict). `:evict_idle` (default) — allow the new pool, emit a `cap_unmet` notification (soft cap, prioritizes availability). `:raise` — raise `Apartment::PoolCapacityReached` (hard cap, sheds load). When an idle pool *is* available it is always evicted inline regardless of policy. See `docs/designs/pool-admission-control.md`.
+`max_tenant_connections`: ceiling on total *tenant-pool* connections per process (default: `nil`); requires `tenant_pool_size`. The admission controller derives the pool budget as `floor(max_tenant_connections / tenant_pool_size)`. Per-process tenant-pool connections ≈ `effective_pool_budget × tenant_pool_size`, where `effective_pool_budget = min(max_tenant_pools, floor(max_tenant_connections / tenant_pool_size))`; the default pool and any separate pinned pool are additional. A tenant using multiple roles (e.g. `writing` + `reading`) holds one pool per role (`tenant:role` keys), counting once per role against the budget. For a hard external-pooler budget, pair this with `pool_overflow_policy: :raise` (the ceiling is soft under the default `:evict_idle`).
+
+`max_total_connections`: **deprecated** (removed in v5) — it capped tenant-pool *count*, not connections. It now aliases `max_tenant_pools`; rename it. For a true connection ceiling, set `max_tenant_connections`.
+
+`pool_overflow_policy`: behavior when a new pool would breach the pool budget (`max_tenant_pools` / `max_tenant_connections`) and every existing pool is pinned or in use (no idle pool to evict). `:evict_idle` (default) — allow the new pool, emit a `cap_unmet` notification (soft cap, prioritizes availability). `:raise` — raise `Apartment::PoolCapacityReached` (hard cap, sheds load). When an idle pool *is* available it is always evicted inline regardless of policy. See `docs/designs/pool-admission-control.md`.
 
 `reap_in_test`: keep the background reaper running under `Rails.env.test?` (default `false` — the Railtie stops it in test, where fixture transactions make mid-example eviction a liability). Set `true` if a deployed process can run under test-env semantics and must keep reaping — that's cleaner than guarding `RAILS_ENV` at boot to avoid silently leaking connections. It applies to *every* `Rails.env.test?` process, including CI, so enable it only when a real deployment needs it.
 
@@ -334,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/CLAUDE.md

@@ -20,7 +20,8 @@ lib/apartment/
 │   └── mysql_config.rb        # MysqlConfig: placeholder
 ├── elevators/             # Rack middleware for tenant detection (see CLAUDE.md); v4 uses constructor keyword args, no class-level state; Generic, Subdomain, FirstSubdomain, Domain, Host, HostHash, Header
 ├── patches/               # ActiveRecord patches for tenant-aware connections
-│   └── connection_handling.rb # Prepends on AR::Base — tenant-aware connection_pool
+│   ├── connection_handling.rb # Prepends on AR::Base — tenant-aware connection_pool
+│   └── postgresql_sequence_name.rb # Prepends on the PG adapter — schema-agnostic Model.sequence_name memoization
 ├── tasks/                 # Rake task utilities; v4.rake for apartment:create/drop/migrate/seed/rollback
 ├── config.rb              # Configuration with validate!/freeze!
 ├── current.rb             # Fiber-safe tenant context (CurrentAttributes)
@@ -59,7 +60,7 @@ lib/apartment/
 
 ### pool_manager.rb — Pool Cache
 
-`Concurrent::Map` storing connection pools by tenant key. Monotonic clock timestamps for idle/LRU tracking. `stats_for` returns `{ seconds_idle: N }`. `clear` disconnects all pools before clearing. When `max_total_connections` is set, `Apartment.configure` wires an `admission_controller` (the reaper) so cold creates route through a serialized, capacity-bounded path; otherwise the lock-free `compute_if_absent` fast path is used. See `docs/designs/pool-admission-control.md`.
+`Concurrent::Map` storing connection pools by tenant key. Monotonic clock timestamps for idle/LRU tracking. `stats_for` returns `{ seconds_idle: N }`. `clear` disconnects all pools before clearing. When a pool budget is configured (`max_tenant_pools` and/or `max_tenant_connections`, resolved by `Config#effective_pool_budget`; `max_total_connections` is the deprecated alias of `max_tenant_pools`), `Apartment.configure` wires an `admission_controller` (the reaper) so cold creates route through a serialized, capacity-bounded path; otherwise the lock-free `compute_if_absent` fast path is used. See `docs/designs/pool-connection-budget.md` and `docs/designs/pool-admission-control.md`.
 
 ### pool_reaper.rb — Pool Eviction + Admission
 
@@ -97,7 +98,7 @@ All inherit from `AbstractAdapter`. Override `resolve_connection_config`, `creat
 
 ### pool_observer.rb — Observability (opt-in)
 
-Sink-agnostic subscriber for the pool events (`create`/`evict`/`cap_unmet`/`skip_evict`/`reaper_stopped`) + an optional `Concurrent::TimerTask` gauge sampler (`tenant_pools_live`, optional adopter `backend_count`). Normalizes each to a `Sample` and forwards to a caller `sink`; ships no transport. Error-isolated — never raises into instrumentation. See `docs/observability.md`.
+Sink-agnostic subscriber for the pool events (`create`/`evict`/`cap_unmet`/`skip_evict`/`reaper_stopped`) + an optional `Concurrent::TimerTask` gauge sampler. Gauges: `tenant_pools_live`, optional adopter `backend_count`, and per-pass checkout-pressure gauges from each tenant pool's AR `ConnectionPool#stat` — `pools_waiting` (blocked on checkout), `pools_saturated` (`busy >= size`), `max_checkout_waiting` (worst pool's `waiting`, tenant in payload not a dimension). Per-pool `#stat` is rescued so one tearing-down pool can't abort the pass. Normalizes each to a `Sample` via the shared `emit_gauge` helper and forwards to a caller `sink`; ships no transport. Error-isolated — never raises into instrumentation. See `docs/observability.md`.
 
 ### railtie.rb — v4 Rails Integration
 

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

@@ -17,7 +17,8 @@ module Apartment
     attr_accessor :tenants_provider, :default_tenant,
                   :default_tenant_switch_allowed,
                   :tenant_pool_size, :pool_idle_timeout, :reaper_interval,
-                  :max_total_connections, :pool_overflow_policy,
+                  :max_total_connections, :max_tenant_pools, :max_tenant_connections,
+                  :pool_overflow_policy,
                   :seed_after_create, :seed_data_file,
                   :schema_load_strategy, :schema_file,
                   :parallel_migration_threads,
@@ -26,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
@@ -38,6 +40,8 @@ module Apartment
       @pool_idle_timeout = 300
       @reaper_interval = nil
       @max_total_connections = nil
+      @max_tenant_pools = nil
+      @max_tenant_connections = nil
       @pool_overflow_policy = :evict_idle
       @seed_after_create = false
       @seed_data_file = nil
@@ -60,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
 
@@ -124,6 +135,17 @@ module Apartment
       # Reap on the idle-timeout cadence unless an explicit interval decouples
       # the two (reap more often without shrinking the idle window).
       @reaper_interval = @pool_idle_timeout if @reaper_interval.nil?
+
+      # max_total_connections is deprecated: the name said "connections" but it
+      # always capped tenant-pool COUNT. Alias it to its true meaning without
+      # changing behavior. Only fill when max_tenant_pools was not set explicitly,
+      # so validate!'s both-set guard can still catch a genuine double-spec.
+      return unless @max_total_connections
+
+      warn '[Apartment] DEPRECATION: config.max_total_connections is deprecated and will be ' \
+           'removed in v5. It caps tenant-pool COUNT, not connections; rename it to ' \
+           'max_tenant_pools. For a true connection ceiling, set max_tenant_connections.'
+      @max_tenant_pools = @max_total_connections if @max_tenant_pools.nil?
     end
 
     # Validate configuration completeness and consistency.
@@ -171,6 +193,35 @@ module Apartment
               "max_total_connections must be a positive integer or nil, got: #{@max_total_connections.inspect}")
       end
 
+      if @max_tenant_pools && (!@max_tenant_pools.is_a?(Integer) || @max_tenant_pools < 1)
+        raise(ConfigurationError,
+              "max_tenant_pools must be a positive integer or nil, got: #{@max_tenant_pools.inspect}")
+      end
+
+      if @max_total_connections && @max_tenant_pools && @max_total_connections != @max_tenant_pools
+        raise(ConfigurationError,
+              'max_total_connections and max_tenant_pools are the same setting under two names; ' \
+              "set only one. Got max_total_connections=#{@max_total_connections}, " \
+              "max_tenant_pools=#{@max_tenant_pools}")
+      end
+
+      if @max_tenant_connections && (!@max_tenant_connections.is_a?(Integer) || @max_tenant_connections < 1)
+        raise(ConfigurationError,
+              "max_tenant_connections must be a positive integer or nil, got: #{@max_tenant_connections.inspect}")
+      end
+
+      if @max_tenant_connections && @tenant_pool_size.nil?
+        raise(ConfigurationError,
+              'max_tenant_connections requires tenant_pool_size to be set (the pool budget is ' \
+              'derived as max_tenant_connections / tenant_pool_size)')
+      end
+
+      if @max_tenant_connections && @tenant_pool_size && @max_tenant_connections < @tenant_pool_size
+        raise(ConfigurationError,
+              "max_tenant_connections (#{@max_tenant_connections}) must be >= tenant_pool_size " \
+              "(#{@tenant_pool_size}); it cannot fit a single tenant pool")
+      end
+
       unless %i[evict_idle raise].include?(@pool_overflow_policy)
         raise(ConfigurationError,
               'pool_overflow_policy must be :evict_idle or :raise, ' \
@@ -215,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, ' \
@@ -238,5 +295,15 @@ module Apartment
     def rails_env_name
       (Rails.env if defined?(Rails.env)) || ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'default_env'
     end
+
+    # The pool-count bound the admission controller enforces: the stricter of the
+    # explicit pool cap (max_tenant_pools) and the pool budget derived from the
+    # connection ceiling (max_tenant_connections / tenant_pool_size, floored).
+    # Returns nil (uncapped) when neither knob is set. Relies on a global
+    # tenant_pool_size, so tenant-pool connections <= budget * tenant_pool_size.
+    def effective_pool_budget
+      derived = @max_tenant_connections && @tenant_pool_size ? @max_tenant_connections / @tenant_pool_size : nil
+      [@max_tenant_pools, derived].compact.min
+    end
   end
 end

data/lib/apartment/errors.rb

@@ -33,22 +33,31 @@ module Apartment
   # Raised when the tenant connection pool is exhausted.
   class PoolExhausted < ApartmentError; end
 
-  # Raised when admitting a new tenant pool would exceed max_total_connections
-  # and no idle pool can be evicted to make room, under the :raise overflow
-  # policy. Distinct from PoolExhausted (a single pool's connections) — this is
-  # the process-wide pool-count ceiling. See docs/designs/pool-admission-control.md.
+  # Raised when admitting a new tenant pool would exceed the effective pool
+  # budget (Config#effective_pool_budget) and no idle pool can be evicted to make
+  # room, under the :raise overflow policy. Distinct from PoolExhausted (a single
+  # pool's connections) — this is the process-wide pool-COUNT ceiling. The message
+  # names the knobs that set it, never the deprecated max_total_connections: that
+  # name is what made the budget look like a connection count in the first place.
+  # See docs/designs/pool-connection-budget.md and pool-admission-control.md.
   class PoolCapacityReached < ApartmentError
+    # +max_total+ is the effective POOL budget, not a connection count. The
+    # reader keeps its name for compatibility with anything already rescuing this.
     attr_reader :max_total, :current
 
+    alias pool_budget max_total
+
     def initialize(max_total: nil, current: nil)
       @max_total = max_total
       @current = current
       super(
-        "Tenant pool capacity reached: #{current.inspect} pools open, " \
-        "max_total_connections is #{max_total.inspect}, and no idle pool could " \
-        'be evicted to admit another (all pinned or in use). Raise ' \
-        'max_total_connections, reduce concurrent tenants, or set ' \
-        'pool_overflow_policy to :evict_idle to allow soft overflow.'
+        "Tenant pool capacity reached: #{current.inspect} tenant pools open, " \
+        "the effective pool budget is #{max_total.inspect}, and no idle pool " \
+        'could be evicted to admit another (all pinned or in use). Raise ' \
+        'max_tenant_pools, or raise max_tenant_connections (which derives the ' \
+        'pool budget as max_tenant_connections / tenant_pool_size), reduce ' \
+        'concurrent tenants, or set pool_overflow_policy to :evict_idle to ' \
+        'allow soft overflow.'
       )
     end
   end

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/patches/postgresql_sequence_name.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Apartment
+  module Patches
+    # Keeps ActiveRecord's class-level Model.sequence_name memoization
+    # schema-agnostic under pool-per-tenant.
+    #
+    # Rails resolves default_sequence_name via pg_get_serial_sequence with an
+    # unqualified table name, so PostgreSQL answers through the current
+    # connection's search_path and returns a schema-QUALIFIED name — the schema
+    # of whichever tenant's pool happened to resolve it first. ActiveRecord then
+    # memoizes that value once per model class, process-wide. Consumers that
+    # render it into SQL (activerecord-import prefetches primary keys as a
+    # literal nextval(Model.sequence_name)) would draw ids from the
+    # first-resolver tenant's sequence in every tenant: wrong-tenant ids, silent
+    # sequence drift, and eventual PG::UniqueViolation.
+    #
+    # Stripping the connection's own current_schema prefix makes the memoized
+    # value schema-agnostic: nextval('widgets_id_seq') re-resolves through each
+    # pool's search_path, per tenant — the same invariant v4 relies on for table
+    # names (see docs/designs/v4-connection-model-rationale.md). A prefix naming
+    # any OTHER schema is preserved on purpose: persistent-schema tables and
+    # pinned models (whose table names are default_tenant-qualified and may
+    # execute on a shared tenant connection) are only correct BECAUSE they stay
+    # qualified.
+    #
+    # v3 shipped this guarantee as PostgreSqlAdapterPatch; it was lost in the
+    # Phase 2.5 v3 deletion (PR #356). Reset-on-switch is not an alternative:
+    # v4 serves tenants concurrently in one process, so only a schema-agnostic
+    # memoized value can be correct.
+    module PostgresqlSequenceName
+      def default_sequence_name(table_name, primary_key = 'id')
+        res = super
+        return res if res.nil?
+        # A schema-qualified table name is a PINNED model: Apartment qualifies
+        # those to the default tenant, and they resolve on whatever connection is
+        # current (the schema strategy shares the tenant's connection). Its
+        # sequence must stay qualified — stripping here is the mirror-image bug,
+        # because an unqualified name would later re-resolve against a *tenant's*
+        # search_path and draw ids from that tenant's stale copy of the pinned
+        # table's sequence. That order is the common one, not a corner case:
+        # pinned models are typically first touched at boot, on the default pool.
+        # v3 guarded the same case by force-adding the default_tenant prefix.
+        return res if table_name.to_s.include?('.')
+
+        # Routed table: drop whatever schema PostgreSQL qualified the sequence
+        # with — not just the connection's own. The two differ when the tenant
+        # schema is missing the table and search_path falls through to a schema
+        # that has it: the resolved sequence then names the FALLBACK schema, and
+        # preserving that would memoize it process-wide, so every tenant —
+        # including correctly-migrated ones — would draw from the fallback's
+        # sequence forever. Unqualified is the only value that lets the sequence
+        # re-resolve per pool exactly like the table name does.
+        #
+        # Parsed with AR's own splitter (rather than by hand) because it is what
+        # produced `res`, so it round-trips quoting and dotted identifiers.
+        ActiveRecord::ConnectionAdapters::PostgreSQL::Utils
+          .extract_schema_qualified_name(res).identifier
+      end
+    end
+  end
+end

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_observer.rb

@@ -66,14 +66,15 @@ module Apartment
     # when supplied. Safe to call from start_sampler! or an external scheduler.
     def sample!
       total = Apartment.pool_manager&.stats&.fetch(:total_pools, 0) || 0
-      emit(Sample.new(name: :tenant_pools_live, kind: :gauge, value: total, dimensions: {}, payload: {}))
+      emit_gauge(:tenant_pools_live, total)
+      emit_checkout_pressure!
 
       return unless @backend_count
 
       backends = @backend_count.call
       return if backends.nil?
 
-      emit(Sample.new(name: :backend_connections, kind: :gauge, value: backends, dimensions: {}, payload: {}))
+      emit_gauge(:backend_connections, backends)
     rescue StandardError => e
       warn_failure('sample!', e)
     end
@@ -104,6 +105,43 @@ module Apartment
       @sampler = nil
     end
 
+    # Per-tenant-pool checkout pressure, aggregated to low cardinality. waiting>0
+    # means threads are blocked acquiring a connection (the same-tenant fan-out
+    # starvation signal). The worst tenant is carried in the Sample payload, NOT
+    # as a metric dimension, to avoid unbounded time-series churn. Per-pool #stat
+    # is rescued so a pool tearing down mid-sample can't abort the whole pass.
+    def emit_checkout_pressure!
+      manager = Apartment.pool_manager
+      return unless manager
+
+      stats = collect_pool_stats(manager)
+      worst = stats.max_by { |s| s[:pending] } || { tenant: nil, pending: 0 }
+      payload = worst[:pending].positive? ? { tenant: worst[:tenant] } : {}
+
+      emit_gauge(:pools_waiting, stats.count { |s| s[:pending].positive? })
+      emit_gauge(:pools_saturated, stats.count { |s| s[:saturated] })
+      emit_gauge(:max_checkout_waiting, worst[:pending], payload: payload)
+    end
+
+    def emit_gauge(name, value, payload: {})
+      emit(Sample.new(name: name, kind: :gauge, value: value, dimensions: {}, payload: payload))
+    end
+
+    # Read each tenant pool's checkout stats into [{ tenant:, pending:, saturated: }],
+    # skipping any pool whose #stat raises (mid-teardown) so one bad pool can't
+    # abort the whole pass.
+    def collect_pool_stats(manager)
+      stats = []
+      manager.each_pair do |tenant_key, pool|
+        stat = pool.stat
+        stats << { tenant: tenant_key, pending: stat[:waiting].to_i,
+                   saturated: stat[:busy].to_i >= stat[:size].to_i }
+      rescue StandardError
+        next
+      end
+      stats
+    end
+
     def record_event(event, payload)
       # Copy the notification payload so a sink that mutates Sample#payload
       # can't corrupt it for other subscribers of the same event.

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.alpha7'
+  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
@@ -265,21 +349,23 @@ module Apartment # rubocop:disable Metrics/ModuleLength
     end
 
     # Build the pool manager + reaper for a freshly-validated config and start
-    # the background reaper. When max_total_connections is set, wire the reaper
-    # as the pool manager's admission controller so cold creates are bounded
-    # synchronously; otherwise the manager keeps its lock-free create path.
+    # the background reaper. When a pool budget is configured (max_tenant_pools
+    # and/or max_tenant_connections, via Config#effective_pool_budget), wire the
+    # reaper as the pool manager's admission controller so cold creates are
+    # bounded synchronously; otherwise the manager keeps its lock-free create path.
     def setup_pools!(new_config)
+      budget = new_config.effective_pool_budget
       @pool_manager = PoolManager.new
       @pool_reaper = PoolReaper.new(
         pool_manager: @pool_manager,
         interval: new_config.reaper_interval,
         idle_timeout: new_config.pool_idle_timeout,
-        max_total: new_config.max_total_connections,
+        max_total: budget,
         default_tenant: new_config.default_tenant,
         shard_key_prefix: new_config.shard_key_prefix,
         overflow_policy: new_config.pool_overflow_policy
       )
-      @pool_manager.admission_controller = @pool_reaper if new_config.max_total_connections
+      @pool_manager.admission_controller = @pool_reaper if budget
       @pool_reaper.start
     end
 
@@ -370,6 +456,16 @@ module Apartment # rubocop:disable Metrics/ModuleLength
   end
 end
 
+# Prepend the sequence-name patch whenever the PostgreSQL adapter loads
+# (immediately, if it already has). Registered at gem load rather than in
+# activate! because ActiveRecord memoizes Model.sequence_name at first touch,
+# which can happen during boot before Apartment.activate! runs. No-op for apps
+# that never load the PostgreSQL adapter, so MySQL/SQLite consumers never pull
+# in pg. See the patch file for the full rationale.
+ActiveSupport.on_load(:active_record_postgresqladapter) do
+  prepend(Apartment::Patches::PostgresqlSequenceName)
+end
+
 # Load Railtie when Rails is present (standard gem convention).
 # Railtie is Zeitwerk-ignored — this explicit require is the only load path.
 require_relative 'apartment/railtie' if defined?(Rails::Railtie)

data/lib/generators/apartment/install/templates/apartment.rb

@@ -37,9 +37,20 @@ Apartment.configure do |config|
 
   # == Connection Pool =====================================================
 
-  # config.tenant_pool_size      = 5
-  # config.pool_idle_timeout     = 300
-  # config.max_total_connections = nil
+  # tenant_pool_size MUST be >= the peak number of threads/fibers in one process
+  # that can touch the SAME tenant at once (e.g. a Sidekiq role's concurrency for a
+  # same-tenant job fan-out); otherwise those threads block on connection checkout.
+  # It is a lazy ceiling — connections are created on demand and idle pools reaped.
+  # config.tenant_pool_size       = 5
+  # config.pool_idle_timeout      = 300
+  #
+  # Bound how many tenant pools exist per process:
+  # config.max_tenant_pools       = nil
+  # ...or bound total tenant-pool CONNECTIONS (requires tenant_pool_size); the
+  # admission controller derives the pool budget as floor(value / tenant_pool_size):
+  # config.max_tenant_connections = nil
+  #
+  # config.max_total_connections  = nil # DEPRECATED: alias of max_tenant_pools; removed in v5
 
   # == Elevator (Request Tenant Detection) =================================
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ros-apartment
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha7
+  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
@@ -194,6 +195,7 @@ files:
 - lib/apartment/migrator.rb
 - lib/apartment/patches/connection_handling.rb
 - lib/apartment/patches/live_tenant_propagation.rb
+- lib/apartment/patches/postgresql_sequence_name.rb
 - lib/apartment/pool_manager.rb
 - lib/apartment/pool_observer.rb
 - lib/apartment/pool_reaper.rb
@@ -206,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