ros-apartment 4.0.0.alpha13 → 4.0.0.alpha14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8e5931794be153df0c2443c215f142fa9f07c8e0a0830f5efac616e0c306e58
-  data.tar.gz: e97bbef33052e8bae6a0ce036afc61aeb19a9b1a04895ddcdfb138b5bf89f031
+  metadata.gz: 2bce6584d418fcb45322b27efd6b816c8e33b603866310d9ffabf96e1078a776
+  data.tar.gz: 77d334fc612ff87fa615b2079f2263b8505c84652e966b08b94386061621fcaa
 SHA512:
-  metadata.gz: 362d681d9a275c070521d0f7dff72d8562e3395262df60ea1d61d8a6865956cc700047b5e12a99b132c6a51c41bdaf813592c434f0ca8f10dcdaef65bc876dbb
-  data.tar.gz: 56ab684ddbdc3db9ec820a5b833538fedf3e10ae6358edc0283020cbd352578870d9277620d4fe230b34f13308f2c7d0382c810cba66f2ac8a5d60947ea277a2
+  metadata.gz: 3f73a95f17f83e8034f2a1db98938018d5d1b5e83ec7508720305269b61cdb847c356616d0aa39ea7ad65e42716838c8f243753a14eaf47539ca20fc043ec4c5
+  data.tar.gz: c7626e6a4dfad74516f56be92ee2703e9a19e0cc1b11c525d0803dcb36f918f7bce72d9c68b62c226a712d138dd18ee6e0746ac2333b6b8a05a57a6984e3ab60

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

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,6 +78,16 @@ 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.
@@ -136,7 +147,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,308 @@
+# 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 database it has connected to, times the
+    # timezone variants live against it. One built map
+    # holds ~138 registrations and 88.5 KB of RSS (measured against PostgreSQL
+    # 18 on Rails 8.1). Schema-per-tenant -- the common case, and the one this
+    # patch was written for -- has exactly ONE key for the whole process. Only
+    # database-per-tenant grows, and it grows with the tenants a process
+    # actually serves rather than with time: 570 tenant databases is ~49 MB. 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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apartment
-  VERSION = '4.0.0.alpha13'
+  VERSION = '4.0.0.alpha14'
 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.alpha14
 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