ros-apartment 4.0.0.alpha13 → 4.0.0.alpha15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8e5931794be153df0c2443c215f142fa9f07c8e0a0830f5efac616e0c306e58
-  data.tar.gz: e97bbef33052e8bae6a0ce036afc61aeb19a9b1a04895ddcdfb138b5bf89f031
+  metadata.gz: 894a4e62959833cd9dba2797321b9199ed8269eab4d51fe6744c95d0aef68076
+  data.tar.gz: 1e2dedc54edd54b7058ac7c86c96df47b90d2d4fb3dd62c9aab0293dbb22590a
 SHA512:
-  metadata.gz: 362d681d9a275c070521d0f7dff72d8562e3395262df60ea1d61d8a6865956cc700047b5e12a99b132c6a51c41bdaf813592c434f0ca8f10dcdaef65bc876dbb
-  data.tar.gz: 56ab684ddbdc3db9ec820a5b833538fedf3e10ae6358edc0283020cbd352578870d9277620d4fe230b34f13308f2c7d0382c810cba66f2ac8a5d60947ea277a2
+  metadata.gz: f31685d04741cef165f6bcffcf67db498c520be551ba31c03a8967d74b4c2992163dddd09047240771347cdb6f1ef0beec6311f1779f14f114f365e96600980d
+  data.tar.gz: 841a51484b694620fa04433f0ce8b2fb63afcb9f003b7750c9b9c138703d9193501adc2fe15be3d67f15b72a7bf52e383d00767719ff7014afdd47344db8e44e

data/README.md

