ros-apartment 4.0.0.alpha1 → 4.0.0.alpha3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff587e273664aea9b3fba6477c64cdd5309dfa75a7b47715e6671452aa209788
-  data.tar.gz: 1684f55b0be423185a8f8b6b41270028a1cfb07bd240afee5325ba6f9da4b6ca
+  metadata.gz: 0b2254c1f3f95622ba9fa45147fcc2f5b2036db4c5c75a2d68c3718772df6149
+  data.tar.gz: efcc9149b0aaaa6c7b614cc981848f02e999259eaa0826120b4df16b555f6caf
 SHA512:
-  metadata.gz: 0b0a44d91f78033ace32559a0d8e8095ba287dfa98cd07c084a5f3f9b79341a21cd3ba36a439412360f37d4147dc83e8fbba944a92a01ffa8d799d23eb746050
-  data.tar.gz: efba1ef8faff63c0ce3795e29d1f16fad2eaf894ba62346ee8aa37cf8fb000c86caa59b865567ee4490898bca4ec2cee19aba16fd0643bee9e8b5ee2bfff8409
+  metadata.gz: 35b3bdeb392ed750be9a20868082f1708e2ae3c4c8449cef5bda163d3e2e911409274abf9a1f8161811678192c8aaaa21c2f4d6a177a5932a9567942172bc234
+  data.tar.gz: 3d0909cc593dcbd014f21626a2565e0e92d373cb74aa768f308b1033f689fbdea1aa48a2f886294e581d4d3954b1d719b15ab3277990a8fde216449eed40485f

data/README.md

@@ -60,7 +60,7 @@ The generated initializer at `config/initializers/apartment.rb` configures Apart
 Apartment.configure do |config|
   config.tenant_strategy = :schema          # :schema (PostgreSQL) or :database_name (MySQL/SQLite)
   config.tenants_provider = -> { Customer.pluck(:subdomain) }
-  config.default_tenant = 'public'
+  config.default_tenant = 'public'          # auto-defaults for :schema; required for :database_name
 end
 ```
 
@@ -99,11 +99,15 @@ All options are set in `config/initializers/apartment.rb` inside an `Apartment.c
 
 ### Pool Settings
 
-`tenant_pool_size`: connections per tenant pool (default: 5).
+`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).
 
-`pool_idle_timeout`: seconds before an idle tenant pool is eligible for reaping (default: 300).
+`pool_idle_timeout`: seconds an idle tenant pool must exceed before it is eligible for reaping (default: 300).
 
-`max_total_connections`: hard cap across all tenant pools; nil for unlimited (default: nil).
+`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`.
+
+`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`.
 
 ### Elevator (Request Tenant Detection)
 
@@ -112,7 +116,7 @@ config.elevator = :subdomain
 config.elevator_options = {}
 ```
 
