ros-apartment 4.0.0.alpha6 → 4.0.0.alpha8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ce0a7124b9df22be74f2899b8a38046f52fcd7e1e0b068b3ebd778e16f57969
-  data.tar.gz: 0f40a39d073ae13bd59dce2e72e3e2aaa3759f2ffc270491f6dbbfcc7ef623fe
+  metadata.gz: 58a2c1795ee20c09d5ffa99ece8bb18d8697f981f6a6292750941775ee81738b
+  data.tar.gz: fb37448602b18043aee5f2d49d4f037c82b9b744917eeafb33de7e1099bdec6d
 SHA512:
-  metadata.gz: ebbc9775707e60c7e7bd896e6f1efa02487017519770dda6558cd89552e53558f47a39df31b73f4c90f6c7039e86399536ce586ce1bd30ac263ad67071c7407a
-  data.tar.gz: 8339cc7eb7b07adcb5df1f923c55f7e3aa96bad5faa47a13975550563af0d77191736b4afe0a8aa97f6a446adc59cc148a21739ff0c36224d3608371e6a0efe0
+  metadata.gz: 9913b7e11919a0a2fb39398a67cab8a5dad0dda6d637df954bec0222bcc83c93b1e71dc36469316d2a50fbdf07996d665903b24f17c87cf99191fea009661ffa
+  data.tar.gz: f1128508d59269eec5ed3c5f2a684b0a8205049242c53b0729b461502ae2d7e2b8613519e4e0cb949896f10468011c6684d0ceca266961ced545fba5e3242885

data/README.md

