ros-apartment 4.0.0.alpha4 → 4.0.0.alpha6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86ded64305e44aac057b97264c079d5090545b7d1740693ea1cf7c881b69fe19
-  data.tar.gz: 99e78891808ff4cdb1e0fef82f7c49a344a4c088408c9c143af465c70a150a3b
+  metadata.gz: 7ce0a7124b9df22be74f2899b8a38046f52fcd7e1e0b068b3ebd778e16f57969
+  data.tar.gz: 0f40a39d073ae13bd59dce2e72e3e2aaa3759f2ffc270491f6dbbfcc7ef623fe
 SHA512:
-  metadata.gz: 6a80e29d57f2d4d4de7cd41666b3cef737720cceb782c3d6a34f5522dec0a6ec3fc04e41ba1a45761eabfee5bee5f5b0d2d80d2ae79d1c43f8d905906d7dc1d3
-  data.tar.gz: a4c460e9ec3c2214e1a52fd399bf0038a6da1d43c66a20fbd97a31ceb6ac44b4595592eec41f0310cfc51f99e5b6699420332fa816a177865479af1772dea928
+  metadata.gz: ebbc9775707e60c7e7bd896e6f1efa02487017519770dda6558cd89552e53558f47a39df31b73f4c90f6c7039e86399536ce586ce1bd30ac263ad67071c7407a
+  data.tar.gz: 8339cc7eb7b07adcb5df1f923c55f7e3aa96bad5faa47a13975550563af0d77191736b4afe0a8aa97f6a446adc59cc148a21739ff0c36224d3608371e6a0efe0

data/lib/apartment/adapters/abstract_adapter.rb

@@ -23,10 +23,17 @@ module Apartment
       # Called by ConnectionHandling — subclasses should NOT override this.
       # base_config_override: when supplied (e.g. a role-specific config from ConnectionHandling),
       # the adapter builds the tenant config on top of it instead of its own base_config.
+      #
+      # This validates only the PHYSICAL identifier (engine rules). Raw pool-key
+      # safety (colon/whitespace/NUL that would corrupt "tenant:role") is enforced
+      # by the sole production caller, ConnectionHandling#connection_pool, before
+      # it builds the pool key — and independently by #create. A future caller
+      # that invokes this directly, bypassing connection_pool, must validate the
+      # raw tenant itself (TenantNameValidator.validate_common!).
       def validated_connection_config(tenant, base_config_override: nil)
         effective_base = base_config_override || base_config
         TenantNameValidator.validate!(
-          tenant,
+          physical_tenant_name(tenant),
           strategy: Apartment.config.tenant_strategy,
           adapter_name: effective_base['adapter']
         )
@@ -41,9 +48,13 @@ module Apartment
       end
 
       # Create a new tenant (schema or database).
+      # Validates the physical identifier create_tenant actually addresses
+      # (raw schema name for :schema, environmentified database name otherwise),
+      # so create and the pool-resolution path validate the same name.
       def create(tenant)
+        validate_pool_key_safety!(tenant)
         TenantNameValidator.validate!(
-          environmentify(tenant),
+          physical_tenant_name(tenant),
           strategy: Apartment.config.tenant_strategy,
           adapter_name: base_config['adapter']
         )
@@ -199,11 +210,34 @@ module Apartment
         end
       end
 
+      # The physical identifier used to address this tenant at connection time:
+      # the database name for database-per-tenant strategies (environmentified).
+      # validated_connection_config validates THIS name so the pool-resolution
+      # path agrees with what the connection actually targets. Schema-per-tenant
+      # overrides this to the raw tenant (schemas are named directly).
+      def physical_tenant_name(tenant)
+        environmentify(tenant)
+      end
+
       # Default tenant from config.
       def default_tenant
         Apartment.config.default_tenant
       end
 
+      private
+
+      # Validate the raw tenant for pool-key safety: it becomes "#{tenant}:#{role}"
+      # in the pool key, so a colon / whitespace / NUL there breaks PoolManager's
+      # prefix and suffix matching and could evict the wrong tenant's pool.
+      # Validated in addition to physical_tenant_name (which carries the engine
+      # rules) because a callable environmentify_strategy could transform an
+      # unsafe character out of the physical name while the raw name still reaches
+      # the pool key. to_s first so a non-String tenant is stringified, not
+      # rejected (it is the value the pool key interpolates anyway).
+      def validate_pool_key_safety!(tenant)
+        TenantNameValidator.validate_common!(tenant.to_s)
+      end
+
       protected
 
       def create_tenant(tenant)

data/lib/apartment/adapters/postgresql_schema_adapter.rb

@@ -38,6 +38,12 @@ module Apartment
         config.merge('schema_search_path' => search_path)
       end
 
