ros-apartment 4.0.0.alpha5 → 4.0.0.alpha7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4e597c986618a8043acbecc8081ef0399493c545fd3720d8f57653da90025da
-  data.tar.gz: 9fb0d04fe5abb04e93a4ef654edc14744dfc8d86d35f6d6ef8b685d7eb6ddb29
+  metadata.gz: '093f09466c1e39d4344764096cec982394980fb08c8b72712c96bd8ad30fdcc7'
+  data.tar.gz: 402f7ef009203bb95296a90d7c6ff3dd34eeebca2d70c7da86cdb398ecc6fa60
 SHA512:
-  metadata.gz: 747e6efe4c8c073368684944bbee84cccfd0b063f389d7b4a699debd97662496db9ea220e6be6f119986fa76e3586d180bb3f61ff61c4c44bc3acc37b7784f0c
-  data.tar.gz: 9ceef5927c8169dc2db2041fbbfba99b81c7106a9cf02814812550c1775cd2566398dd8383e78bd0d24e7a82a845d2c4418bc974c43cc5e0169cd25a6072eba5
+  metadata.gz: 99343f0efe17d444cc23b244581c56135a293371c97ee3fc5d2d2931e51c688c50d9d3d93d8ae55489ec36d3a6a43a910cacdc85d22c43a6c7e80a1bad189faa
+  data.tar.gz: 2ccd4c456cf1a5ce190d4b50dedfc131231cd1f02518c0444313987ef0a5fda8acc00c1376bfc5daac791768f1b13685d0bb47a08ae5ba755943a2cd6eb5d04b

data/README.md

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

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

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

data/lib/apartment/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/instrumentation.rb

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

data/lib/apartment/migrator.rb

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

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

data/lib/apartment/tenant.rb

@@ -293,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.alpha5'
+  VERSION = '4.0.0.alpha7'
 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.alpha5
+  version: 4.0.0.alpha7
 platform: ruby
 authors:
 - Ryan Brunner