@@ -40,6 +40,25 @@ This gem is a maintained fork of the original [Apartment gem](https://github.com
 - Rails 7.2+
 - PostgreSQL 14+, MySQL 8.4+, or SQLite3
 
+### Ruby version manager
+
+`.ruby-version` is the single source of truth for the local Ruby version (the
+same file `ruby/setup-ruby` reads in CI). Both [mise](https://mise.jdx.dev) and
+[rbenv](https://github.com/rbenv/rbenv) honor it — use whichever you prefer:
+
+```bash
+# mise (recommended)
+brew install mise                 # then add `eval "$(mise activate zsh)"` to ~/.zshrc
+mise trust && mise install        # one-time trust per clone, then install the pinned Ruby
+
+# rbenv (also works, unchanged)
+rbenv install "$(cat .ruby-version)"
+```
+
+The committed `mise.toml` carries settings only (never a version): it tells mise
+to honor `.ruby-version` without any per-developer global config. `mise trust`
+is required once per clone; `bin/dev/setup-worktree` handles it for new worktrees.
+
 ### Setup
 
 ```ruby
@@ -99,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.
+
+`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 `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`.
+`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.
 

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/cli/migrations.rb

@@ -5,6 +5,13 @@ require 'thor'
 module Apartment
   class CLI < Thor
     class Migrations < Thor
+      # The raised Thor::Error message is the low-context surface a monitor or
+      # CI-log tail captures even when the stdout summary is dropped/unindexed.
+      # Name a few failed tenants there (capped, so a 600-tenant run does not
+      # produce a wall of text); the full per-tenant detail is in the summary
+      # and in the migrate_tenant_failed.apartment events.
+      FAILED_TENANTS_PREVIEW = 5
+
       def self.exit_on_failure? = true
 
       desc 'migrate [TENANT]', 'Run migrations for tenants'
@@ -62,7 +69,15 @@ module Apartment
         say(result.summary)
 
         trigger_schema_dump if result.success?
-        raise(Thor::Error, "Migration failed for #{result.failed.size} tenant(s)") unless result.success?
+        raise(Thor::Error, migration_failure_message(result.failed)) unless result.success?
+      end
+
+      def migration_failure_message(failures)
+        names = failures.map(&:tenant)
+        shown = names.first(FAILED_TENANTS_PREVIEW)
+        more = names.size - shown.size
+        suffix = more.positive? ? ", and #{more} more" : ''
+        "Migration failed for #{names.size} tenant(s): #{shown.join(', ')}#{suffix} (see summary above)"
       end
 
       # Rollback bypasses the Migrator's parallelism and Result tracking but

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,
@@ -38,6 +39,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
@@ -124,6 +127,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 +185,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, ' \
@@ -238,5 +281,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/instrumentation.rb

@@ -3,8 +3,8 @@
 require 'active_support/notifications'
 
 module Apartment
-  # Thin wrapper around ActiveSupport::Notifications.
-  # Known events: create, drop, evict (all namespaced as *.apartment).
+  # Thin wrapper around ActiveSupport::Notifications. All events are namespaced
+  # *.apartment; see docs/observability.md for the authoritative event catalog.
   module Instrumentation
     def self.instrument(event, payload = {}, &block)
       event_name = "#{event}.apartment"

data/lib/apartment/migrator.rb

@@ -121,9 +121,15 @@ module Apartment
         duration: monotonic_now - start, error: nil, versions_run: versions
       )
     rescue StandardError => e
+      duration = monotonic_now - start
+      # Symmetric with the :migrate_tenant success event above: the gem holds the
+      # full structured error here, so emit it for subscribers rather than
+      # stranding it in the returned Result. See migrate_tenant's rescue.
+      instrument_failure(tenant_name, e, duration)
+
       Result.new(
         tenant: tenant_name, status: :failed,
-        duration: monotonic_now - start, error: e, versions_run: []
+        duration: duration, error: e, versions_run: []
       )
     end
 
@@ -166,9 +172,17 @@ module Apartment
         end
       end
     rescue StandardError => e
+      duration = monotonic_now - start
+      # Failure counterpart to the :migrate_tenant success event. On SUCCESS the
+      # gem instruments; on FAILURE it previously only returned a failed Result,
+      # leaving adopters no hook to observe the (structured) error. This closes
+      # that asymmetry — generic payload (tenant + error + duration); routing to
+      # an error tracker is the subscriber's job.
+      instrument_failure(tenant, e, duration)
+
       Result.new(
         tenant: tenant, status: :failed,
-        duration: monotonic_now - start, error: e, versions_run: []
+        duration: duration, error: e, versions_run: []
       )
     ensure
       Apartment::Current.migrating = false
@@ -242,6 +256,34 @@ module Apartment
       conn.instance_variable_set(ADVISORY_LOCKS_IVAR, original) if conn&.instance_variable_defined?(ADVISORY_LOCKS_IVAR)
     end
 
+    # Emit the failure event without letting a raising subscriber break the
+    # Migrator's non-raising contract: the failed Result MUST still be returned.
+    # ActiveSupport::Notifications propagates subscriber exceptions through
+    # instrument (verified against AS 8.0), and this fires from inside a rescue
+    # block, so an un-isolated call would convert a captured per-tenant failure
+    # into an unhandled raise out of #run.
+    #
+    # Scope of the guarantee: a subscriber raising a StandardError is swallowed
+    # and warned. Process-control exceptions (SystemExit, SignalException /
+    # Interrupt) are deliberately NOT rescued — they must propagate so exit and
+    # Ctrl-C still work mid-migration; a subscriber raising a bare Exception
+    # subclass is itself a bug (Ruby errors should descend from StandardError).
+    # The warn is nested-rescued so a broken $stderr (IOError is a StandardError)
+    # cannot re-escape the handler. Success-path instrumentation is left
+    # un-isolated by design — only the failure path carries the hard no-raise
+    # guarantee, and swallowing there would mask real subscriber bugs.
+    def instrument_failure(tenant, error, duration)
+      Instrumentation.instrument(:migrate_tenant_failed, tenant: tenant, error: error, duration: duration)
+    rescue StandardError => e
+      # Nested rescue: a sibling `rescue` on this method would NOT catch an
+      # exception raised by warn (a broken $stderr), so the warn gets its own.
+      begin
+        warn "[Apartment::Migrator] migrate_tenant_failed subscriber raised #{e.class}: #{e.message}"
+      rescue StandardError
+        nil
+      end
+    end
+
     def monotonic_now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end

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_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/tasks/v4.rake

@@ -34,6 +34,13 @@ namespace :apartment do
     else
       Apartment::CLI::Migrations.new.invoke(:migrate)
     end
+    # Parity with apartment:drop: `.new.invoke` bypasses Thor.start's
+    # exit_on_failure? handling, so an unrescued Thor::Error (raised on
+    # migration failure) would surface as a raw `rake aborted!` backtrace that
+    # buries the actionable message. abort re-emits it as a clean one-liner
+    # with a non-zero exit.
+  rescue Thor::Error => e
+    abort(e.message)
   end
 
   desc 'Seed all tenants'

data/lib/apartment/version.rb

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

data/lib/apartment.rb

@@ -265,21 +265,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 +372,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.alpha6
+  version: 4.0.0.alpha8
 platform: ruby
 authors:
 - Ryan Brunner
@@ -194,6 +194,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