+      # Schemas are named directly (never environmentified), so the physical
+      # identifier validated at pool-resolution time is the raw tenant name.
+      def physical_tenant_name(tenant)
+        tenant.to_s
+      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

data/lib/apartment/cli/tenants.rb

@@ -29,7 +29,7 @@ module Apartment
       DESC
       method_option :force, type: :boolean, desc: 'Skip confirmation prompt'
       def drop(tenant)
-        return say('Cancelled.') if !force? && !yes?("Drop tenant '#{tenant}'? This cannot be undone. [y/N]")
+        return unless confirmed_destructive?(tenant)
 
         Apartment::Tenant.drop(tenant)
         say("Dropped tenant: #{tenant}") unless quiet?
@@ -77,6 +77,28 @@ module Apartment
         options[:force] || ENV['APARTMENT_FORCE'] == '1'
       end
 
+      # Whether the irreversible drop may proceed. --force / APARTMENT_FORCE=1
+      # is the explicit opt-in. On a TTY we prompt [y/N]. In a non-interactive
+      # context (deploy/cron/CI, binstub, rake) we cannot prompt: rather than
+      # let Thor's yes? read EOF as "no" — a silent cancel that still exits 0 —
+      # or block on $stdin.gets against an open-but-empty pipe, refuse loudly
+      # with a non-zero exit. Centralizing it here (not in the rake wrapper)
+      # covers every entry point uniformly. See issue #457.
+      def confirmed_destructive?(tenant)
+        return true if force?
+
+        unless $stdin.tty?
+          raise(Thor::Error,
+                'apartment tenants drop is destructive and cannot prompt in a ' \
+                'non-interactive context. Re-run with --force or APARTMENT_FORCE=1 to proceed.')
+        end
+
+        return true if yes?("Drop tenant '#{tenant}'? This cannot be undone. [y/N]")
+
+        say('Cancelled.')
+        false
+      end
+
       def quiet?
         options[:quiet] || ENV['APARTMENT_QUIET'] == '1'
       end

data/lib/apartment/migrator.rb

@@ -6,6 +6,11 @@ require_relative 'errors'
 
 module Apartment
   class Migrator # rubocop:disable Metrics/ClassLength