@@ -38,7 +38,7 @@ This gem is a maintained fork of the original [Apartment gem](https://github.com
 ### Requirements
 
 - Ruby 3.3+
-- Rails 7.2+
+- Rails 8.1+
 - PostgreSQL 14+, MySQL 8.4+, or SQLite3
 
 ### Ruby version manager
@@ -438,18 +438,20 @@ routed-vs-pinned model and the two-store recipe.
 
 ## Iterating across tenants
 
-v4 keys a connection pool per `"tenant:role"`, so *switching* into a tenant creates a pool. Pick the lightest primitive for the work — the question is **does the block touch per-tenant-schema data?**
+v4 keys a connection pool per `"tenant:role"`, and the pool is created when a query resolves a connection — **not** when `Tenant.switch` sets the tenant. So a switch whose block never touches the tenant database costs nothing, and the question for picking a primitive is **does the block query per-tenant-schema data?**
 
 | Need | Use | v4 cost |
 |---|---|---|
 | Names only (enqueue a job, build a list) | `Apartment.tenant_names.each { ... }` | No switch, no pool created |
-| Per-tenant-schema work (read/write tenant tables) | `Apartment::Tenant.each(release_connection: true) { ... }` | One pool per tenant; released between iterations |
+| Per-tenant-schema work, every tenant | `Apartment::Tenant.each(release_connection: true) { ... }` | One pool per tenant; released between iterations |
+| Per-tenant-schema work, a **subset** | `Apartment::Tenant.each(names, release_connection: true) { ... }` | Same, over the list you pass — no need to hand-roll the `ensure` |
 | Global/pinned data only | Don't switch — read it in the default context | Under shared pinned connections (PG schema, MySQL default), a switch routes pinned/global models *through* the tenant pool |
 
 Rules of thumb:
 
-- **Enqueueing jobs?** Don't switch — pass the tenant as a job argument (`Job.perform_async(tenant: name)`) and let your worker middleware switch when the job runs. Switching only to enqueue spins up a pool for nothing.
+- **Enqueueing jobs?** Pass the tenant as a job argument (`Job.perform_async(tenant: name)`) and let your worker middleware switch when the job runs — the worker needs the name anyway, and the enqueue side stays independent of tenant routing. A switch that only enqueues is *not* itself expensive: the block touches the queue, never the tenant database, so no pool is created.
 - **Only need global/pinned data?** Don't switch. Under shared pinned connections a `switch` resolves pinned and excluded models through the *current tenant's* pool, so reading global data inside a switch still creates a tenant pool.
+- **Iterating some tenants, not all?** `Tenant.each` takes the list as its first argument — `Tenant.each(Account.active.pluck(:tenant_name)) { ... }`. Reach for this instead of writing `names.each { |n| Tenant.switch(n) { ... } }`: it is the gem-native shape, and it puts `release_connection:` within reach for when the next bullet says you need it. Add that flag deliberately rather than by default — it is not a free no-op inside an outer transaction. A hand-rolled loop over such a block leaves one leased connection per visited tenant, which keeps every pool it touches un-evictable and can drive the pool count far past `max_tenant_pools` (see [Pool admission control](docs/designs/pool-admission-control.md)). A block using only modern query methods creates a pool per tenant but no lasting lease, so those pools stay idle and the reaper can trim them. The subset form and `release_connection:` are **v4 API** — v3's `Tenant.each` forwards to the adapter and accepts neither. `Tenant.with_tenants(*names) { ... }` scopes the provider instead, if you want nested calls to see the same subset.
 - **Large fan-out doing real per-tenant work?** Pass `release_connection: true` to `Tenant.each` — it releases connections after each tenant so the reaper can evict finished tenants' pools mid-run. It matters for blocks that hold a connection (raw `ActiveRecord::Base.connection`, an open transaction, a long operation); modern query methods (`create!`, `where`, …) check the connection back in themselves (Rails 7.2+), so a fan-out of only those needs no release. **It releases *every* connection leased to the current thread (`clear_active_connections!(:all)`), so don't use it inside an outer transaction or while holding a connection for non-tenant work.**
 
 ## Convenience Methods

data/lib/apartment/CLAUDE.md

@@ -22,7 +22,8 @@ lib/apartment/
 ├── patches/               # ActiveRecord patches for tenant-aware connections
 │   ├── connection_handling.rb # Prepends on AR::Base — tenant-aware connection_pool
 │   ├── connection_registry.rb # Prepends on AR's PoolManager + ConnectionHandler — serializes the pool registry
-│   └── postgresql_sequence_name.rb # Prepends on the PG adapter — schema-agnostic Model.sequence_name memoization
+│   ├── postgresql_sequence_name.rb # Prepends on the PG adapter — schema-agnostic Model.sequence_name memoization
+│   └── postgresql_type_map.rb # Prepends on the PG adapter — one OID type map per database, shared across tenant pools
 ├── privileges/            # Tenant privilege policy support
 │   └── context.rb         # Privileges::Context: what a tenant_privilege_policy receives, one per phase
 ├── tasks/                 # Rake task utilities; v4.rake for apartment:create/drop/migrate/seed/rollback
@@ -77,10 +78,22 @@ The readers are Rails' own, all reaching the registry through `ConnectionHandler
 
 `serialize!` **fails closed**: it resolves each guarded method with `method_defined?` / `private_method_defined?` (matching what `super` actually needs, so an upstream method merely *moved* to a superclass or module still counts) and raises `Apartment::ConfigurationError` at `activate!` when one is genuinely gone. It only *warns* when upstream has grown a public accessor we do not guard — a hole beats a boot failure. See `docs/designs/ar-connection-registry-thread-safety.md`.
 
+### patches/postgresql_type_map.rb — Shared PostgreSQL Type Map
+
+Rails builds the PostgreSQL OID type map **per connection**: `configure_connection` ends in `reload_type_map`, which clears `@type_map` and runs `initialize_type_map`, and that issues three `pg_type` queries. Two of them have no usable index and sequential-scan `pg_type`, which grows by two rows per table per tenant schema (a composite type and its array type). Pool-per-tenant pays that on every cold tenant pool, so a nightly sweep over hundreds of tenants rebuilds the same map hundreds of times against a catalog hundreds of times larger than a single-schema app's: measured 3.4 ms of type-map queries per connect at 5 schemas, 65 ms at 500 (design: `docs/designs/postgresql-type-map-sharing.md`).
+
+The patch shares one map per **database** (OIDs are database-wide; `search_path`, role and tenant play no part) across every adapter in the process, through two public `:nodoc:` seams identical on Rails 8.1 and main. `clear_cache!(new_connection: true)` is Rails' own "the socket is being replaced" signal, called from `reconnect!`, `disconnect!` and `reset!`; the override nils `@type_map` there, so every path to a new physical connection reaches `reload_type_map` with a nil map. `reload_type_map` with a nil map **adopts** the shared instance from `REGISTRY`, building and publishing with `put_if_absent` if this is the first connection to that database; with a live map, which only the enum DDL helpers reach, it **rebuilds** into a fresh instance and republishes.
+
+The key is `[[host, port, database], [database_oid, postmaster_start_time], default_timezone]` and everything but the timezone comes off the **live connection, never `@config`** — libpq resolves defaults the config cannot show (`dbname` from the user name, a service file, `PGDATABASE`, `hostaddr` without `host`), so two identical-looking configs can reach different databases. The catalog identity costs one query (`pg_database.oid` plus the *epoch* of `pg_postmaster_start_time()`, both world-readable, 0.096 ms; the epoch because a timestamptz renders through the session's `TimeZone`/`DateStyle` and would split one catalog's key) and exists because a name is not a catalog: the patch deliberately survives `clear_cache!`, which is what heals a replaced catalog today, so a different cluster behind an unchanged endpoint (blue/green on logical replication, a restore into the same name) would otherwise be adopted — and fresh catalogs restart type OIDs at 16384, so a stale entry describes a *different* type rather than going unused. The OID alone will not do — `postgres` is OID 5 on every cluster ever initdb'd, so an app on the RDS default database would have a constant check — which is why the start time is in the same SELECT; publishing then supersedes same-endpoint entries carrying a different identity, so restarts do not strand one map each. Within one cluster the OID counter is global and monotonic, so a drop and recreate leaves dead entries, not wrong ones; a promoted physical replica rebuilds once, the accepted cost of fail-closed identity. A failed probe warns, **detaches `@type_map` first** and falls back to upstream — detaching is load-bearing, since upstream's `reload_type_map` clears a live map in place and would blank the shared instance for every other holder. The timezone is in the key because `initialize_type_map` bakes it into the `time`/`timestamp` registrations. A published map is never cleared in place: holders keep resolving against it and adopt the rebuilt one on their next physical reconnect, learning any new OID lazily through `get_oid_type` meanwhile, exactly as a stale per-connection map does today.
+
+Three details are load-bearing. The map is a `SharedTypeMap < HashLookupTypeMap` whose `@mapping` is a `Concurrent::Map`, so lazy OID registrations from one thread are serialized against reads from every other by the same primitive Rails uses for the other half of that object; on MRI a plain Hash would already be safe here, but the argument should not be implicit. No registry lock is held across I/O: the catalog queries run before `put_if_absent`, whose **return value is load-bearing** — the loser of a publish race adopts the winner, so every adapter converges on one instance. And the build writes into the adapter's own `@type_map` before publishing, because `initialize_type_map` loads through the private `type_map` reader rather than its argument; `apply!` **fails closed** (`ConfigurationError`) if that reader or either public seam is gone. Retention is measured rather than bounded: 88.5 KB per map, one key for the whole process under schema-per-tenant, ~49 MB for 570 tenant databases — no eviction ships because a cap tight enough to matter would thrash the nightly sweep it exists to speed up, and eviction stays free to add later. Applied from the gem-load `on_load(:active_record_postgresqladapter)` hook alongside the sequence-name patch, not from `activate!`, because boot opens connections before `activate!` runs and the map they build is the one tenant pools should adopt. `add_pg_decoders` still runs its one index-driven `pg_type` lookup per connection; deliberately untouched. **Rails main** (rails/rails#57013, not in 8.1.x) already ships the built-in OIDs statically and defers the one remaining scan to the first unknown OID per adapter; both seams survive there, `HashLookupTypeMap#initialize` lost its `parent` argument (so `SharedTypeMap` forwards `...`), and the patch's value shrinks to making that deferred scan per process. The integration spec feature-detects `OID::WellKnown` and pends its two connect-time examples on main.
+
 ### pool_reaper.rb — Pool Eviction + Admission
 
 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.
 
+**Admission is the quadratic path, so it does not instrument per candidate.** The scan walks every pool on every cold create; the timer paths walk every pool once per reap cycle. So `protected_pool?` (per-candidate `:skip_evict`, timer only) and `protection_reason` (bare predicate, admission) are split, and admission reports one `skipped: { pinned:, in_use:, default: }` tally on `:cap_unmet` instead — three buckets, because the default tenant's own pools are refused before the protection check and would otherwise vanish from the accounting; `pinned + in_use + default` equals `current` for an *uninterrupted* scan — a candidate whose protection check raises is rescued without being tallied, and the reaper does not take `@create_mutex`, so it can evict between the scan and the count. It also reads `PoolManager#total_pools` rather than `#stats`, which materializes the full key array to answer a count. A measured breach reaching 477 pools emitted ~218k `:skip_evict` events before this. Note that `in_use` means *leased*, not *executing* — a fan-out that never releases reads as saturation while nothing is running; `docs/observability.md` documents the tell.
+
 ### 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). `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`).
@@ -136,7 +149,7 @@ Three hooks in Rails boot order:
 
 `Apartment::MigrationRole.wrap` runs a block inside `connected_to(role: config.ddl_role)`, or yields when no role is configured. It exists as its own module because both `Migrator` and the adapters need it and an adapter cannot depend on `Migrator`; `Migrator.with_migration_role` stays as the documented entry point and delegates here. All tenant DDL goes through it — migrations, `Tenant.create`, and `Tenant.drop`'s engine call — because PostgreSQL scopes an `ALTER DEFAULT PRIVILEGES` rule with no `FOR ROLE` to the role that executed it, and because `DROP SCHEMA` needs ownership of a container `ddl_role` owns. See `docs/designs/v4-rbac-contract.md`.
 
-An unresolvable role is translated here: `ActiveRecord::ConnectionNotEstablished` becomes an `Apartment::ConfigurationError` naming `ddl_role` and the symbol given. `connected_to` resolves no pool — it pushes onto `connected_to_stack` and yields — so the failure arrives from *inside* the block and cannot be detected before it; a wrap whose block never touches the database stays silent by design. What discriminates is not the error class but a probe: `retrieve_connection_pool` for our role, nil meaning the failure is ours to explain and a pool meaning it belongs to the caller's block and re-raises untouched. The rescue names `ConnectionNotEstablished` and **only** that class, because `ConnectionNotDefined` does not exist before Rails 8.0 and Ruby resolves rescue constants at raise time, so naming the subclass raised `NameError` on the Rails floor and destroyed the error it was classifying. No wrapped error still needs translating: `Patches::ConnectionHandling#connection_pool` scopes its relabelling rescue to the tenant-resolution path, so errors do still arrive wrapped from inside it — but those are genuine tenant-pool failures that belong to the tenant rather than to `ddl_role`, and translating them would misattribute. A ddl_role failure is not one of them: it surfaces from the default-path lookup outside that boundary, and the tenant path establishes a pool for the role itself so it never fails on an unregistered one. The `ApartmentError` clause and one-layer unwrap this rescue once carried belonged to the old method-level rescue and went with it. Checked at first use rather than at `activate!`, which runs in `after_initialize`, after the eager-load initializer: under lazy loading no model has run `connects_to` yet and a boot-time check would fail on every boot.
+An unresolvable role is translated here: `ActiveRecord::ConnectionNotEstablished` becomes an `Apartment::ConfigurationError` naming `ddl_role` and the symbol given. `connected_to` resolves no pool — it pushes onto `connected_to_stack` and yields — so the failure arrives from *inside* the block and cannot be detected before it; a wrap whose block never touches the database stays silent by design. What discriminates is not the error class but a probe: `retrieve_connection_pool` for our role, nil meaning the failure is ours to explain and a pool meaning it belongs to the caller's block and re-raises untouched. The rescue names `ConnectionNotEstablished` and **only** that class, even though every supported Rails now raises the `ConnectionNotDefined` subclass here. Narrowing to the subclass would buy nothing — the probe, not the class, decides — and would cost the case the method exists for: a bare `ConnectionNotEstablished` raised inside the caller's block while `ddl_role` is genuinely unregistered would stop getting the message that names `ddl_role`. (History, no longer binding: the subclass did not exist before Rails 8.0, and Ruby resolves rescue constants at raise time, so while 7.2 was supported naming it raised `NameError` and destroyed the error it was classifying.) No wrapped error still needs translating: `Patches::ConnectionHandling#connection_pool` scopes its relabelling rescue to the tenant-resolution path, so errors do still arrive wrapped from inside it — but those are genuine tenant-pool failures that belong to the tenant rather than to `ddl_role`, and translating them would misattribute. A ddl_role failure is not one of them: it surfaces from the default-path lookup outside that boundary, and the tenant path establishes a pool for the role itself so it never fails on an unregistered one. The `ApartmentError` clause and one-layer unwrap this rescue once carried belonged to the old method-level rescue and went with it. Checked at first use rather than at `activate!`, which runs in `after_initialize`, after the eager-load initializer: under lazy loading no model has run `connects_to` yet and a boot-time check would fail on every boot.
 
 ### privileges.rb / privileges/context.rb — Adopter-Owned Privilege Policy
 

data/lib/apartment/migration_role.rb

@@ -38,13 +38,20 @@ module Apartment
     # explain. Non-nil means the role is fine and the error belongs to something the
     # caller did inside the block, so it re-raises untouched.
     #
-    # The probe is the discriminator; the class is only a pre-filter, and on the Rails
-    # floor it cannot filter at all. +ActiveRecord::ConnectionNotDefined+ does not exist
-    # before Rails 8.0 (absent on 7.2.3.1, present on 8.0.5 and 8.1.3), and Ruby
-    # resolves a rescue clause's constants at raise time — so naming it here raised
-    # NameError on 7.2 and destroyed the error it was meant to classify. 7.2 raises
-    # +ConnectionNotEstablished+ for an unregistered role and 8.0+ raises the subclass,
-    # so the superclass alone covers the whole matrix. Do not narrow it back.
+    # The probe is the discriminator; the class is only a pre-filter. The clause names
+    # the +ConnectionNotEstablished+ superclass even though every supported Rails now
+    # raises the +ActiveRecord::ConnectionNotDefined+ subclass here, and that is
+    # deliberate rather than leftover. Narrowing to the subclass would buy nothing —
+    # the probe, not the class, decides — and would cost the case below: a bare
+    # +ConnectionNotEstablished+ raised inside the caller's block while +ddl_role+ is
+    # genuinely unregistered would stop getting the message that names +ddl_role+,
+    # which is the one situation this method exists to explain. Do not narrow it.
+    #
+    # (History, no longer binding: the subclass did not exist before Rails 8.0 — absent
+    # on 7.2.3.1, present on 8.0.5 and 8.1.3 — and Ruby resolves a rescue clause's
+    # constants at raise time, so while 7.2 was supported naming it raised NameError
+    # and destroyed the error it was meant to classify. The 8.1 floor removed that
+    # constraint; it did not change the conclusion.)
     #
     # The cost of the wider clause is that a bare ConnectionNotEstablished from the
     # caller's own code now reaches the probe instead of passing straight through. That

data/lib/apartment/patches/connection_registry.rb

@@ -264,10 +264,13 @@ module Apartment
       # silently taking any shard already registered in it with it. Serializing
       # the whole method makes the upsert atomic.
       #
-      # Wrapped with argument forwarding rather than a reimplementation because
-      # the signature is version-dependent (AR >= 8.0 passes a ConnectionDescriptor
-      # where 7.2 passed the connection-name String) and the key derivation is
-      # upstream's business, not ours.
+      # Wrapped with argument forwarding rather than a reimplementation because the
+      # key derivation is upstream's business, not ours. Across the supported matrix
+      # the signature is currently stable — 8.1 and main both take a
+      # ConnectionDescriptor (verified) — so forwarding buys nothing today. It is
+      # kept because upstream has already changed this argument once: 7.2 passed the
+      # connection-name String and 8.0 replaced it with the descriptor. Forwarding
+      # costs a token and survives the next one.
       #
       # Declared private to match upstream. A prepended method is public by
       # default, and leaving it so would widen a Rails internal into public API

data/lib/apartment/patches/live_tenant_propagation.rb

@@ -7,7 +7,7 @@ module Apartment
     # Backports rails/rails#56902 ("Pass IsolatedExecutionState.context to
     # share_with") to Rails versions where the fix has not landed.
     #
-    # On Rails 7.2 / 8.0 / 8.1.x stable, ActionController::Live#process calls
+    # On Rails 8.1.x stable, ActionController::Live#process calls
     # ActiveSupport::IsolatedExecutionState.share_with(Thread.current, ...)
     # which reads from Thread.current.active_support_execution_state. Under
     # :fiber isolation that's empty — the data lives on Fiber.current's

data/lib/apartment/patches/postgresql_type_map.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+# Referenced in a class body below. Rails requires it from the PostgreSQL
+# adapter file, which an eager-loading host app may not have loaded yet.
+require 'active_record/type/hash_lookup_type_map'
+
+module Apartment
+  module Patches
+    # Shares one PostgreSQL OID type map per database across every adapter in
+    # the process.
+    #
+    # Rails builds the type map per connection: configure_connection ends in
+    # reload_type_map, which clears @type_map and runs initialize_type_map, and
+    # that issues three pg_type queries (load_types_queries). Two of them have
+    # no usable index and sequential-scan pg_type, which grows by two rows per
+    # table per tenant schema. Pool-per-tenant pays that on every cold tenant
+    # pool, so a nightly sweep over hundreds of tenants rebuilds the same map
+    # hundreds of times against a catalog hundreds of times larger than a
+    # single-schema app's. Measured at 65 ms per connect for 500 schemas of
+    # 220 tables. The map is database-scoped (OIDs are), so one instance can
+    # serve every tenant pool. Design: docs/designs/postgresql-type-map-sharing.md.
+    #
+    # Two public :nodoc: seams, identical on Rails 8.1 and main:
+    #
+    # * clear_cache!(new_connection: true) is Rails' own "the socket is being
+    #   replaced, drop connection-derived caches" signal, called from reconnect!,
+    #   disconnect! and reset!. We drop @type_map there, so every path to a new
+    #   physical connection reaches reload_type_map with a nil map.
+    # * reload_type_map with a nil map ADOPTS the shared instance (building and
+    #   publishing it if this is the first connection to that database); with a
+    #   live map it REBUILDS into a fresh instance and republishes. The live-map
+    #   callers upstream are the enum DDL helpers and disable_extension. A
+    #   published map is
+    #   never cleared in place: other holders keep resolving against it and pick
+    #   up the rebuilt one on their next physical reconnect, learning any new
+    #   OID lazily through get_oid_type meanwhile, exactly as a stale
+    #   per-connection map does today.
+    #
+    # The build writes into this adapter's own @type_map before publishing
+    # because initialize_type_map loads through the private +type_map+ reader,
+    # not its argument (load_additional_types constructs
+    # TypeMapInitializer.new(type_map)). Both that reader and
+    # initialize_type_map are checked by apply!, which refuses to boot without
+    # either.
+    #
+    # RETENTION, measured rather than bounded. An entry is removed only when a
+    # later publish supersedes it (see #apartment_supersede_stale_identities),
+    # so a process retains one map per KEY it has built against, and the key is
+    # [[host, port, database], identity, timezone] -- not the database alone. A
+    # :reading role on a replica is a different endpoint and carries its own
+    # map for the same catalog, so multiply by distinct endpoints, usually the
+    # number of roles. (Timezone splits nothing in practice: tenant configs
+    # derive from one base config.) One built map holds ~138 registrations and
+    # 88.5 KB of RSS (measured against PostgreSQL 18 on Rails 8.1) against a
+    # catalog carrying only built-in enums, domains and ranges -- a BASELINE,
+    # not a constant. The second load query has no namespace filter, so a map
+    # holds the built-ins plus every such type in the catalog it was built
+    # against, and pg_type is per-DATABASE, so the strategy decides only how
+    # tenant-defined types distribute. Schema-per-tenant -- the common case,
+    # and the one this patch was written for -- has one key per endpoint
+    # however many tenants there are, and that single map carries every
+    # tenant's types (138 + tenants x types-per-schema). Database-per-tenant
+    # splits the same types across maps: each carries 138 + its own tenant's,
+    # so COUNT grows with tenants, cumulatively -- supersede fires only for one
+    # endpoint under a different identity, so a dropped database leaves its
+    # entry for the life of the process. 570 tenant databases is ~49 MB of
+    # baseline per endpoint, plus whatever those tenants define. See docs/designs/postgresql-type-map-sharing.md. No
+    # eviction policy ships because a cap tight enough to bound that
+    # meaningfully is also tight enough to thrash the nightly sweep it exists to
+    # speed up, which is the deployment that has the problem in the first place.
+    # Eviction is semantically free if that ever changes -- dropping an entry
+    # only costs the next cold connection one rebuild, which is the unpatched
+    # behaviour -- so a bound can land later with no correctness migration.
+    # +reset!+ is the escape hatch in the meantime.
+    module PostgresqlTypeMap
+      # HashLookupTypeMap whose mapping is a Concurrent::Map.
+      #
+      # Upstream keeps @mapping in a plain Hash because one connection owns it.
+      # Shared, it sees lock-free reads from every thread and occasional writes
+      # from lazy OID registration. On MRI a plain Hash would already be safe
+      # here (single C calls, no Ruby-level iteration in this class, Integer and
+      # String keys), but the argument should not be implicit: Concurrent::Map
+      # is the primitive Rails already uses for the other half of this object,
+      # and every operation the adapter and TypeMapInitializer perform on the
+      # store ([]=, fetch(key, default), key?, keys, clear) exists on it with the
+      # same semantics.
+      class SharedTypeMap < ActiveRecord::Type::HashLookupTypeMap
+        # Forwards whatever it is given: 8.1 takes an optional parent, Rails main
+        # takes nothing, and the adapter passes nothing on either. The forwarding is
+        # what spans the two SUPPORTED lanes -- not a shim for a dropped Rails.
+        def initialize(...)
+          super
+          @mapping = Concurrent::Map.new
+        end
+      end
+
+      # [[host, port, database], [database_oid, postmaster_start_time],
+      # default_timezone] => SharedTypeMap. Nested so the endpoint and the
+      # catalog incarnation stay separable: #apartment_supersede_stale_identities
+      # needs exactly that distinction. Everything but the timezone is read off
+      # the live connection rather than @config -- see #apartment_type_map_key.
+      # Timezone is part of the key because initialize_type_map bakes
+      # @default_timezone into the time and timestamp registrations (verified on
+      # 8.1 and main).
+      REGISTRY = Concurrent::Map.new
+
+      # Identity of the catalog behind the endpoint name, in one round trip.
+      #
+      # The database OID alone is NOT enough, which a probe settles rather than
+      # an argument: template1, template0 and postgres hold OIDs 1, 4 and 5 on
+      # every cluster ever initdb'd, so an app whose database is `postgres` --
+      # the RDS default -- would have an identity check that evaluates to a
+      # constant. Freshly provisioned clusters also hand the first user database
+      # the same OID, 16384, so identical provisioning collides too. Neither
+      # needs a pooler or any exotic topology; a plain endpoint swap is enough.
+      # pg_postmaster_start_time() closes both: two live clusters disagree on it
+      # with near-certainty.
+      #
+      # Both are world-readable and need no privilege, unlike
+      # pg_control_system() and pg_control_checkpoint(), which are superuser-only
+      # by default. Everything is schema-qualified because an unqualified name
+      # can resolve to a temporary relation or an earlier entry in search_path.
+      # Measured at 0.049 ms of execution, 0.096 ms including the round trip,
+      # against 1.9 ms for a full type-map load on a 647-row pg_type and ~24 ms
+      # on a 281,927-row one.
+      # EXTRACT(EPOCH FROM ...) rather than the timestamptz itself, because the
+      # value is read as text and a timestamptz renders through the session's
+      # TimeZone and DateStyle. Two connection classes to the SAME catalog that
+      # differ in those (a per-role `ALTER ROLE ... SET TimeZone` with no
+      # explicit `variables` entry, say) would produce different identity
+      # strings, split the key, and set the supersede rule below ping-ponging --
+      # sharing quietly switching itself off, with no wrong data and no warning
+      # to explain it. A numeric epoch depends on neither GUC.
+      DATABASE_IDENTITY_SQL = <<~SQL.squish
+        SELECT d.oid, EXTRACT(EPOCH FROM pg_catalog.pg_postmaster_start_time())
+        FROM pg_catalog.pg_database d
+        WHERE d.datname = pg_catalog.current_database()
+      SQL
+
+      PUBLIC_SEAMS = %i[reload_type_map clear_cache!].freeze
+      PRIVATE_SEAMS = %i[initialize_type_map type_map].freeze
+
+      class << self
+        # FAILS CLOSED on a shape we cannot patch, for the same reason
+        # ConnectionRegistry does: the failure this patch prevents is database
+        # saturation during the nightly sweep, which is far harder to attribute
+        # than a boot error naming the ActiveRecord version. Resolution uses
+        # method_defined? so a seam that merely moved to a superclass still
+        # counts. Prepend is idempotent, so apply! may run more than once.
+        def apply!(adapter_class)
+          missing = PUBLIC_SEAMS.reject { |name| adapter_class.method_defined?(name) } +
+                    PRIVATE_SEAMS.reject { |name| adapter_class.private_method_defined?(name) }
+
+          unless missing.empty?
+            raise(Apartment::ConfigurationError,
+                  'Apartment cannot share the PostgreSQL type map on ActiveRecord ' \
+                  "#{ActiveRecord::VERSION::STRING}: expected method(s) #{missing.join(', ')} " \
+                  'are gone. Without them every cold tenant pool reloads the OID type map ' \
+                  'from pg_type. Upgrade ros-apartment to a version that supports this ' \
+                  'ActiveRecord release.')
+          end
+
+          adapter_class.prepend(self)
+          nil
+        end
+
+        # Forget every shared map. The next connection to each database rebuilds.
+        # A test hook for suites that need a cold start, and the escape hatch for
+        # an adopter who wants the retention described above reclaimed. Not a
+        # configuration knob.
+        def reset!
+          REGISTRY.clear
+        end
+      end
+
+      def clear_cache!(new_connection: false)
+        super
+        @type_map = nil if new_connection
+      end
+
+      def reload_type_map
+        @lock.synchronize do
+          key = apartment_type_map_key
+
+          # No identity we can trust, so fall back to upstream's per-connection
+          # map: sharing under an identity we could not confirm is the one thing
+          # this must never do. Detaching first is load-bearing rather than
+          # tidy -- upstream's reload_type_map CLEARS a live @type_map in place,
+          # and if this adapter had already adopted the shared instance that
+          # would blank the map every other holder is resolving against, which
+          # is the invariant the whole design rests on.
+          if key.nil?
+            @type_map = nil
+            return super
+          end
+
+          if @type_map.nil?
+            @type_map = REGISTRY[key] || apartment_publish_type_map(key)
+          else
+            REGISTRY[key] = apartment_build_type_map
+          end
+        end
+      end
+
+      private
+
+      # Ask the live connection, never @config, and ask the server which catalog
+      # it actually is.
+      #
+      # Two different failures make @config alone the wrong source. First, libpq
+      # fills in defaults the configuration hash cannot show -- dbname
+      # defaulting to the user name, a service file, PGHOST/PGPORT/PGDATABASE,
+      # hostaddr given without host -- so two adapters whose configs look
+      # identical can land on different databases. PQhost, PQport and PQdb are
+      # client-side reads of the RESOLVED parameters (measured ~0.06 us each)
+      # and close all of that; PQhost reports hostaddr when only hostaddr was
+      # given.
+      #
+      # Second, and the reason for the query: a name is not a catalog. This
+      # patch deliberately survives +clear_cache!(new_connection: true)+, which
+      # is Rails' "the socket is being replaced, drop what you cached" signal,
+      # and that signal is exactly what heals a replaced catalog today. Put a
+      # different cluster behind an unchanged endpoint -- an RDS blue/green
+      # cutover on logical replication, a restore into the same name -- and
+      # every connection drops, every adapter reconnects, and without this each
+      # one would adopt the old catalog's map. Type OIDs in a fresh catalog
+      # restart at 16384, so a stale registration does not merely go unused: it
+      # can describe a DIFFERENT type that now holds its OID, and an enum gets
+      # cast as a domain with nothing raised. (A promoted physical replica is
+      # not affected either way -- its catalog is byte-identical, so the OIDs
+      # still agree.) Within one cluster the OID counter is global and
+      # monotonic, verified by probe, so a same-cluster drop and recreate leaves
+      # dead entries rather than wrong ones; it is the cross-cluster case this
+      # closes.
+      #
+      # The identity read runs on the raw connection rather than through the
+      # adapter: it must not recurse into the type map it is about to resolve,
+      # and PQexec's arity does not drift across the Rails versions this gem
+      # supports. Any PG error means we could not establish identity, so we do
+      # not share.
+      #
+      # A pooler whose single alias fans out across several databases, or across
+      # clusters, IS caught: every resolved libpq parameter names the pooler, but
+      # the identity query travels to the backend. What no connect-time check of
+      # any kind can see is a pooler that moves a live client connection onto a
+      # different cluster without configure_connection running again.
+      def apartment_type_map_key
+        raw = @raw_connection
+        return nil unless raw
+
+        [[raw.host, raw.port, raw.db], apartment_database_identity(raw), @default_timezone]
+      rescue PG::Error => e
+        # Sharing silently switching itself off has no symptom beyond "the
+        # nightly got slow again", so leave evidence. Rescuing rather than
+        # raising keeps a probe failure from breaking a connection that is
+        # otherwise fine; the cost is one rebuilt map.
+        warn('[Apartment] could not identify the database for type-map sharing ' \
+             "(#{e.class}: #{e.message.lines.first&.strip}); this connection builds its own map.")
+        nil
+      end
+
+      # Block form so the PG::Result is freed at once instead of waiting for GC.
+      def apartment_database_identity(raw)
+        raw.exec(DATABASE_IDENTITY_SQL) { |result| [result.getvalue(0, 0), result.getvalue(0, 1)] }
+      end
+
+      # put_if_absent rather than compute_if_absent: the build runs catalog
+      # queries on this connection, and no registry lock is held across that
+      # I/O. A lost race costs one redundant build, which is today's cost once.
+      # Returning the WINNER is load-bearing -- the loser adopts it and drops its
+      # own build, so every adapter converges on one instance.
+      def apartment_publish_type_map(key)
+        built = apartment_build_type_map
+        published = REGISTRY.put_if_absent(key, built) || built
+        apartment_supersede_stale_identities(key)
+        published
+      end
+
+      # Drop entries for the same endpoint under a DIFFERENT catalog incarnation.
+      #
+      # Without this, putting the postmaster's start time in the key would trade
+      # one unbounded growth for another: every database restart would strand an
+      # entry per database, forever, which is growth in TIME rather than in
+      # tenants. A superseded entry can never be adopted again -- its identity
+      # will not recur -- so removing it costs nothing, and the worst case if an
+      # endpoint is flipped back is one rebuild, which is the unpatched
+      # behaviour. Timezone variants of the same live catalog share an endpoint
+      # AND an identity, so they survive; only the identity slice discriminates.
+      #
+      # Keys are collected before deleting rather than deleted mid-iteration.
+      #
+      # Two publishers for the same endpoint under DIFFERENT identities can each
+      # delete the other's entry, leaving the registry empty for that endpoint.
+      # Harmless, and deliberately uncoordinated: it takes both incarnations
+      # reachable at once (a cutover window), every live adapter holds its map by
+      # reference, adoption is keyed by the identity the adopting connection
+      # measured on its own socket, and losing costs one rebuild -- the unpatched
+      # behaviour. Superseding before the publish has the symmetric race, so
+      # there is nothing to buy.
+      def apartment_supersede_stale_identities(key)
+        endpoint, identity = key
+        stale = REGISTRY.keys.select { |other| other[0] == endpoint && other[1] != identity }
+        stale.each { |other| REGISTRY.delete(other) }
+      end
+
+      def apartment_build_type_map
+        @type_map = SharedTypeMap.new
+        # Parity with upstream's own reload, which clears this before
+        # reinitialising. It exists only on Rails main, where it records whether
+        # this adapter has run the deferred bulk pg_type query; the assignment is
+        # inert on 8.1, where nothing reads it. Without it a rebuilt
+        # map would skip the bulk half of the next deferred load -- still
+        # correct, since the specific OID is always requested, but less than
+        # upstream promises.
+        @type_map_queried = false
+        initialize_type_map
+        @type_map
+      end
+    end
+  end
+end

data/lib/apartment/pool_manager.rb

@@ -124,11 +124,19 @@ module Apartment
         .map(&:first)
     end
 
+    # O(1) pool count. Separate from #stats because the admission path asks for
+    # the count on every cold create, and #stats answers by materializing the
+    # full key array — garbage proportional to the pool count, at exactly the
+    # moment the pool count is the problem.
+    def total_pools
+      @pools.size
+    end
+
     # Basic stats. Full observability (per-tenant breakdown, connection
     # counts, eviction counters) deferred to Phase 3.
     def stats
       {
-        total_pools: @pools.size,
+        total_pools: total_pools,
         tenants: @pools.keys,
       }
     end

data/lib/apartment/pool_reaper.rb

@@ -61,13 +61,18 @@ module Apartment
     def admit!(incoming_tenant_key)
       return unless @max_total
 
+      # Reset per scan: the tally that matters is the one from the pass that
+      # gave up, not a sum over passes that each evicted something.
+      skipped = nil
       loop do
-        break if @pool_manager.stats[:total_pools] < @max_total
-        break unless evict_one_for_admission(incoming_tenant_key)
+        break if @pool_manager.total_pools < @max_total
+
+        skipped = { pinned: 0, in_use: 0, default: 0 }
+        break unless evict_one_for_admission(incoming_tenant_key, skipped)
       end
-      return if @pool_manager.stats[:total_pools] < @max_total
+      return if @pool_manager.total_pools < @max_total
 
-      apply_overflow_policy
+      apply_overflow_policy(skipped)
     end
 
     def start
@@ -156,11 +161,32 @@ module Apartment
     # Evict the single LRU evictable pool to make room for an incoming one,
     # skipping the incoming key, the default tenant, and pinned/in-use pools.
     # Returns the evicted tenant key, or nil if nothing is evictable.
-    def evict_one_for_admission(incoming_tenant_key)
-      @pool_manager.lru_tenants(count: @pool_manager.stats[:total_pools]).each do |tenant|
+    #
+    # Tallies protected candidates into +skipped+ instead of emitting a
+    # per-candidate :skip_evict. This scan walks every pool and runs on every
+    # cold create, so a per-candidate event is quadratic in the pool count: a
+    # measured breach that reached 477 pools emitted ~218k of them, each one
+    # eagerly walking that pool's connection array twice to build a payload.
+    # The aggregate lands on :cap_unmet once per admission instead. The timer
+    # paths keep their per-candidate events — there the scan is once per reap
+    # cycle, and "this tenant has been skipped for N cycles" is the signal.
+    def evict_one_for_admission(incoming_tenant_key, skipped)
+      @pool_manager.lru_tenants(count: @pool_manager.total_pools).each do |tenant|
         next if tenant == incoming_tenant_key
-        next if default_tenant_pool?(tenant)
-        next if protected_pool?(tenant, eviction_reason: :admission)
+
+        # Tallied, not silently skipped: a breach caused entirely by default
+        # pools would otherwise report "nothing protected" beside a cap that
+        # could not be met. The three buckets plus the incoming key account
+        # for every candidate the scan saw.
+        if default_tenant_pool?(tenant)
+          skipped[:default] += 1
+          next
+        end
+
+        if (reason = protection_reason(@pool_manager.peek(tenant)))
+          skipped[reason] += 1
+          next
+        end
 
         evict_tenant(tenant, reason: :admission)
         return tenant
@@ -174,18 +200,20 @@ module Apartment
     # or in use). :evict_idle degrades to a soft cap — allow the new pool, surface
     # the breach via :cap_unmet. :raise fails the admission so the caller sheds
     # load. See docs/designs/pool-admission-control.md.
-    def apply_overflow_policy
-      current = @pool_manager.stats[:total_pools]
+    def apply_overflow_policy(skipped = nil)
+      current = @pool_manager.total_pools
       case @overflow_policy
       when :raise
         raise(Apartment::PoolCapacityReached.new(max_total: @max_total, current: current))
       else
-        Instrumentation.instrument(:cap_unmet, max_total: @max_total, current: current, unevicted: 1)
+        payload = { max_total: @max_total, current: current, unevicted: 1 }
+        payload[:skipped] = skipped if skipped
+        Instrumentation.instrument(:cap_unmet, payload)
       end
     end
 
     def evict_lru
-      total = @pool_manager.stats[:total_pools]
+      total = @pool_manager.total_pools
       excess = total - @max_total
       return 0 if excess <= 0
 
@@ -231,15 +259,20 @@ module Apartment
     # protected. Used as a single guard for both eviction paths.
     def protected_pool?(tenant, eviction_reason:)
       pool = @pool_manager.peek(tenant)
-      if pool_pinned?(pool)
-        instrument_skip(reason: :pinned, tenant: tenant, eviction_reason: eviction_reason, pool: pool)
-        return true
-      end
-      if pool_in_use?(pool)
-        instrument_skip(reason: :in_use, tenant: tenant, eviction_reason: eviction_reason, pool: pool)
-        return true
-      end
-      false
+      return false unless (reason = protection_reason(pool))
+
+      instrument_skip(reason: reason, tenant: tenant, eviction_reason: eviction_reason, pool: pool)
+      true
+    end
+
+    # Why this pool cannot be evicted right now (:pinned / :in_use), or nil when
+    # it can. Split out of protected_pool? so the admission scan can classify a
+    # candidate without paying for instrumentation — see evict_one_for_admission.
+    def protection_reason(pool)
+      return :pinned if pool_pinned?(pool)
+      return :in_use if pool_in_use?(pool)
+
+      nil
     end
 
     # Instance-side wrapper around the class predicate; kept for callers

data/lib/apartment/version.rb

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

data/lib/apartment.rb

@@ -545,14 +545,17 @@ module Apartment # rubocop:disable Metrics/ModuleLength
   end
 end
 
-# Prepend the sequence-name patch whenever the PostgreSQL adapter loads
+# Prepend the PostgreSQL adapter patches whenever the 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.
+# activate! because both fire before activate! can: ActiveRecord memoizes
+# Model.sequence_name at first touch, and boot opens connections (schema cache,
+# pending-migration check) whose type map the tenant pools should then adopt.
+# No-op for apps that never load the PostgreSQL adapter, so MySQL/SQLite
+# consumers never pull in pg. See each patch file for the full rationale.
 ActiveSupport.on_load(:active_record_postgresqladapter) do
   prepend(Apartment::Patches::PostgresqlSequenceName)
+
+  Apartment::Patches::PostgresqlTypeMap.apply!(self)
 end
 
 # Load Railtie when Rails is present (standard gem convention).

data/ros-apartment.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '>= 3.3'
 
-  s.add_dependency('activerecord',    '>= 7.2.0', '< 8.2')
+  s.add_dependency('activerecord',    '>= 8.1.0', '< 8.2')
   s.add_dependency('activesupport',   '>= 7.2.0', '< 8.2')
   s.add_dependency('concurrent-ruby', '>= 1.3.0')
   s.add_dependency('parallel',        '>= 1.26.0')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ros-apartment
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha13
+  version: 4.0.0.alpha15
 platform: ruby
 authors:
 - Ryan Brunner
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.2.0
+        version: 8.1.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
@@ -28,7 +28,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.2.0
+        version: 8.1.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
@@ -199,6 +199,7 @@ files:
 - lib/apartment/patches/connection_registry.rb
 - lib/apartment/patches/live_tenant_propagation.rb
 - lib/apartment/patches/postgresql_sequence_name.rb
+- lib/apartment/patches/postgresql_type_map.rb
 - lib/apartment/pool_manager.rb
 - lib/apartment/pool_observer.rb
 - lib/apartment/pool_reaper.rb