ros-apartment 3.3.0 → 3.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22097d27933cc7eee7bf0c5e3ad5cf1b84d9243dcfc04be00d6db07a91c9857b
-  data.tar.gz: 28e20f76b32b532db8db681503753216ca2847c66ab80e902c200ea43a82b05d
+  metadata.gz: 8c1a77f61c7ac94816e7f0a0d906435cf2f9f06d7efc979a7308ac41a99c4247
+  data.tar.gz: '08bdfedeaba0107f0931a2a1f438b2dffebcdd4df89381b5be97f7bd9de5b7d3'
 SHA512:
-  metadata.gz: 5f007c6b72251b371b02380628d53b5cf1c7b62e5620fb659b596e9dec1a62e7a2fc0bf0ad1f5253d99b852f31091ddcedf073ed5e64457c5430c58c79c8aa83
-  data.tar.gz: 53ccf42974cebbcc6f874f9a631fe366a3952ff36d993127173df34563848359f409a3beeaa37596896a75e8c85cccd63a5ce4a7ec70b7d3278bf7e3b8c7e394
+  metadata.gz: c09415eddebce74732c14bf8f71ec3a4d8dab0e53f6df5d15439068964b2de79ac57c36253878456866e2021d6c8faf1a6f1a3ae12961b33d33a4118536128e3
+  data.tar.gz: db8413aa220b089dd0ab874051a5bf990e2f02b9a10da80e7e2356b8fbfd4a908346811ce6f8da0d9fc028c111fe9829ab495807e481a8b268353332d2e0c2bd

data/.gitignore

@@ -14,3 +14,4 @@ tmp
 spec/dummy/db/*.sqlite3
 .DS_Store
 .claude/
+.mcp.json

data/.rubocop.yml

@@ -33,6 +33,12 @@ Metrics/MethodLength:
   Exclude:
     - spec/**/*.rb
     - lib/apartment/tenant.rb
+    - lib/apartment/migrator.rb
+
+Metrics/ModuleLength:
+  Max: 150
+  Exclude:
+    - spec/**/*.rb
 
 Metrics/AbcSize:
   Max: 20

data/.ruby-version

@@ -1 +1 @@
-3.3.10
+3.4.7

data/AGENTS.md

@@ -0,0 +1,19 @@
+# Repository Guidelines for AI Agents
+
+This repo uses `CLAUDE.md` files as authoritative contributor guides for all AI assistants.
+
+## Reading Order
+
+1. **Read `/CLAUDE.md` (root) first** - project-wide architecture, patterns, design decisions
+2. **Read directory-specific `CLAUDE.md`** - check the directory you're modifying and its parents
+3. **Nested files override root** on conflicts (per AGENTS.md spec)
+
+Nested `CLAUDE.md` files exist in `lib/apartment/`, `lib/apartment/adapters/`, `lib/apartment/elevators/`, `lib/apartment/tasks/`, and `spec/`.
+
+## Key Principle
+
+Check `CLAUDE.md` before copying patterns from existing code - it documents preferred patterns, design rationale, and known pitfalls.
+
+## Adding Documentation
+
+Update the appropriate `CLAUDE.md` rather than this file. This file exists only as a pointer.

data/README.md