-The Railtie auto-inserts elevator middleware. No manual `config.middleware.use` needed.
+The Railtie auto-inserts elevator middleware after `ActionDispatch::Callbacks` (just before cookies/sessions in full mode; works in API mode too).
 
 See the [Elevators](#elevators) section for available options.
 
@@ -217,7 +221,14 @@ Apartment.configure do |config|
 end
 ```
 
-The Railtie inserts the elevator as middleware automatically. You do not need `config.middleware.use` or `config.middleware.insert_before`.
+The Railtie inserts the elevator after `ActionDispatch::Callbacks` automatically. In the full middleware stack this places it just before cookies, sessions, and authentication. In API mode (where cookies/sessions are absent), `Callbacks` is still present so the elevator works without changes.
+
+If you need different positioning, skip `config.elevator` and insert manually:
+
+```ruby
+# config/application.rb
+config.middleware.insert_before 'Warden::Manager', Apartment::Elevators::Subdomain
+```
 
 ### Custom Elevator
 
@@ -304,6 +315,28 @@ Workaround: add `include Apartment::Model` and `pin_tenant` on the abstract clas
 
 The common pattern of `ApplicationRecord` using `connects_to` with multiple roles (writing/reading) on the same database works correctly; Apartment keys pools by `tenant:role` and respects Rails' role routing.
 
+## ActionController::Live Streaming
+
+Apartment v4 handles tenant propagation across `ActionController::Live`'s spawned streaming thread automatically, under both `:thread` and `:fiber` isolation. Including `ActionController::Live` in your controller is sufficient — no additional configuration:
+
+```ruby
+class StreamingController < ApplicationController
+  include ActionController::Live
+
+  def show
+    response.headers['Content-Type'] = 'text/event-stream'
+    # Apartment::Tenant.current returns the request's tenant here,
+    # even though we're now executing on the OS thread Rails spawned
+    # for streaming.
+    response.stream.write("data: #{{ tenant: Apartment::Tenant.current }.to_json}\n\n")
+  ensure
+    response.stream.close
+  end
+end
+```
+
+How it works: Apartment prepends `ActionController::Live#process` with a patch that backports [rails/rails#56902](https://github.com/rails/rails/pull/56902) to released Rails versions — it points `Thread.current.active_support_execution_state` at the request fiber's hash for the duration of the request, so Rails' own `share_with` carries all `CurrentAttributes` (apartment's tenant plus any app-defined ones) into the spawned streaming thread. User-spawned threads or fibers *inside* a Live action (`Thread.new`, `Async { }`, raw `Fiber.new`) escape the patch and need explicit `Apartment::Tenant.switch` wrapping. See the [upgrading guide](docs/upgrading-to-v4.md) and [`docs/designs/rails-boundary-tenancy.md`](docs/designs/rails-boundary-tenancy.md).
+
 ## Background Workers
 
 Use block-scoped switching in jobs:
@@ -323,6 +356,19 @@ For automatic tenant propagation:
 - [apartment-sidekiq](https://github.com/rails-on-services/apartment-sidekiq)
 - [apartment-activejob](https://github.com/rails-on-services/apartment-activejob)
 
+A job that forgets to switch runs in the default tenant — for `Rails.cache` and
+other `Tenant.current`-derived resources that silently contaminate another
+tenant's keyspace. Guard routed work with `Apartment::Tenant.require_tenant!`
+(raises unless a real, non-default tenant is active) and pinned/global work with
+`require_default_tenant!`. See [Tenant-Aware Caching](docs/caching.md) for the
+routed-vs-pinned model and the two-store recipe.
+
+## Convenience Methods
+
+`Apartment.tenant_names` returns the current tenant list (delegates to `config.tenants_provider.call`). Preserves the v3 API so existing call sites work without changes.
+
+`Apartment.excluded_models` returns the excluded models list (delegates to `config.excluded_models`). Deprecated in v4; use `Apartment::Model` + `pin_tenant` instead.
+
 ## Troubleshooting
 
 If tenant switching raises unexpected errors, verify that `tenants_provider` returns valid tenant names and that the tenant exists in the database.
@@ -331,6 +377,28 @@ If tenant switching raises unexpected errors, verify that `tenants_provider` ret
 
 See the [upgrade guide](docs/upgrading-to-v4.md) for a complete list of breaking changes and migration steps.
 
+## RuboCop cops
+
+Apartment ships two optional RuboCop cops that enforce the block-form
+tenant-switching discipline. Enable them in your application's `.rubocop.yml`:
+
+```yaml
+require: rubocop/apartment
+inherit_gem:
+  ros-apartment: config/default.yml
+```
+
+- **`Apartment/NoDirectCurrentWrite`** (error) — bans assigning
+  `Apartment::Current.tenant` / `.previous_tenant` directly. Change tenant context
+  with `Apartment::Tenant.switch(tenant) { ... }` (or `with_default_tenant` for
+  global work), which guarantees a restore via `ensure`.
+- **`Apartment/PreferBlockSwitch`** (warning) — nudges `Apartment::Tenant.switch!`
+  toward the block form. `reset` is not flagged.
+
+Both match the qualified `Apartment::` receiver only. Scope them to your
+application code with the standard `Exclude:` keys if needed. See
+[`docs/designs/rubocop-cops.md`](docs/designs/rubocop-cops.md) for the rationale.
+
 ## Contributing
 
 1. Check [existing issues](https://github.com/rails-on-services/apartment/issues) and [discussions](https://github.com/rails-on-services/apartment/discussions)

data/config/default.yml

@@ -0,0 +1,9 @@
+Apartment/NoDirectCurrentWrite:
+  Description: 'Use the block-form switch instead of writing Apartment::Current directly.'
+  Enabled: true
+  Severity: error
+
+Apartment/PreferBlockSwitch:
+  Description: 'Prefer the block-form Apartment::Tenant.switch over switch!.'
+  Enabled: true
+  Severity: warning

data/lib/apartment/CLAUDE.md

@@ -14,9 +14,9 @@ lib/apartment/
 │   ├── trilogy_adapter.rb     # Database-per-tenant on MySQL (trilogy driver, inherits Mysql2Adapter)
 │   └── sqlite3_adapter.rb     # File-per-tenant (FileUtils lifecycle)
 ├── concerns/              # ActiveRecord concerns for tenant-aware models
-│   └── model.rb               # Apartment::Model concern: pin_tenant, apartment_pinned?
+│   └── model.rb               # Apartment::Model concern: pin_tenant, pinned identity, table-name helpers
 ├── configs/               # Database-specific config objects
-│   ├── postgresql_config.rb   # PostgresqlConfig: persistent_schemas, enforce_search_path_reset
+│   ├── postgresql_config.rb   # PostgresqlConfig: persistent_schemas, include_schemas_in_dump
 │   └── 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
@@ -42,6 +42,13 @@ lib/apartment/
 
 `switch(tenant) { ... }` sets `Current.tenant` via ensure block. Delegates lifecycle ops (`create`, `drop`, `migrate`, `seed`) to `Apartment.adapter`. No thread-local state — uses `CurrentAttributes` for fiber safety.
 
+**Tenant-context guard family — two axes (#427)**:
+- **Explicitness axis** (raw `Current.tenant`, ignores the `default_tenant` fallback): `tenant_switched?` / `assert_tenant_switched!(message:)`. Answers "did this code explicitly enter a tenant?" — test discipline. Renamed from `inside_tenant?` / `assert_inside_tenant!` (no aliases).
+- **Identity axis** (effective `Tenant.current`, `to_s`-normalized): `in_tenant?` / `require_tenant!` (real, non-default; `require_tenant!` returns the name and raises `TenantRequired`), `in_default_tenant?` / `require_default_tenant!` (default; returns the name, raises `DefaultTenantRequired` in a real tenant or `DefaultTenantNotConfigured` when no default is set). `cache_namespace` wraps `require_tenant!` for fail-closed namespace procs; `with_default_tenant { }` enters the default/pinned context (guard-exempt, restore-on-raise). For runtime routed/pinned decisions (cache, jobs). See `docs/caching.md` and `docs/designs/tenant-aware-caching.md`.
+
+**Strict-mode switch guard (4.0.0.alpha3)**:
+- `switch(name) { ... }` calls `guard_default_tenant_switch!`, which raises when `Apartment.config.default_tenant_switch_allowed` is `false` AND `name == default_tenant`. `switch!`, `reset`, and `with_default_tenant` are exempt by design — they remain the unguarded paths back to the default tenant. The flag defaults to `true` (permissive) for all strategies; new PG `:schema` apps wanting strict semantics opt in. See `docs/testing.md`.
+
 ### config.rb — Configuration
 
 `Apartment.configure { |c| ... }` builds config, validates, freezes. Prepare-then-swap pattern: failed configure preserves previous working config. Frozen after validation — tests must reconfigure, not stub.
@@ -52,15 +59,15 @@ 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.
+`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`.
 
-### pool_reaper.rb — Pool Eviction
+### pool_reaper.rb — Pool Eviction + Admission
 
-Background `Concurrent::TimerTask` instance that evicts idle and excess tenant pools. Created by `Apartment.configure`, stored as `Apartment.pool_reaper`. Deregisters evicted pools from AR's ConnectionHandler. Default tenant is never evicted.
+Background `Concurrent::TimerTask` that evicts idle and excess tenant pools, and also serves as the pool manager's synchronous admission controller (`admit!`) when a cap is configured — evicting the LRU idle pool inline before a new one is established, applying `pool_overflow_policy` (`:evict_idle` / `:raise`) when no idle pool can be freed. A single `evict_tenant` primitive backs the timer (idle/LRU) and admission paths. Reap cadence (`interval`/`reaper_interval`) is decoupled from the idle window (`idle_timeout`/`pool_idle_timeout`). Created by `Apartment.configure`, stored as `Apartment.pool_reaper`. Deregisters evicted pools from AR's ConnectionHandler. Default tenant is never evicted.
 
 ### adapters/abstract_adapter.rb — Base Adapter
 
-Lifecycle ops (`create`, `drop`, `migrate`, `seed`), `ActiveSupport::Callbacks` on `:create`/`:switch`, `resolve_connection_config` (abstract — subclasses override), `process_excluded_models`, `environmentify`, `base_config` (stringified `connection_config`), `rails_env` (guarded `Rails.env` access). Constructor takes `connection_config` (raw AR hash, not `Apartment::Config`).
+Lifecycle ops (`create`, `drop`, `migrate`, `seed`), `ActiveSupport::Callbacks` on `:create`/`:switch`, `resolve_connection_config` (abstract — subclasses override), `process_excluded_models`, `environmentify`, `base_config` (stringified `connection_config`), `rails_env` (guarded `Rails.env` access). `process_pinned_model` / `qualify_pinned_table_name` call **`Apartment::Model` class methods** (`apartment_explicit_table_name?`, `apartment_mark_processed!`, etc.); no `instance_variable_*` on arbitrary model classes. Constructor takes `connection_config` (raw AR hash, not `Apartment::Config`).
 
 ### Concrete Adapters (Phase 2.2)
 
@@ -74,7 +81,19 @@ All inherit from `AbstractAdapter`. Override `resolve_connection_config`, `creat
 
 ### concerns/model.rb — Model Pinning Concern
 
-`Apartment::Model` provides `pin_tenant` (class method) to declare a model as pinned to the default tenant. Registered models bypass the `ConnectionHandling` patch. Zeitwerk-safe: works whether called before or after `activate!`. `apartment_pinned?` checks the class and its superclass chain.
+`Apartment::Model` provides `pin_tenant` (class method) to declare a model as pinned to the default tenant. Registered models bypass the `ConnectionHandling` patch when the adapter uses a separate pool; when shared pinned connections are enabled, routing follows the tenant pool (see design docs). Zeitwerk-safe: works whether called before or after `activate!`.
+
+**Identity:** `apartment_pinned?` — the class answers whether it is pinned (ivars + superclass walk). `Apartment.pinned_model?(klass)` delegates to `klass.apartment_pinned?` when the concern is included; otherwise it falls back to registry lookup (`pinned_models`) for `excluded_models` shim classes that never included the concern.
+
+**Table naming:** `apartment_explicit_table_name?` — whether `self.table_name` was explicitly set vs convention (compares `@table_name` to `compute_table_name`). Lives here so adapters do not read `@table_name` or call `compute_table_name` from outside; **class instance variable access for pinning is confined to this concern**.
+
+**Lifecycle:** `apartment_pinned_processed?`, `apartment_mark_processed!`, `apartment_restore!` — qualification state and teardown. Adapters call these; `Apartment.clear_config` uses `apartment_restore!` with `respond_to?` so shim-registered models without the concern still clear safely. `apartment_mark_pinned!` — sets the pinned flag without triggering processing (used by `process_pinned_model` for shim classes to avoid `pin_tenant` recursion).
+
+**Guards:** `pin_tenant` raises `ArgumentError` if called on a non-AR class or module. For anonymous classes (`Class.new`), it warns that `TracePoint(:end)` won't fire and skips deferral; call `process_pinned_model` explicitly after assigning the constant.
+
+**Deferred processing:** When `Apartment.activated?` is true (Zeitwerk lazy-load path), `pin_tenant` defers `process_pinned_model` via `apartment_defer_processing!` — a one-shot `TracePoint(:end)` constrained to `Thread.current`. Only `:end` is used: `:b_return` fires for ALL block returns in class context (each, include hooks) and would trigger prematurely; `:raise` is not used because rescued raises still produce `:end` (MRI verified). For `Class.new { }` (tests, runtime metaprogramming), `:end` does not fire; call `process_pinned_model` explicitly. Models loaded before `activate!` are unaffected (processed in batch by `Tenant.init`). Reopening a pinned class does not re-trigger processing (idempotent via `apartment_pinned?`).
+
+**Shim compatibility:** `process_pinned_model` dynamically includes `Apartment::Model` on classes registered via the `excluded_models` shim that lack the concern. This is a runtime `include` on a partially-booted class — acceptable for the legacy shim path but new code should always use `include Apartment::Model` + `pin_tenant` explicitly.
 
 ### railtie.rb — v4 Rails Integration
 

data/lib/apartment/adapters/abstract_adapter.rb

@@ -30,7 +30,8 @@ module Apartment
           strategy: Apartment.config.tenant_strategy,
           adapter_name: effective_base['adapter']
         )
-        resolve_connection_config(tenant, base_config: effective_base)
+        config = resolve_connection_config(tenant, base_config: effective_base)
+        apply_tenant_pool_size(config)
       end
 
       # Resolve a tenant-specific connection config hash.
@@ -96,37 +97,83 @@ module Apartment
         end
       end
 
-      # Process all pinned models — establish separate connections pinned to default tenant.
+      # Whether pinned models can share the tenant's connection pool using
+      # qualified table names instead of establish_connection.
+      #
+      # Returns false by default (separate pool). Subclasses override to
+      # return true when the engine supports cross-schema/database queries,
+      # gated by config.force_separate_pinned_pool.
+      def shared_pinned_connection?
+        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
+      # cross-process drop) rather than an app-level failure. An empty list
+      # disables the rescue, so an adapter that does not implement the seams
+      # never converts an error into a 404.
+      def failsafe_error_classes
+        []
+      end
+
+      # Whether +error+, raised while serving +tenant+, means the tenant's
+      # container (schema/database/file) no longer exists — so the validator
+      # should evict the name and the request should 404 instead of surfacing a
+      # 500. Composed from a cheap error-shape check and an authoritative
+      # existence probe, both conservative by default so the base adapter never
+      # reclassifies. Subclasses override the seams.
+      def tenant_container_gone?(error, tenant)
+        return false unless container_error?(unwrap_db_error(error))
+
+        !tenant_container_exists?(tenant)
+      end
+
+      # Qualify a pinned model's table_name so it targets the default
+      # tenant's tables from any tenant connection. Subclasses must
+      # implement when shared_pinned_connection? returns true.
+      def qualify_pinned_table_name(_klass)
+        raise(NotImplementedError,
+              "#{self.class}#qualify_pinned_table_name must be implemented when shared_pinned_connection? is true")
+      end
+
+      # Process all pinned models. When shared_pinned_connection? is true, qualifies
+      # table names for shared pool routing. Otherwise, establishes separate connections.
       def process_pinned_models
         return if Apartment.pinned_models.empty?
 
         Apartment.pinned_models.each do |klass|
           process_pinned_model(klass)
+        rescue StandardError => e
+          raise(Apartment::ConfigurationError,
+                "Failed to process pinned model #{klass.name}: #{e.class}: #{e.message}")
         end
       end
 
       # Process a single pinned model. Called by process_pinned_models (batch)
       # and by Apartment::Model.pin_tenant (when activated? is true).
+      #
+      # When shared_pinned_connection? is true, qualifies the table name so
+      # the model uses the tenant's pool (preserving transactional integrity).
+      # Otherwise, establishes a separate connection pool (required when
+      # cross-database queries are impossible).
       def process_pinned_model(klass)
-        # Idempotent: skip if already processed. Uses a class-level flag rather
-        # than connection_specification_name comparison — the spec name differs
-        # from ActiveRecord::Base for ApplicationRecord subclasses even before
-        # establish_connection, so it's not a reliable "already processed" signal.
-        return if klass.instance_variable_get(:@apartment_connection_established)
-
-        # Use base_config (the adapter's raw connection config) rather than
-        # resolve_connection_config(default_tenant). For database-per-tenant
-        # strategies (MySQL, SQLite), resolve_connection_config would set the
-        # database key to the default tenant NAME (e.g. 'default'), not the
-        # actual default database (e.g. 'apartment_v4_test'). base_config
-        # points to the real default database.
-        klass.establish_connection(base_config)
-        klass.instance_variable_set(:@apartment_connection_established, true)
+        # Ensure the concern is included — models registered via the
+        # excluded_models shim may not have it yet. Uses apartment_mark_pinned!
+        # (not pin_tenant) to avoid recursion back into process_pinned_model.
+        unless klass.respond_to?(:apartment_pinned_processed?)
+          klass.include(Apartment::Model)
+          klass.apartment_mark_pinned!
+        end
 
-        return unless Apartment.config.tenant_strategy == :schema
+        return if klass.apartment_pinned_processed?
 
-        table = klass.table_name.split('.').last
-        klass.table_name = "#{default_tenant}.#{table}"
+        if shared_pinned_connection?
+          qualify_pinned_table_name(klass)
+        else
+          klass.establish_connection(pinned_model_config)
+          klass.apartment_mark_processed!
+        end
       end
 
       # Deprecated: use process_pinned_models instead.
@@ -169,6 +216,28 @@ module Apartment
 
       private
 
+      # --- Missing-tenant fail-safe seams -------------------------------------
+
+      # Does +error+ look like a missing-container error for this engine?
+      # Base: never, so the default adapter classifies nothing.
+      def container_error?(_error)
+        false
+      end
+
+      # Authoritative check that the tenant's container exists. Base: assume it
+      # does, so an unimplemented adapter never evicts a live tenant.
+      def tenant_container_exists?(_tenant)
+        true
+      end
+
+      # ConnectionHandling wraps non-Apartment errors raised during pool
+      # resolution in Apartment::ApartmentError with the original as #cause; the
+      # schema-strategy query error arrives unwrapped. Inspect the cause when
+      # present so both shapes classify the same.
+      def unwrap_db_error(error)
+        error.is_a?(Apartment::ApartmentError) && error.cause ? error.cause : error
+      end
+
       def grant_tenant_privileges(tenant)
         app_role = Apartment.config.app_role
         return unless app_role
@@ -191,6 +260,33 @@ module Apartment
         connection_config.transform_keys(&:to_s)
       end
 
+      # Cap the tenant pool's max checkout size to Apartment.config.tenant_pool_size
+      # when configured. Defaults to nil — the tenant pool inherits the base/default
+      # pool's `pool:` (the app's DB_POOL_SIZE), preserving pre-4.0.0.alpha3 behavior.
+      # Set tenant_pool_size to size each per-tenant pool independently of the app pool
+      # (e.g. to bound total connections across many schema-per-tenant pools). The config
+      # is string-keyed here; HashConfig symbolizes it and reads `:pool` for the size.
+      def apply_tenant_pool_size(config)
+        size = Apartment.config.tenant_pool_size
+        return config unless size
+
+        config.merge('pool' => size)
+      end
+
+      # Connection config for pinned models on the separate-pool path.
+      # For schema strategy, pins schema_search_path to the default tenant
+      # (plus persistent schemas) so the connection resolves tables and FK
+      # constraints in the correct schema.
+      # For database strategies, returns base_config unchanged.
+      def pinned_model_config
+        config = base_config
+        return config unless Apartment.config.tenant_strategy == :schema
+
+        persistent = Apartment.config.postgres_config&.persistent_schemas || []
+        search_path = [default_tenant, *persistent].map { |s| %("#{s}") }.join(',')
+        config.merge('schema_search_path' => search_path)
+      end
+
       def rails_env
         unless defined?(Rails)
           raise(Apartment::ConfigurationError,

data/lib/apartment/adapters/mysql2_adapter.rb

@@ -10,11 +10,41 @@ module Apartment
     # to the environmentified tenant name. Lifecycle operations (create/drop)
     # execute DDL against the default connection.
     class Mysql2Adapter < AbstractAdapter
+      def shared_pinned_connection?
+        !Apartment.config.force_separate_pinned_pool
+      end
+
+      def qualify_pinned_table_name(klass)
+        db_name = base_config['database']
+
+        if klass.apartment_explicit_table_name?
+          original = klass.table_name
+          table = original.sub(/\A[^.]+\./, '')
+          klass.table_name = "#{db_name}.#{table}"
+          klass.apartment_mark_processed!(:explicit, original)
+        else
+          original_prefix = klass.table_name_prefix
+          klass.table_name_prefix = "#{db_name}."
+          klass.reset_table_name
+          klass.apartment_mark_processed!(:convention, original_prefix)
+        end
+      end
+
       def resolve_connection_config(tenant, base_config: nil)
         config = base_config || send(:base_config)
         config.merge('database' => environmentify(tenant))
       end
 
+      # The database-per-tenant missing-tenant error: connecting to a dropped
+      # database raises ActiveRecord::NoDatabaseError (MySQL error 1049) — an
+      # unambiguous signal. It surfaces raw at query time, or wrapped in
+      # ApartmentError when ConnectionHandling resolves the pool (the dev-mode
+      # pending-migration check), so both are listed; #container_error? gates on
+      # the unwrapped NoDatabaseError. Inherited by TrilogyAdapter.
+      def failsafe_error_classes
+        [ActiveRecord::NoDatabaseError, Apartment::ApartmentError]
+      end
+
       protected
 
       def create_tenant(tenant)
@@ -38,6 +68,24 @@ module Apartment
           "GRANT SELECT, INSERT, UPDATE, DELETE ON #{connection.quote_table_name(db_name)}.* TO #{quoted_role}@'%'"
         )
       end
+
+      def container_error?(error)
+        error.is_a?(ActiveRecord::NoDatabaseError)
+      end
+
+      # Authoritative existence check on the DEFAULT connection:
+      # information_schema.schemata is server-global and reachable from any
+      # database, and the rescue runs after switch restored Current.tenant to
+      # default. The tenant's database is the environmentified name. A probe
+      # failure means we cannot prove it gone, so report it as existing and let
+      # the original error re-raise.
+      def tenant_container_exists?(tenant)
+        conn = ActiveRecord::Base.connection
+        quoted = conn.quote(environmentify(tenant))
+        !conn.select_value("SELECT 1 FROM information_schema.schemata WHERE schema_name = #{quoted}").nil?
+      rescue StandardError
+        true
+      end
     end
   end
 end

data/lib/apartment/adapters/postgresql_database_adapter.rb

@@ -15,6 +15,16 @@ module Apartment
         config.merge('database' => environmentify(tenant))
       end
 
+      # The database-per-tenant missing-tenant error: connecting to a dropped
+      # database raises ActiveRecord::NoDatabaseError (PG SQLSTATE 3D000) — an
+      # unambiguous signal, unlike the schema strategy's 42P01. It surfaces raw at
+      # query time, or wrapped in ApartmentError when ConnectionHandling resolves
+      # the pool (the dev-mode pending-migration check), so both are listed;
+      # #container_error? gates on the unwrapped NoDatabaseError.
+      def failsafe_error_classes
+        [ActiveRecord::NoDatabaseError, Apartment::ApartmentError]
+      end
+
       protected
 
       def create_tenant(tenant)
@@ -42,6 +52,25 @@ module Apartment
       # (GRANT CONNECT on server, table grants inside tenant DB).
       # Use the callable app_role escape hatch for this strategy.
       # See docs/designs/v4-phase5-rbac-roles-schema-cache.md.
+
+      private
+
+      def container_error?(error)
+        error.is_a?(ActiveRecord::NoDatabaseError)
+      end
+
+      # Authoritative existence check on the DEFAULT connection: pg_database is a
+      # cluster-global catalog reachable from any database, and the rescue runs
+      # after switch restored Current.tenant to default. The tenant's database is
+      # the environmentified name. A probe failure means we cannot prove it gone,
+      # so report it as existing and let the original error re-raise.
+      def tenant_container_exists?(tenant)
+        conn = ActiveRecord::Base.connection
+        quoted = conn.quote(environmentify(tenant))
+        !conn.select_value("SELECT 1 FROM pg_database WHERE datname = #{quoted}").nil?
+      rescue StandardError
+        true
+      end
     end
   end
 end

data/lib/apartment/adapters/postgresql_schema_adapter.rb

@@ -12,14 +12,48 @@ module Apartment
     # Apartment.config.postgres_config. Lifecycle operations (create/drop)
     # execute DDL against the default connection.
     class PostgresqlSchemaAdapter < AbstractAdapter
+      def shared_pinned_connection?
+        !Apartment.config.force_separate_pinned_pool
+      end
+
+      def qualify_pinned_table_name(klass)
+        if klass.apartment_explicit_table_name?
+          original = klass.table_name
+          table = original.sub(/\A[^.]+\./, '')
+          klass.table_name = "#{default_tenant}.#{table}"
+          klass.apartment_mark_processed!(:explicit, original)
+        else
+          original_prefix = klass.table_name_prefix
+          klass.table_name_prefix = "#{default_tenant}."
+          klass.reset_table_name
+          klass.apartment_mark_processed!(:convention, original_prefix)
+        end
+      end
+
       def resolve_connection_config(tenant, base_config: nil)
         config = base_config || send(:base_config)
         persistent = Apartment.config.postgres_config&.persistent_schemas || []
-        search_path = [tenant, *persistent].join(',')
+        search_path = [tenant, *persistent].map { |s| %("#{s}") }.join(',')
 
         config.merge('schema_search_path' => search_path)
       end
 
+      # The schema-strategy missing-tenant error: a dropped schema is not caught
+      # at switch time (search_path accepts a non-existent schema silently) — it
+      # surfaces on the first query as ActiveRecord::StatementInvalid
+      # (PG::UndefinedTable, 42P01). That is the same shape as a missing table in
+      # a *live* schema, so #tenant_container_exists? does the disambiguating
+      # to_regnamespace check.
+      #
+      # ApartmentError is included because ConnectionHandling wraps errors raised
+      # during pool resolution (e.g. the dev-mode pending-migration check, which
+      # queries schema_migrations in the gone schema) as ApartmentError with the
+      # StatementInvalid as #cause; #container_error? then unwraps and classifies
+      # it the same as the query-time case, and re-raises any other ApartmentError.
+      def failsafe_error_classes
+        [ActiveRecord::StatementInvalid, Apartment::ApartmentError]
+      end
+
       protected
 
       def create_tenant(tenant)
@@ -34,6 +68,27 @@ module Apartment
 
       private
 
+      # Any StatementInvalid is a candidate; the authoritative call is the
+      # existence probe below, so a missing table in a live schema (same 42P01)
+      # correctly re-raises rather than 404ing.
+      def container_error?(error)
+        error.is_a?(ActiveRecord::StatementInvalid)
+      end
+
+      # Authoritative existence check, run on the DEFAULT connection: the
+      # elevator's switch ensure-block has already restored Current.tenant before
+      # the fail-safe rescue runs, so ActiveRecord::Base.connection targets the
+      # default pool rather than the gone tenant. to_regnamespace returns NULL for
+      # a missing schema. If the probe itself errors (e.g. the database is down),
+      # we cannot prove the schema is gone — report it as existing so the original
+      # error re-raises instead of masking infrastructure failure as a 404.
+      def tenant_container_exists?(tenant)
+        conn = ActiveRecord::Base.connection
+        conn.select_value("SELECT to_regnamespace(#{conn.quote(tenant)}) IS NOT NULL")
+      rescue StandardError
+        true
+      end
+
       def grant_privileges(tenant, connection, role_name) # rubocop:disable Metrics/MethodLength
         quoted_schema = connection.quote_table_name(tenant)
         quoted_role = connection.quote_table_name(role_name)

data/lib/apartment/adapters/sqlite3_adapter.rb

@@ -18,6 +18,20 @@ module Apartment
         config.merge('database' => File.join(db_dir, "#{environmentify(tenant)}.sqlite3"))
       end
 
+      # No missing-tenant fail-safe override on purpose — keep the conservative
+      # AbstractAdapter default (failsafe_error_classes == []). SQLite gives no
+      # sound "container gone" signal: connecting to a dropped file auto-recreates
+      # it empty, so by the time the elevator's rescue runs File.exist? is true
+      # and the only query error is "no such table" (StatementInvalid) — identical
+      # to a missing table in a live tenant, or to a freshly created tenant with
+      # no schema loaded (schema_load_strategy nil). A zero-tables heuristic would
+      # 404 valid-but-empty tenants; there is no authoritative catalog (unlike
+      # pg_database / information_schema) to distinguish dropped from unpopulated.
+      # Auto-create is also load-bearing — create_tenant relies on it — so it
+      # cannot be disabled to force a clean missing-file error. SQLite file-per-
+      # tenant is a dev/test strategy, not a multi-process target, so the
+      # cross-process drop gap this guards barely applies. See the design doc.
+
       protected
 
       def create_tenant(tenant)

data/lib/apartment/cli/migrations.rb

@@ -79,7 +79,7 @@ module Apartment
       end
 
       def rollback_all
-        tenants = Apartment.config.tenants_provider.call
+        tenants = Apartment.tenant_names
         failed = []
         tenants.each do |t|
           rollback_single(t)

data/lib/apartment/cli/seeds.rb

@@ -29,7 +29,7 @@ module Apartment
       end
 
       def seed_all
-        tenants = Apartment.config.tenants_provider.call
+        tenants = Apartment.tenant_names
         failed = []
         tenants.each do |t|
           say("Seeding tenant: #{t}")

data/lib/apartment/cli/tenants.rb

@@ -37,7 +37,7 @@ module Apartment
 
       desc 'list', 'List all tenants'
       def list
-        Apartment.config.tenants_provider.call.each { |t| say(t) }
+        Apartment.tenant_names.each { |t| say(t) }
       end
 
       desc 'current', 'Show current tenant'
@@ -56,7 +56,7 @@ module Apartment
       end
 
       def create_all
-        tenants = Apartment.config.tenants_provider.call
+        tenants = Apartment.tenant_names
         failed = []
         tenants.each do |t|
           say("Creating tenant: #{t}") unless quiet?