+    # ActiveRecord exposes no public setter for advisory-lock state (only the
+    # advisory_locks_enabled? reader), so we toggle this private ivar directly.
+    # The guard in with_advisory_locks_disabled detects a future Rails rename.
+    ADVISORY_LOCKS_IVAR = :@advisory_locks_enabled
+
     Result = Data.define(
       :tenant,
       :status,
@@ -213,13 +218,28 @@ module Apartment
     # Disable advisory locks on the leased connection for the duration of the
     # block, then restore the original value. lease_connection returns the same
     # connection object for the current thread (fiber-local via IsolatedExecutionState).
+    #
+    # PG's advisory locks are database-wide and would serialize parallel tenant
+    # migrations (issue #298). Rails offers no public setter, so we poke the
+    # private @advisory_locks_enabled ivar. The instance_variable_defined? guard
+    # detects a future Rails *rename or removal* of the ivar (a name-presence
+    # check — it does NOT catch a semantics change where Rails keeps the ivar but
+    # stops honoring it on the lock path). On a detected rename we warn and
+    # proceed rather than silently creating an orphan ivar; the ivar contract is
+    # also unit-tested against a real connection so a rename breaks CI first.
     def with_advisory_locks_disabled
       conn = ActiveRecord::Base.lease_connection
-      original = conn.instance_variable_get(:@advisory_locks_enabled)
-      conn.instance_variable_set(:@advisory_locks_enabled, false)
+      unless conn.instance_variable_defined?(ADVISORY_LOCKS_IVAR)
+        warn "[Apartment::Migrator] ActiveRecord connection #{conn.class} does not define " \
+             "#{ADVISORY_LOCKS_IVAR}; cannot disable advisory locks for this Rails version. " \
+             'Parallel tenant migrations may serialize or fail on the database-wide advisory lock.'
+        return yield
+      end
+      original = conn.instance_variable_get(ADVISORY_LOCKS_IVAR)
+      conn.instance_variable_set(ADVISORY_LOCKS_IVAR, false)
       yield
     ensure
-      conn&.instance_variable_set(:@advisory_locks_enabled, original)
+      conn.instance_variable_set(ADVISORY_LOCKS_IVAR, original) if conn&.instance_variable_defined?(ADVISORY_LOCKS_IVAR)
     end
 
     def monotonic_now

data/lib/apartment/patches/connection_handling.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'active_record'
+require_relative '../tenant_name_validator'
 
 module Apartment
   module Patches
@@ -28,6 +29,15 @@ module Apartment
           return super
         end
 
+        # Reject pool-key-unsafe tenant names BEFORE building pool_key or entering
+        # fetch_or_create. In the capped path, fetch_or_admit runs admit! (which
+        # may LRU-evict an idle pool) before the adapter validates inside the
+        # block, so a colon / whitespace / NUL in the raw tenant — which would
+        # also corrupt the "#{tenant}:#{role}" key and PoolManager's prefix
+        # matching — must be caught here. ConfigurationError is an ApartmentError,
+        # so the rescue below re-raises it cleanly.
+        Apartment::TenantNameValidator.validate_common!(tenant.to_s)
+
         role = ActiveRecord::Base.current_role
         pool_key = "#{tenant}:#{role}"
 
@@ -109,7 +119,13 @@ module Apartment
         cache_path = Apartment::SchemaCache.cache_path_for(tenant)
         return unless File.exist?(cache_path)
 
-        pool.schema_cache.load!(cache_path)
+        # Bind the pool's reflection to the dump file (Rails 7.1+ API). The
+        # removed path-taking SchemaCache#load! raised ArgumentError here:
+        # pool.schema_cache returns a BoundSchemaReflection whose #load! takes
+        # no args. SchemaReflection.new(path) lazily loads the dump (and Rails
+        # version-checks it, ignoring a stale file with a warning).
+        pool.schema_reflection =
+          ActiveRecord::ConnectionAdapters::SchemaReflection.new(cache_path)
       end
     end
   end

data/lib/apartment/pool_observer.rb

@@ -24,7 +24,18 @@ module Apartment
     def self.install!(sink:, sample_interval: nil, backend_count: nil)
       observer = new(sink: sink, backend_count: backend_count)
       observer.subscribe!
-      observer.start_sampler!(interval: sample_interval) if sample_interval&.positive?
+      if sample_interval.nil?
+        # nil is the intentional "no gauge sampler" signal; counters still flow.
+      elsif sample_interval.positive?
+        observer.start_sampler!(interval: sample_interval)
+      else
+        # A non-nil, non-positive interval is almost always a misconfig (e.g. an
+        # empty APARTMENT_POOL_SAMPLE_INTERVAL coerced to 0). Silently skipping
+        # the sampler ships an observer whose gauges never emit; surface it.
+        warn "[Apartment::PoolObserver] sample_interval=#{sample_interval.inspect} is not " \
+             'positive; gauge sampler not started (tenant_pools_live/backend_connections ' \
+             'will not emit). Pass a positive interval, or nil to disable the sampler.'
+      end
       observer
     rescue StandardError
       # Don't leak subscriptions if a later step (e.g. a bad sample_interval)

data/lib/apartment/tasks/v4.rake

@@ -15,7 +15,16 @@ namespace :apartment do
   desc 'Drop a tenant schema/database'
   task :drop, [:tenant] => :environment do |_t, args|
     abort('Usage: rake apartment:drop[tenant_name]') unless args[:tenant]
-    Apartment::CLI::Tenants.new.invoke(:drop, [args[:tenant]], force: true)
+    # Plain delegate: Apartment::CLI::Tenants#drop owns the confirmation policy
+    # (TTY prompts [y/N]; non-interactive requires --force / APARTMENT_FORCE=1,
+    # otherwise raises Thor::Error). The rake wrapper adds no force handling of
+    # its own. It only reformats the guard error: `.new.invoke` bypasses
+    # Thor.start's exit_on_failure? handling, so an unrescued Thor::Error would
+    # surface as a raw `rake aborted!` backtrace that buries the actionable
+    # message — abort re-emits it as a clean one-liner with a non-zero exit.
+    Apartment::CLI::Tenants.new.invoke(:drop, [args[:tenant]])
+  rescue Thor::Error => e
+    abort(e.message)
   end
 
   desc 'Run migrations for all tenants (or one: rake apartment:migrate[tenant])'

data/lib/apartment/tenant.rb

@@ -200,17 +200,29 @@ module Apartment
       # it drops EVERY connection leased to the current execution context, across
       # all pools and roles, not just the tenant pool. Do NOT use it inside an
       # outer ActiveRecord::Base.transaction, or while holding a non-tenant
-      # connection you mean to keep. Fail-fast: if the block raises, the failing
-      # tenant is not released (the fan-out aborts).
+      # connection you mean to keep. Fail-fast: a raising block still aborts the
+      # fan-out, but the failing tenant's connection is released first — the
+      # release is best-effort cleanup (in an ensure), not iteration semantics.
       def each(tenants = nil, release_connection: false)
         raise(ArgumentError, 'Apartment::Tenant.each requires a block') unless block_given?
 
         tenants ||= Apartment.tenant_names
         tenants.each do |tenant|
           switch(tenant) { yield(tenant) }
+        ensure
           # Handler-wide (:all) covers writing + reading roles — the gem's
-          # established release call (see memory_stability_spec).
-          ActiveRecord::Base.connection_handler.clear_active_connections!(:all) if release_connection
+          # established release call (see memory_stability_spec). In an ensure so
+          # a raising tenant is still released; the exception then propagates and
+          # halts the fan-out (fail-fast preserved). Best-effort: a release
+          # failure must never mask the block's exception, so it is rescued and
+          # warned rather than raised out of the ensure.
+          if release_connection
+            begin
+              ActiveRecord::Base.connection_handler.clear_active_connections!(:all)
+            rescue StandardError => e
+              warn("[Apartment::Tenant.each] connection release failed: #{e.class}: #{e.message}")
+            end
+          end
         end
       end
 
@@ -281,8 +293,56 @@ module Apartment
         Apartment.pool_manager&.stats || {}
       end
 
+      # Clear the schema cache on warm tenant pools (and the default pool) in
+      # THIS PROCESS, so the next query re-reflects the database. Use after DDL
+      # on a pinned/shared table (which N warm tenant pools may have cached) or
+      # after manual DDL in a console. Lazy: clears now, repopulates from the DB
+      # on next access (not from any dump file).
+      #
+      # Current-process only — it cannot reach other workers' pools; fleet-wide
+      # DDL still needs a rolling restart. Clears schema reflection only, not
+      # prepared statements (AR self-heals those on PostgreSQL) and not model
+      # @columns_hash (call Model.reset_column_information or restart for that).
+      # Not a linearized barrier: an in-flight request may use metadata it
+      # already read. Intended for console / post-migrate / low-traffic use.
+      #
+      # tenant: nil clears all warm tenant pools + the default pool. A tenant
+      # name clears only that tenant's warm pools (+ the default pool when the
+      # name is the default tenant). Returns the count of pools cleared.
+      #
+      # Role scope: warm tenant pools are cleared across all roles (the pool key
+      # is "tenant:role"), but the default pool is cleared only for the CURRENT
+      # role. A multi-role app with a :reading default replica should call once
+      # per role (e.g. inside connected_to(role: :reading)) to clear the replica
+      # default pool too. For pinned/shared-table DDL, prefer the unscoped form
+      # (no tenant arg) — a tenant-scoped call clears only that tenant's pools.
+      def reload_schema_cache!(tenant = nil)
+        pools = []
+        Apartment.pool_manager&.each_pair do |key, pool|
+          pools << pool if tenant.nil? || key.start_with?("#{tenant}:")
+        end
+        default_pool = default_schema_cache_pool(tenant)
+        pools << default_pool if default_pool
+
+        pools.each { |pool| pool.schema_cache.clear! }
+        pools.size
+      end
+
       private
 
+      # The default pool to clear for reload_schema_cache!, or nil when it should
+      # be excluded (a real-tenant scope, or no default tenant configured). The
+      # ConnectionHandling patch routes connection_pool by Current.tenant, so we
+      # enter default context to get the real default pool, not a tenant one;
+      # guarded on `default` because with_default_tenant raises with no default.
+      def default_schema_cache_pool(tenant)
+        default = default_tenant
+        return nil unless default
+        return nil unless tenant.nil? || tenant.to_s == default.to_s
+
+        with_default_tenant { ActiveRecord::Base.connection_pool }
+      end
+
       # Raise when default_tenant_switch_allowed is false and the caller is
       # block-switching into the default tenant. switch! and reset are exempt:
       # neither enters this guard, so they remain the legitimate paths into

data/lib/apartment/version.rb

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

data/lib/apartment.rb

@@ -31,6 +31,16 @@ loader.ignore("#{__dir__}/apartment/cli")
 # as the cli.rb / cli ignores above.
 loader.ignore("#{__dir__}/rubocop")
 
+# Rails generators live under lib/generators and are loaded on demand by Rails'
+# generator machinery, never autoloaded. They follow Rails' generator naming
+# (Apartment::InstallGenerator), not Zeitwerk's path-based inference
+# (Generators::Apartment::Install::InstallGenerator), so leaving them managed
+# makes `Zeitwerk::Loader.eager_load_all` — which Rails runs whenever a host app
+# sets config.eager_load = true (production/CI) — raise Zeitwerk::NameError at
+# boot. Ignoring the directory is the canonical for_gem pattern for gems that
+# ship generators.
+loader.ignore("#{__dir__}/generators")
+
 # Collapse concerns/ so Zeitwerk maps lib/apartment/concerns/model.rb
 # to Apartment::Model (not Apartment::Concerns::Model). Mirrors the
 # Rails convention for app/models/concerns/.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ros-apartment
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha4
+  version: 4.0.0.alpha6
 platform: ruby
 authors:
 - Ryan Brunner