@@ -23,6 +23,12 @@ As of May 2024, Apartment is maintained with the support of [CampusESP](https://
 
 ## Installation
 
+### Requirements
+
+- Ruby 3.1+
+- Rails 7.0+ (Rails 6.1 support was dropped in v3.4.0)
+- PostgreSQL, MySQL, or SQLite3
+
 ### Rails
 
 Add the following to your Gemfile:
@@ -531,14 +537,55 @@ Note that you can disable the default migrating of all tenants with `db:migrate`
 
 #### Parallel Migrations
 
-Apartment supports parallelizing migrations into multiple threads when
-you have a large number of tenants. By default, parallel migrations is
-turned off. You can enable this by setting `parallel_migration_threads` to
-the number of threads you want to use in your initializer.
+Apartment supports parallel tenant migrations for applications with many schemas where sequential migration time becomes problematic. This is an **advanced feature** that requires understanding of your migration safety guarantees.
+
+##### Enabling Parallel Migrations
+
+```ruby
+Apartment.configure do |config|
+  config.parallel_migration_threads = 4
+end
+```
+
+##### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `parallel_migration_threads` | `0` | Number of parallel workers. `0` disables parallelism (recommended default). |
+| `parallel_strategy` | `:auto` | `:auto` detects platform, `:threads` forces thread-based, `:processes` forces fork-based. |
+| `manage_advisory_locks` | `true` | Disables PostgreSQL advisory locks during parallel execution to prevent deadlocks. |
+
+##### Platform Considerations
+
+Apartment auto-detects the safest parallelism strategy for your platform:
+
+- **Linux**: Uses process-based parallelism (faster due to copy-on-write memory)
+- **macOS/Windows**: Uses thread-based parallelism (avoids libpq fork issues)
+
+You can override this with `parallel_strategy: :threads` or `parallel_strategy: :processes`, but forcing processes on macOS may cause crashes due to PostgreSQL's C library (libpq) not being fork-safe on that platform.
+
+##### Important: Your Responsibility
+
+When you enable parallel migrations, Apartment disables PostgreSQL advisory locks to prevent deadlocks. This means **you are responsible for ensuring your migrations are safe to run concurrently**.
+
+**Use parallel migrations when:**
+- You have many tenants and sequential migration time is problematic
+- Your migrations only modify objects within each tenant's schema
+- You've verified your migrations have no cross-schema side effects
+
+**Stick with sequential execution when:**
+- Migrations create or modify PostgreSQL extensions
+- Migrations modify shared types, functions, or other database-wide objects
+- Migrations have ordering dependencies that span tenants
+- You're unsure whether your migrations are parallel-safe
+
+##### Connection Pool Sizing
+
+The `parallel_migration_threads` value should be less than your database connection pool size to avoid exhaustion errors. If you set `parallel_migration_threads: 8`, ensure your `pool` setting in `database.yml` is at least 10 to leave headroom.
+
+##### Schema Dump After Migration
 
-Keep in mind that because migrations are going to access the database,
-the number of threads indicated here should be less than the pool size
-that Rails will use to connect to your database.
+Apartment automatically dumps `schema.rb` after successful migrations, ensuring the dump comes from the public schema (the source of truth). This respects Rails' `dump_schema_after_migration` setting.
 
 ### Handling Environments
 

data/RELEASING.md

@@ -0,0 +1,106 @@
+# Releasing ros-apartment
+
+This document describes the release process for the `ros-apartment` gem.
+
+## Overview
+
+Releases are automated via GitHub Actions. Pushing to `main` triggers the `gem-publish.yml` workflow, which publishes to RubyGems using trusted publishing (no API key required).
+
+## Prerequisites
+
+- All changes merged to `development` branch
+- CI passing on `development`
+- Version number updated in `lib/apartment/version.rb`
+
+## Release Steps
+
+### 1. Bump the version
+
+Update `lib/apartment/version.rb` on the `development` branch:
+
+```ruby
+module Apartment
+  VERSION = 'X.Y.Z'
+end
+```
+
+Follow [Semantic Versioning](https://semver.org/):
+- **MAJOR** (X): Breaking changes
+- **MINOR** (Y): New features, backwards compatible
+- **PATCH** (Z): Bug fixes, backwards compatible
+
+### 2. Create release PR
+
+Create a PR from `development` to `main`:
+
+```bash
+gh pr create --base main --head development --title "Release vX.Y.Z"
+```
+
+Include a summary of changes in the PR description.
+
+### 3. Merge the release PR
+
+Once CI passes and the PR is approved, merge it. This triggers the publish workflow.
+
+**Important**: The workflow creates the git tag automatically. Do not create the tag manually beforehand or the workflow will fail.
+
+### 4. Verify the publish
+
+Monitor the `gem-publish.yml` workflow run. It will:
+1. Build the gem
+2. Create and push the `vX.Y.Z` tag
+3. Publish to RubyGems
+4. Wait for RubyGems indexes to update
+
+Verify at: https://rubygems.org/gems/ros-apartment
+
+### 5. Create GitHub Release
+
+After the workflow completes:
+
+1. Go to https://github.com/rails-on-services/apartment/releases/new
+2. Select the `vX.Y.Z` tag (created by the workflow)
+3. Click "Generate release notes" for a starting point
+4. Edit the release notes to highlight key changes
+5. Publish the release
+
+We use GitHub Releases as our changelog (no CHANGELOG.md file).
+
+### 6. Sync branches
+
+Merge `main` back into `development` to keep them in sync:
+
+```bash
+git checkout development
+git pull origin development
+git merge origin/main --no-edit
+git push
+```
+
+## Workflow Details
+
+The `gem-publish.yml` workflow uses:
+- **Trusted publishing**: Configured via RubyGems.org OIDC, no API key needed
+- **rubygems/release-gem@v1**: Official RubyGems action
+- **rake release**: Builds gem, creates tag, pushes to RubyGems
+
+## Troubleshooting
+
+### Workflow fails with "tag already exists"
+
+The tag was created manually before the workflow ran. Delete the tag and re-run:
+
+```bash
+git push origin --delete vX.Y.Z
+```
+
+Then re-trigger the workflow by pushing to main again (or re-run from GitHub Actions UI).
+
+### Gem published but GitHub Release missing
+
+The GitHub Release is created manually (step 5). The gem is already available on RubyGems; the release is just for documentation.
+
+### RubyGems trusted publishing fails
+
+Verify the GitHub environment `production` is configured correctly in repository settings, and that RubyGems.org has the trusted publisher configured for this repository.

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rails-on-services/apartment",
+  "public_key": "pk_EQhqzkh8FktmxBU0mbzmZ"
+}

data/lib/apartment/CLAUDE.md

@@ -6,11 +6,11 @@ This directory contains the core implementation of Apartment v3's multi-tenancy
 
 ```
 lib/apartment/
-├── adapters/              # Database-specific tenant isolation strategies
+├── adapters/              # Database-specific tenant isolation strategies (see CLAUDE.md)
 ├── active_record/         # ActiveRecord patches and extensions
-├── elevators/             # Rack middleware for automatic tenant switching
+├── elevators/             # Rack middleware for automatic tenant switching (see CLAUDE.md)
 ├── patches/               # Ruby/Rails core patches
-├── tasks/                 # Rake task utilities
+├── tasks/                 # Rake task utilities, parallel migrations (see CLAUDE.md)
 ├── console.rb             # Rails console tenant switching utilities
 ├── custom_console.rb      # Enhanced console with tenant prompts
 ├── deprecation.rb         # Deprecation warnings configuration

data/lib/apartment/migrator.rb

@@ -8,37 +8,47 @@ module Apartment
 
     # Migrate to latest
     def migrate(database)
-      Tenant.switch(database) do
-        version = ENV['VERSION']&.to_i
+      # Pin a connection for the entire migration to ensure Tenant.switch
+      # sets search_path on the same connection used by migration_context.
+      # Without this, connection pool may return different connections
+      # for the switch vs the actual migration operations.
+      ActiveRecord::Base.connection_pool.with_connection do
+        Tenant.switch(database) do
+          version = ENV['VERSION']&.to_i
 
-        migration_scope_block = ->(migration) { ENV['SCOPE'].blank? || (ENV['SCOPE'] == migration.scope) }
+          migration_scope_block = ->(migration) { ENV['SCOPE'].blank? || (ENV['SCOPE'] == migration.scope) }
 
-        if ActiveRecord.version >= Gem::Version.new('7.2.0')
-          ActiveRecord::Base.connection_pool.migration_context.migrate(version, &migration_scope_block)
-        else
-          ActiveRecord::Base.connection.migration_context.migrate(version, &migration_scope_block)
+          if ActiveRecord.version >= Gem::Version.new('7.2.0')
+            ActiveRecord::Base.connection_pool.migration_context.migrate(version, &migration_scope_block)
+          else
+            ActiveRecord::Base.connection.migration_context.migrate(version, &migration_scope_block)
+          end
         end
       end
     end
 
     # Migrate up/down to a specific version
     def run(direction, database, version)
-      Tenant.switch(database) do
-        if ActiveRecord.version >= Gem::Version.new('7.2.0')
-          ActiveRecord::Base.connection_pool.migration_context.run(direction, version)
-        else
-          ActiveRecord::Base.connection.migration_context.run(direction, version)
+      ActiveRecord::Base.connection_pool.with_connection do
+        Tenant.switch(database) do
+          if ActiveRecord.version >= Gem::Version.new('7.2.0')
+            ActiveRecord::Base.connection_pool.migration_context.run(direction, version)
+          else
+            ActiveRecord::Base.connection.migration_context.run(direction, version)
+          end
         end
       end
     end
 
     # rollback latest migration `step` number of times
     def rollback(database, step = 1)
-      Tenant.switch(database) do
-        if ActiveRecord.version >= Gem::Version.new('7.2.0')
-          ActiveRecord::Base.connection_pool.migration_context.rollback(step)
-        else
-          ActiveRecord::Base.connection.migration_context.rollback(step)
+      ActiveRecord::Base.connection_pool.with_connection do
+        Tenant.switch(database) do
+          if ActiveRecord.version >= Gem::Version.new('7.2.0')
+            ActiveRecord::Base.connection_pool.migration_context.rollback(step)
+          else
+            ActiveRecord::Base.connection.migration_context.rollback(step)
+          end
         end
       end
     end

data/lib/apartment/tasks/CLAUDE.md

@@ -0,0 +1,107 @@
+# lib/apartment/tasks/ - Rake Task Infrastructure
+
+This directory contains modules that support Apartment's rake task operations, particularly tenant migrations with optional parallelism.
+
+## Problem Context
+
+Multi-tenant PostgreSQL applications using schema-per-tenant isolation face operational challenges:
+
+1. **Migration time scales linearly**: 100 tenants × 2 seconds each = 3+ minutes blocking deploys
+2. **Rails assumes single-schema**: Built-in migration tasks don't iterate over tenant schemas
+3. **Parallel execution has pitfalls**: Database connections, advisory locks, and platform differences create subtle failure modes
+
+## Files
+
+### task_helper.rb
+
+**Purpose**: Orchestrates tenant iteration for rake tasks with optional parallel execution.
+
+**Key decisions**:
+
+- **Result-based error handling**: Operations return `Result` structs instead of raising exceptions. This allows migrations to continue for other tenants when one fails, with aggregated reporting at the end.
+
+- **Platform-aware parallelism**: macOS has documented issues with libpq after `fork()` due to GSS/Kerberos state. We auto-detect the platform and choose threads (safe everywhere) or processes (faster on Linux) accordingly. Developers can override via `parallel_strategy` config.
+
+- **Advisory lock management**: Rails uses `pg_advisory_lock` to prevent concurrent migrations. With parallel tenant migrations, all workers compete for the same lock, causing deadlocks. We disable advisory locks during parallel execution. **This shifts responsibility to the developer** to ensure migrations are parallel-safe.
+
+**When to use parallel migrations**:
+
+Use when you have many tenants and your migrations only touch tenant-specific objects. Avoid when migrations create extensions, modify shared types, or have cross-tenant dependencies.
+
+**Configuration options** (set in `config/initializers/apartment.rb`):
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `parallel_migration_threads` | `0` | Worker count. 0 = sequential (safest) |
+| `parallel_strategy` | `:auto` | `:auto`, `:threads`, or `:processes` |
+| `manage_advisory_locks` | `true` | Disable locks during parallel execution |
+
+### schema_dumper.rb
+
+**Purpose**: Ensures schema is dumped from the public schema after tenant migrations.
+
+**Why this exists**: After `rails db:migrate`, Rails dumps the current schema. Without intervention, this could capture the last-migrated tenant's schema rather than the authoritative public schema. We switch to the default tenant before invoking the dump.
+
+**Rails convention compliance**: Respects all relevant Rails settings:
+- `dump_schema_after_migration`: Global toggle for automatic dumps
+- `schema_format`: `:ruby` produces schema.rb, `:sql` produces structure.sql
+- `database_tasks`, `replica`, `schema_dump`: Per-database settings
+
+### enhancements.rb
+
+**Purpose**: Hooks Apartment tasks into Rails' standard `db:migrate` and `db:rollback` tasks.
+
+**Design choice**: We enhance rather than replace Rails tasks. Running `rails db:migrate` automatically migrates all tenant schemas after the public schema.
+
+## Relationship to Other Components
+
+- **Apartment::Migrator** (`lib/apartment/migrator.rb`): The actual migration execution logic. TaskHelper coordinates which tenants to migrate; Migrator handles the per-tenant work.
+
+- **Rake tasks** (`lib/tasks/apartment.rake`): Define the public task interface (`apartment:migrate`, etc.). These tasks use TaskHelper for iteration.
+
+- **Configuration** (`lib/apartment.rb`): Parallel execution settings live in the main Apartment module.
+
+## Common Failure Modes
+
+### Connection pool exhaustion
+
+**Symptom**: "could not obtain a connection from the pool" errors
+
+**Cause**: `parallel_migration_threads` exceeds database pool size
+
+**Fix**: Ensure `pool` in `database.yml` > `parallel_migration_threads`
+
+### Advisory lock deadlocks
+
+**Symptom**: Migrations hang indefinitely
+
+**Cause**: Multiple workers waiting for the same advisory lock
+
+**Fix**: Ensure `manage_advisory_locks: true` (default) when using parallelism
+
+### macOS fork crashes
+
+**Symptom**: Segfaults or GSS-API errors when using process-based parallelism on macOS
+
+**Cause**: libpq doesn't support fork() cleanly on macOS
+
+**Fix**: Use `parallel_strategy: :threads` or rely on `:auto` detection
+
+### Empty tenant name errors
+
+**Symptom**: `PG::SyntaxError: zero-length delimited identifier`
+
+**Cause**: `tenant_names` proc returned empty strings or nil values
+
+**Fix**: Fixed in v3.4.0 - empty values are now filtered automatically
+
+## Testing Considerations
+
+Parallel execution paths are difficult to unit test due to process isolation and connection state. The test suite verifies:
+
+- Correct delegation between sequential/parallel paths
+- Platform detection logic
+- Advisory lock ENV management
+- Result aggregation and error capture
+
+Integration testing of actual parallel execution happens in CI across Linux (processes) and macOS (threads) runners.

data/lib/apartment/tasks/enhancements.rb

@@ -2,12 +2,26 @@
 
 # Require this file to append Apartment rake tasks to ActiveRecord db rake tasks
 # Enabled by default in the initializer
+#
+# ## Multi-Database Support (Rails 7+)
+#
+# When a Rails app has multiple databases configured in database.yml, Rails creates
+# namespaced rake tasks like `db:migrate:primary`, `db:rollback:primary`, etc.
+# This enhancer automatically detects databases with `database_tasks: true` and
+# enhances their namespaced tasks to also run the corresponding apartment task.
+#
+# Example: Running `rails db:rollback:primary` will also invoke `apartment:rollback`
+# to rollback all tenant schemas.
 
 module Apartment
   class RakeTaskEnhancer
     module TASKS
       ENHANCE_BEFORE = %w[db:drop].freeze
       ENHANCE_AFTER  = %w[db:migrate db:rollback db:migrate:up db:migrate:down db:migrate:redo db:seed].freeze
+
+      # Base tasks that have namespaced variants in multi-database setups
+      # db:seed is excluded because Rails doesn't create db:seed:primary
+      NAMESPACED_AFTER = %w[db:migrate db:rollback db:migrate:up db:migrate:down db:migrate:redo].freeze
       freeze
     end
 
@@ -18,36 +32,89 @@ module Apartment
       def enhance!
         return unless should_enhance?
 
-        # insert task before
+        enhance_base_tasks!
+        enhance_namespaced_tasks!
+      end
+
+      def should_enhance?
+        Apartment.db_migrate_tenants
+      end
+
+      private
+
+      # Enhance standard db:* tasks (backward compatible behavior)
+      def enhance_base_tasks!
         TASKS::ENHANCE_BEFORE.each do |name|
-          task = Rake::Task[name]
-          enhance_before_task(task)
+          enhance_task_before(name)
         end
 
-        # insert task after
         TASKS::ENHANCE_AFTER.each do |name|
-          task = Rake::Task[name]
-          enhance_after_task(task)
+          enhance_task_after(name)
         end
       end
 
-      def should_enhance?
-        Apartment.db_migrate_tenants
+      # Enhance namespaced db:*:database_name tasks for multi-database setups
+      # Maps namespaced tasks to base apartment tasks:
+      #   db:migrate:primary    -> apartment:migrate
+      #   db:rollback:primary   -> apartment:rollback
+      #   db:migrate:up:primary -> apartment:migrate:up
+      def enhance_namespaced_tasks!
+        database_names_with_tasks.each do |db_name|
+          TASKS::NAMESPACED_AFTER.each do |base_task|
+            namespaced_task = "#{base_task}:#{db_name}"
+            next unless task_defined?(namespaced_task)
+
+            apartment_task = base_task.sub('db:', 'apartment:')
+            enhance_namespaced_task_after(namespaced_task, apartment_task)
+          end
+        end
       end
 
-      def enhance_before_task(task)
+      def enhance_task_before(name)
+        return unless task_defined?(name)
+
+        task = Rake::Task[name]
         task.enhance([inserted_task_name(task)])
       end
 
-      def enhance_after_task(task)
+      def enhance_task_after(name)
+        return unless task_defined?(name)
+
+        task = Rake::Task[name]
         task.enhance do
           Rake::Task[inserted_task_name(task)].invoke
         end
       end
 
+      def enhance_namespaced_task_after(namespaced_task_name, apartment_task_name)
+        Rake::Task[namespaced_task_name].enhance do
+          Rake::Task[apartment_task_name].invoke
+        end
+      end
+
       def inserted_task_name(task)
         task.name.sub('db:', 'apartment:')
       end
+
+      def task_defined?(name)
+        Rake::Task.task_defined?(name)
+      end
+
+      # Returns database names that have database_tasks enabled and are not replicas.
+      # These are the databases for which Rails creates namespaced rake tasks.
+      #
+      # @return [Array<String>] database names (e.g., ['primary', 'secondary'])
+      def database_names_with_tasks
+        return [] unless defined?(Rails) && Rails.respond_to?(:env)
+
+        configs = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env)
+        configs
+          .select { |c| c.database_tasks? && !c.replica? }
+          .map(&:name)
+      rescue StandardError
+        # Fail gracefully if configurations unavailable (e.g., during early boot)
+        []
+      end
     end
   end
 end

data/lib/apartment/tasks/schema_dumper.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Apartment
+  module Tasks
+    # Handles automatic schema dumping after tenant migrations.
+    #
+    # ## Problem Context
+    #
+    # After running `rails db:migrate`, Rails dumps the schema to capture the
+    # current database structure. With Apartment, tenant migrations modify
+    # individual schemas but the canonical structure lives in the public/default
+    # schema. Without explicit handling, the schema could be dumped from the
+    # last-migrated tenant schema instead of the authoritative public schema.
+    #
+    # ## Why This Approach
+    #
+    # We switch to the default tenant before dumping to ensure the schema file
+    # reflects the public schema structure. This is correct because:
+    #
+    # 1. All tenant schemas are created from the same schema file
+    # 2. The public schema is the source of truth for structure
+    # 3. Tenant-specific data differences don't affect schema structure
+    #
+    # ## Rails Convention Compliance
+    #
+    # We respect several Rails configurations rather than inventing our own:
+    #
+    # - `config.active_record.dump_schema_after_migration`: Global toggle
+    # - `config.active_record.schema_format`: `:ruby` for schema.rb, `:sql` for structure.sql
+    # - `database_tasks: true/false`: Per-database migration responsibility
+    # - `replica: true`: Excludes read replicas from schema operations
+    # - `schema_dump: false`: Per-database schema dump toggle
+    #
+    # The `db:schema:dump` task respects `schema_format` and produces either
+    # schema.rb or structure.sql accordingly.
+    #
+    # ## Gotchas
+    #
+    # - Schema dump failures are logged but don't fail the migration. This
+    #   prevents a secondary concern from blocking critical migrations.
+    # - Multi-database setups must mark one connection with `database_tasks: true`
+    #   to indicate which database owns schema management.
+    # - Don't call `Rails.application.load_tasks` here; if invoked from a rake
+    #   task, it re-triggers apartment enhancements causing recursion.
+    module SchemaDumper
+      class << self
+        # Entry point called after successful migrations. Checks all relevant
+        # Rails settings before attempting dump.
+        def dump_if_enabled
+          return unless rails_dump_schema_enabled?
+
+          db_config = find_schema_dump_config
+          return if db_config.nil?
+
+          schema_dump_setting = db_config.configuration_hash[:schema_dump]
+          return if schema_dump_setting == false
+
+          Apartment::Tenant.switch(Apartment.default_tenant) do
+            dump_schema
+          end
+        rescue StandardError => e
+          # Log but don't fail - schema dump is secondary to migration success
+          Rails.logger.warn("[Apartment] Schema dump failed: #{e.message}")
+        end
+
+        private
+
+        # Finds the database configuration responsible for schema management.
+        # Multi-database setups use `database_tasks: true` to mark the primary
+        # migration database. Falls back to 'primary' named config.
+        def find_schema_dump_config
+          configs = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env)
+
+          migration_config = configs.find { |c| c.database_tasks? && !c.replica? }
+          return migration_config if migration_config
+
+          configs.find { |c| c.name == 'primary' }
+        end
+
+        # Invokes the standard Rails schema dump task. We reenable first
+        # because Rake tasks can only run once per session by default.
+        def dump_schema
+          if task_defined?('db:schema:dump')
+            Rails.logger.info('[Apartment] Dumping schema from default tenant...')
+            Rake::Task['db:schema:dump'].reenable
+            Rake::Task['db:schema:dump'].invoke
+            Rails.logger.info('[Apartment] Schema dump completed.')
+          else
+            Rails.logger.warn('[Apartment] db:schema:dump task not found')
+          end
+        end
+
+        # Safe task existence check. Avoids load_tasks which would cause
+        # recursive enhancement loading when called from apartment rake tasks.
+        def task_defined?(task_name)
+          Rake::Task.task_defined?(task_name)
+        end
+
+        # Checks Rails' global schema dump setting. Older Rails versions
+        # may not have this method, so we default to enabled.
+        def rails_dump_schema_enabled?
+          return true unless ActiveRecord::Base.respond_to?(:dump_schema_after_migration)
+
+          ActiveRecord::Base.dump_schema_after_migration
+        end
+      end
+    end
+  end
+end

data/lib/apartment/tasks/task_helper.rb

@@ -1,54 +1,292 @@
 # frozen_string_literal: true
 
+require 'active_support/core_ext/module/delegation'
+
 module Apartment
+  # Coordinates tenant operations for rake tasks with parallel execution support.
+  #
+  # ## Problem Context
+  #
+  # Multi-tenant applications with many schemas face slow migration times when
+  # running sequentially. A 100-tenant system with 2-second migrations takes
+  # 3+ minutes sequentially but ~20 seconds with 10 parallel workers.
+  #
+  # ## Why This Design
+  #
+  # Parallel database migrations introduce two categories of problems:
+  #
+  # 1. **Platform-specific fork safety**: macOS/Windows have issues with libpq
+  #    (PostgreSQL C library) after fork() due to GSS/Kerberos state corruption.
+  #    Linux handles fork() cleanly. We auto-detect and choose the safe strategy.
+  #
+  # 2. **PostgreSQL advisory lock deadlocks**: Rails uses advisory locks to
+  #    prevent concurrent migrations. When multiple processes/threads migrate
+  #    different schemas simultaneously, they deadlock competing for the same
+  #    lock. We disable advisory locks during parallel execution, which means
+  #    **you accept responsibility for ensuring your migrations are parallel-safe**.
+  #
+  # ## When to Use Parallel Migrations
+  #
+  # This is an advanced feature. Use it when:
+  # - You have many tenants and sequential migration time is problematic
+  # - Your migrations only modify tenant-specific schema objects
+  # - You've verified your migrations don't have cross-schema side effects
+  #
+  # Stick with sequential execution (the default) when:
+  # - Migrations create/modify extensions, types, or shared objects
+  # - Migrations have ordering dependencies across tenants
+  # - You're unsure whether parallel execution is safe for your use case
+  #
+  # ## Gotchas
+  #
+  # - The `parallel_migration_threads` count should be less than your connection
+  #   pool size to avoid connection exhaustion.
+  # - Empty/nil tenant names from `tenant_names` proc are filtered to prevent
+  #   PostgreSQL "zero-length delimited identifier" errors.
+  # - Process-based parallelism requires fresh connections in each fork;
+  #   thread-based parallelism shares the pool but needs explicit checkout.
+  #
+  # @see Apartment.parallel_migration_threads
+  # @see Apartment.parallel_strategy
+  # @see Apartment.manage_advisory_locks
   module TaskHelper
-    def self.each_tenant
-      Parallel.each(tenants_without_default, in_threads: Apartment.parallel_migration_threads) do |tenant|
-        Rails.application.executor.wrap do
-          yield(tenant)
+    # Captures outcome per tenant for aggregated reporting. Allows migrations
+    # to continue for remaining tenants even when one fails.
+    Result = Struct.new(:tenant, :success, :error, keyword_init: true)
+
+    class << self
+      # Primary entry point for tenant iteration. Automatically selects
+      # sequential or parallel execution based on configuration.
+      #
+      # @yield [String] tenant name
+      # @return [Array<Result>] outcome for each tenant
+      def each_tenant(&)
+        return [] if tenants_without_default.empty?
+
+        if parallel_migration_threads.positive?
+          each_tenant_parallel(&)
+        else
+          each_tenant_sequential(&)
         end
       end
-    end
 
-    def self.tenants_without_default
-      tenants - [Apartment.default_tenant]
-    end
+      # Sequential execution: simpler, no connection management complexity.
+      # Used when parallel_migration_threads is 0 (the default).
+      def each_tenant_sequential
+        tenants_without_default.map do |tenant|
+          Rails.application.executor.wrap do
+            yield(tenant)
+          end
+          Result.new(tenant: tenant, success: true, error: nil)
+        rescue StandardError => e
+          Result.new(tenant: tenant, success: false, error: e.message)
+        end
+      end
 
-    def self.tenants
-      ENV['DB'] ? ENV['DB'].split(',').map(&:strip) : Apartment.tenant_names || []
-    end
+      # Parallel execution wrapper. Disables advisory locks for the duration,
+      # then delegates to platform-appropriate parallelism strategy.
+      def each_tenant_parallel(&)
+        with_advisory_locks_disabled do
+          case resolve_parallel_strategy
+          when :processes
+            each_tenant_in_processes(&)
+          else
+            each_tenant_in_threads(&)
+          end
+        end
+      end
 
-    def self.warn_if_tenants_empty
-      return unless tenants.empty? && ENV['IGNORE_EMPTY_TENANTS'] != 'true'
+      # Process-based parallelism via fork(). Faster on Linux due to
+      # copy-on-write memory and no GIL contention. Each forked process
+      # gets isolated memory, so we must clear inherited connections
+      # and establish fresh ones.
+      def each_tenant_in_processes
+        Parallel.map(tenants_without_default, in_processes: parallel_migration_threads) do |tenant|
+          # Forked processes inherit parent's connection handles but the
+          # underlying sockets are invalid. Must reconnect before any DB work.
+          ActiveRecord::Base.connection_handler.clear_all_connections!(:all)
+          reconnect_for_parallel_execution
 
-      puts <<-WARNING
-        [WARNING] - The list of tenants to migrate appears to be empty. This could mean a few things:
+          Rails.application.executor.wrap do
+            yield(tenant)
+          end
+          Result.new(tenant: tenant, success: true, error: nil)
+        rescue StandardError => e
+          Result.new(tenant: tenant, success: false, error: e.message)
+        ensure
+          ActiveRecord::Base.connection_handler.clear_all_connections!(:all)
+        end
+      end
 
-          1. You may not have created any, in which case you can ignore this message
-          2. You've run `apartment:migrate` directly without loading the Rails environment
-            * `apartment:migrate` is now deprecated. Tenants will automatically be migrated with `db:migrate`
+      # Thread-based parallelism. Safe on all platforms but subject to GIL
+      # for CPU-bound work (migrations are typically I/O-bound, so this is fine).
+      # Threads share the connection pool, so we reconfigure once before
+      # spawning and restore after completion.
+      def each_tenant_in_threads
+        original_config = ActiveRecord::Base.connection_db_config.configuration_hash
+        reconnect_for_parallel_execution
 
-        Note that your tenants currently haven't been migrated. You'll need to run `db:migrate` to rectify this.
-      WARNING
-    end
+        Parallel.map(tenants_without_default, in_threads: parallel_migration_threads) do |tenant|
+          # Explicit connection checkout prevents pool exhaustion when
+          # thread count exceeds pool size minus buffer.
+          ActiveRecord::Base.connection_pool.with_connection do
+            Rails.application.executor.wrap do
+              yield(tenant)
+            end
+          end
+          Result.new(tenant: tenant, success: true, error: nil)
+        rescue StandardError => e
+          Result.new(tenant: tenant, success: false, error: e.message)
+        end
+      ensure
+        ActiveRecord::Base.connection_handler.clear_all_connections!(:all)
+        ActiveRecord::Base.establish_connection(original_config) if original_config
+      end
 
-    def self.create_tenant(tenant_name)
-      puts("Creating #{tenant_name} tenant")
-      Apartment::Tenant.create(tenant_name)
-    rescue Apartment::TenantExists => e
-      puts "Tried to create already existing tenant: #{e}"
-    end
+      # Auto-detection logic for parallelism strategy. Only Linux gets
+      # process-based parallelism by default due to macOS libpq fork issues.
+      def resolve_parallel_strategy
+        strategy = Apartment.parallel_strategy
+
+        return :threads if strategy == :threads
+        return :processes if strategy == :processes
+
+        fork_safe_platform? ? :processes : :threads
+      end
+
+      # Platform detection. Conservative: only Linux is considered fork-safe.
+      # macOS has documented issues with libpq, GSS-API, and Kerberos after fork.
+      # See: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-GSSENCMODE
+      def fork_safe_platform?
+        RUBY_PLATFORM.include?('linux')
+      end
+
+      # Advisory lock management. Rails acquires pg_advisory_lock during migrations
+      # to prevent concurrent schema changes. With parallel tenant migrations,
+      # this causes deadlocks since all workers compete for the same lock.
+      #
+      # **Important**: Disabling advisory locks shifts responsibility to you.
+      # Your migrations must be safe to run concurrently across tenants. If your
+      # migrations modify shared resources, create extensions, or have other
+      # cross-schema side effects, parallel execution may cause failures.
+      # When in doubt, use sequential execution (parallel_migration_threads = 0).
+      #
+      # Uses ENV var because Rails checks it at connection establishment time,
+      # and we need it disabled before Parallel spawns workers.
+      def with_advisory_locks_disabled
+        return yield unless parallel_migration_threads.positive?
+        return yield unless Apartment.manage_advisory_locks
+
+        original_env_value = ENV.fetch('DISABLE_ADVISORY_LOCKS', nil)
+        begin
+          ENV['DISABLE_ADVISORY_LOCKS'] = 'true'
+          yield
+        ensure
+          if original_env_value.nil?
+            ENV.delete('DISABLE_ADVISORY_LOCKS')
+          else
+            ENV['DISABLE_ADVISORY_LOCKS'] = original_env_value
+          end
+        end
+      end
 
-    def self.migrate_tenant(tenant_name)
-      strategy = Apartment.db_migrate_tenant_missing_strategy
-      create_tenant(tenant_name) if strategy == :create_tenant
+      # Re-establishes database connection for parallel execution.
+      # When manage_advisory_locks is true, disables advisory locks in the
+      # connection config (belt-and-suspenders with the ENV var approach).
+      # When false, reconnects with existing config unchanged.
+      def reconnect_for_parallel_execution
+        current_config = ActiveRecord::Base.connection_db_config.configuration_hash
 
-      puts("Migrating #{tenant_name} tenant")
-      Apartment::Migrator.migrate(tenant_name)
-    rescue Apartment::TenantNotFound => e
-      raise(e) if strategy == :raise_exception
+        new_config = if Apartment.manage_advisory_locks
+                       current_config.merge(advisory_locks: false)
+                     else
+                       current_config
+                     end
 
-      puts e.message
+        ActiveRecord::Base.establish_connection(new_config)
+      end
+
+      # Delegate to Apartment.parallel_migration_threads
+      delegate :parallel_migration_threads, to: Apartment
+
+      # Get list of tenants excluding the default tenant
+      # Also filters out blank/empty tenant names to prevent errors
+      #
+      # @return [Array<String>] tenant names
+      def tenants_without_default
+        (tenants - [Apartment.default_tenant]).reject { |t| t.nil? || t.to_s.strip.empty? }
+      end
+
+      # Get list of all tenants to operate on
+      # Supports DB env var for targeting specific tenants
+      # Filters out blank tenant names for safety
+      #
+      # @return [Array<String>] tenant names
+      def tenants
+        result = ENV['DB'] ? ENV['DB'].split(',').map(&:strip) : Apartment.tenant_names || []
+        result.reject { |t| t.nil? || t.to_s.strip.empty? }
+      end
+
+      # Display warning if tenant list is empty
+      def warn_if_tenants_empty
+        return unless tenants.empty? && ENV['IGNORE_EMPTY_TENANTS'] != 'true'
+
+        puts <<~WARNING
+          [WARNING] - The list of tenants to migrate appears to be empty. This could mean a few things:
+
+            1. You may not have created any, in which case you can ignore this message
+            2. You've run `apartment:migrate` directly without loading the Rails environment
+              * `apartment:migrate` is now deprecated. Tenants will automatically be migrated with `db:migrate`
+
+          Note that your tenants currently haven't been migrated. You'll need to run `db:migrate` to rectify this.
+        WARNING
+      end
+
+      # Display summary of operation results
+      #
+      # @param operation [String] name of the operation (e.g., "Migration", "Rollback")
+      # @param results [Array<Result>] results from each_tenant
+      def display_summary(operation, results)
+        return if results.empty?
+
+        succeeded = results.count(&:success)
+        failed = results.reject(&:success)
+
+        puts "\n=== #{operation} Summary ==="
+        puts "Succeeded: #{succeeded}/#{results.size} tenants"
+
+        return if failed.empty?
+
+        puts "Failed: #{failed.size} tenants"
+        failed.each do |result|
+          puts "  - #{result.tenant}: #{result.error}"
+        end
+      end
+
+      # Create a tenant with logging
+      #
+      # @param tenant_name [String] name of tenant to create
+      def create_tenant(tenant_name)
+        puts("Creating #{tenant_name} tenant")
+        Apartment::Tenant.create(tenant_name)
+      rescue Apartment::TenantExists => e
+        puts "Tried to create already existing tenant: #{e}"
+      end
+
+      # Migrate a single tenant with error handling based on strategy
+      #
+      # @param tenant_name [String] name of tenant to migrate
+      def migrate_tenant(tenant_name)
+        strategy = Apartment.db_migrate_tenant_missing_strategy
+        create_tenant(tenant_name) if strategy == :create_tenant
+
+        puts("Migrating #{tenant_name} tenant")
+        Apartment::Migrator.migrate(tenant_name)
+      rescue Apartment::TenantNotFound => e
+        raise(e) if strategy == :raise_exception
+
+        puts e.message
+      end
     end
   end
 end

data/lib/apartment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apartment
-  VERSION = '3.3.0'
+  VERSION = '3.4.1'
 end

data/lib/apartment.rb

@@ -28,7 +28,8 @@ module Apartment
     WRITER_METHODS = %i[tenant_names database_schema_file excluded_models
                         persistent_schemas connection_class
                         db_migrate_tenants db_migrate_tenant_missing_strategy seed_data_file
-                        parallel_migration_threads pg_excluded_names].freeze
+                        parallel_migration_threads pg_excluded_names
+                        parallel_strategy manage_advisory_locks].freeze
 
     attr_accessor(*ACCESSOR_METHODS)
     attr_writer(*WRITER_METHODS)
@@ -93,6 +94,24 @@ module Apartment
       @parallel_migration_threads || 0
     end
 
+    # Parallelism strategy for migrations
+    # :auto (default) - Detect platform: processes on Linux, threads on macOS/Windows
+    # :threads - Always use threads (safer, works everywhere)
+    # :processes - Always use processes (faster on Linux, may crash on macOS/Windows)
+    def parallel_strategy
+      @parallel_strategy || :auto
+    end
+
+    # Whether to manage PostgreSQL advisory locks during parallel migrations
+    # When true and parallel_migration_threads > 0, advisory locks are disabled
+    # during migration to prevent deadlocks, then restored afterward.
+    # Default: true
+    def manage_advisory_locks
+      return @manage_advisory_locks if defined?(@manage_advisory_locks)
+
+      @manage_advisory_locks = true
+    end
+
     def persistent_schemas
       @persistent_schemas || []
     end

data/lib/tasks/apartment.rake

@@ -2,6 +2,7 @@
 
 require 'apartment/migrator'
 require 'apartment/tasks/task_helper'
+require 'apartment/tasks/schema_dumper'
 require 'parallel'
 
 apartment_namespace = namespace(:apartment) do
@@ -27,9 +28,22 @@ apartment_namespace = namespace(:apartment) do
   desc('Migrate all tenants')
   task(migrate: :environment) do
     Apartment::TaskHelper.warn_if_tenants_empty
-    Apartment::TaskHelper.each_tenant do |tenant|
+
+    results = Apartment::TaskHelper.each_tenant do |tenant|
       Apartment::TaskHelper.migrate_tenant(tenant)
     end
+
+    Apartment::TaskHelper.display_summary('Migration', results)
+
+    # Dump schema after successful migrations
+    if results.all?(&:success)
+      Apartment::Tasks::SchemaDumper.dump_if_enabled
+    else
+      puts '[Apartment] Skipping schema dump due to migration failures'
+    end
+
+    # Exit with non-zero status if any tenant failed
+    exit(1) if results.any? { |r| !r.success }
   end
 
   desc('Seed all tenants')
@@ -51,14 +65,23 @@ apartment_namespace = namespace(:apartment) do
   task(rollback: :environment) do
     Apartment::TaskHelper.warn_if_tenants_empty
 
-    step = ENV['STEP'] ? ENV['STEP'].to_i : 1
+    step = ENV.fetch('STEP', '1').to_i
 
-    Apartment::TaskHelper.each_tenant do |tenant|
+    results = Apartment::TaskHelper.each_tenant do |tenant|
       puts("Rolling back #{tenant} tenant")
       Apartment::Migrator.rollback(tenant, step)
-    rescue Apartment::TenantNotFound => e
-      puts e.message
     end
+
+    Apartment::TaskHelper.display_summary('Rollback', results)
+
+    # Dump schema after successful rollback
+    if results.all?(&:success)
+      Apartment::Tasks::SchemaDumper.dump_if_enabled
+    else
+      puts '[Apartment] Skipping schema dump due to rollback failures'
+    end
+
+    exit(1) if results.any? { |r| !r.success }
   end
 
   namespace(:migrate) do
@@ -66,35 +89,39 @@ apartment_namespace = namespace(:apartment) do
     task(up: :environment) do
       Apartment::TaskHelper.warn_if_tenants_empty
 
-      version = ENV['VERSION']&.to_i
+      version = ENV.fetch('VERSION', nil)&.to_i
       raise('VERSION is required') unless version
 
-      Apartment::TaskHelper.each_tenant do |tenant|
+      results = Apartment::TaskHelper.each_tenant do |tenant|
         puts("Migrating #{tenant} tenant up")
         Apartment::Migrator.run(:up, tenant, version)
-      rescue Apartment::TenantNotFound => e
-        puts e.message
       end
+
+      Apartment::TaskHelper.display_summary('Migrate Up', results)
+      Apartment::Tasks::SchemaDumper.dump_if_enabled if results.all?(&:success)
+      exit(1) if results.any? { |r| !r.success }
     end
 
     desc('Runs the "down" for a given migration VERSION across all tenants.')
     task(down: :environment) do
       Apartment::TaskHelper.warn_if_tenants_empty
 
-      version = ENV['VERSION']&.to_i
+      version = ENV.fetch('VERSION', nil)&.to_i
       raise('VERSION is required') unless version
 
-      Apartment::TaskHelper.each_tenant do |tenant|
+      results = Apartment::TaskHelper.each_tenant do |tenant|
         puts("Migrating #{tenant} tenant down")
         Apartment::Migrator.run(:down, tenant, version)
-      rescue Apartment::TenantNotFound => e
-        puts e.message
       end
+
+      Apartment::TaskHelper.display_summary('Migrate Down', results)
+      Apartment::Tasks::SchemaDumper.dump_if_enabled if results.all?(&:success)
+      exit(1) if results.any? { |r| !r.success }
     end
 
     desc('Rolls back the tenant one migration and re migrate up (options: STEP=x, VERSION=x).')
     task(:redo) do
-      if ENV['VERSION']
+      if ENV.fetch('VERSION', nil)
         apartment_namespace['migrate:down'].invoke
         apartment_namespace['migrate:up'].invoke
       else

data/ros-apartment.gemspec

@@ -32,8 +32,8 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '>= 3.1'
 
-  s.add_dependency('activerecord', '>= 6.1.0', '< 8.2')
-  s.add_dependency('activesupport', '>= 6.1.0', '< 8.2')
+  s.add_dependency('activerecord', '>= 7.0.0', '< 8.2')
+  s.add_dependency('activesupport', '>= 7.0.0', '< 8.2')
   s.add_dependency('parallel', '< 2.0')
   s.add_dependency('public_suffix', '>= 2.0.5', '< 7')
   s.add_dependency('rack', '>= 1.3.6', '< 4.0')

metadata

@@ -1,17 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: ros-apartment
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.4.1
 platform: ruby
 authors:
 - Ryan Brunner
 - Brad Robertson
 - Rui Baltazar
 - Mauricio Novelo
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -19,7 +18,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: 7.0.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
@@ -29,7 +28,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: 7.0.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
@@ -39,7 +38,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: 7.0.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
@@ -49,7 +48,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: 7.0.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
@@ -123,13 +122,16 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- AGENTS.md
 - Appraisals
 - CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Guardfile
 - README.md
+- RELEASING.md
 - Rakefile
+- context7.json
 - docs/adapters.md
 - docs/architecture.md
 - docs/elevators.md
@@ -166,7 +168,9 @@ files:
 - lib/apartment/migrator.rb
 - lib/apartment/model.rb
 - lib/apartment/railtie.rb
+- lib/apartment/tasks/CLAUDE.md
 - lib/apartment/tasks/enhancements.rb
+- lib/apartment/tasks/schema_dumper.rb
 - lib/apartment/tasks/task_helper.rb
 - lib/apartment/tenant.rb
 - lib/apartment/version.rb
@@ -181,7 +185,6 @@ licenses:
 metadata:
   github_repo: ssh://github.com/rails-on-services/apartment
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -196,8 +199,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Ruby gem for managing database multitenancy. Apartment Gem drop in replacement
 test_files: []