postgres_multitenant 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: adf23754bd33057352e117a40249d291bea349d0a6b92df9690ac6c09e3eba4a
+  data.tar.gz: 70fee68ab239014dd1e336faf79982322c8c6e7ed0089861142bbee558a0de7d
+SHA512:
+  metadata.gz: b81bfceab7f0aee9f2b59daa16079791692aeb0c82f060dbdf47b1424c03eb54f191c3cc35bc7636192f10b9a053a7c2da649d5480e6e593bb8ff5d6c79f3032
+  data.tar.gz: e96fb48ee50239aa068464dd9a097cdb7f6adb112f307e5445e7eda9bca6f1f3d7aa836ff20d3474a770657de657eed6ac54212c91f0291eebb2d66695c532cf

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- Initial public release.
+- Adds PostgreSQL schema switching middleware for Rails applications.
+- Adds schema lifecycle helpers and tenant rake tasks.
+- Adds `rails generate postgres_multitenant:install`.
+- Supports Rails 6.1 through Rails 8.1.x.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Needham - DAD Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+# PostgresMultitenant
+
+Schema-based multi-tenancy for Rails applications backed by PostgreSQL schemas.
+
+PostgresMultitenant provides:
+
+- request middleware that switches PostgreSQL `search_path` by tenant subdomain
+- schema lifecycle helpers for creating, dropping, switching, and listing tenants
+- tenant schema sync from `db/tenant_schema.rb`, with `db/schema.rb` fallback
+- Rails rake tasks for tenant lifecycle operations
+- a Rails install generator
+
+## Requirements
+
+- Ruby 3.1+
+- Rails 6.1+
+- PostgreSQL with `schema_search_path` support
+
+The gem is compatible with Rails 8.1.x, including Rails 8.1.3. Rails 8.1 itself requires Ruby 3.2+, so applications on Ruby 3.1 should stay on an older compatible Rails release.
+
+## Installation
+
+Add the gem to your Rails app:
+
+```ruby
+gem "postgres_multitenant"
+```
+
+Then run:
+
+```bash
+bundle install
+bin/rails generate postgres_multitenant:install
+```
+
+The generator creates:
+
+- `config/initializers/postgres_multitenant.rb`
+- `db/tenant_schema.rb`
+
+Generator options:
+
+```bash
+bin/rails generate postgres_multitenant:install --tenant-class-name=Account --tenant-foreign-key=account_id
+```
+
+## Configuration
+
+Edit `config/initializers/postgres_multitenant.rb` after running the generator:
+
+```ruby
+PostgresMultitenant.configure do |config|
+  # Public-schema model that identifies tenants by subdomain.
+  config.tenant_class_name = "Organization"
+
+  # Required: return tenant-scoped table names without schema prefixes.
+  config.tenant_table_resolver = -> { %w[clients projects bookings] }
+
+  # Optional: scope tenant records considered for routing and tenant migration.
+  config.tenant_scope_proc = ->(klass) { klass.where(active: true) }
+
+  # Optional: custom subdomain lookup.
+  config.tenant_finder = ->(subdomain) { Organization.find_by(subdomain: subdomain) }
+
+  # Optional: custom schema naming.
+  config.tenant_schema_name_proc = ->(tenant) { tenant.subdomain.tr("-", "_") }
+
+  # Tenant foreign key expected on tenant-scoped tables during development checks.
+  config.tenant_foreign_key = "organization_id"
+
+  # Optional: override request-to-subdomain extraction.
+  # config.subdomain_extractor = ->(request) { request.subdomain.presence }
+
+  # Strategy when tenant is not found:
+  #   :raise  -> raise PostgresMultitenant::TenantNotFoundError
+  #   :public -> continue in config.default_schema
+  #   :custom -> call config.tenant_not_found_handler
+  config.tenant_not_found_strategy = :raise
+
+  # Required when tenant_not_found_strategy is :custom.
+  # config.tenant_not_found_handler = ->(_request, _subdomain) {
+  #   [404, {"Content-Type" => "text/plain"}, ["Tenant not found"]]
+  # }
+end
+```
+
+## Data Model Contract
+
+Your tenant class, for example `Organization`, should:
+
+- live in the public schema
+- expose a `subdomain` attribute, unless `tenant_finder` is configured
+- expose a schema name through `schema_name`, or use `tenant_schema_name_proc`
+
+Tenant-scoped tables should include the configured tenant foreign key, such as `organization_id`, unless the table is listed in `config.system_tables`.
+
+## Tenant Schema
+
+Prefer defining tenant-only tables in `db/tenant_schema.rb`:
+
+```ruby
+ActiveRecord::Schema.define do
+  create_table "projects", force: :cascade do |t|
+    t.bigint "organization_id", null: false
+    t.string "name", null: false
+    t.timestamps
+  end
+end
+```
+
+If `db/tenant_schema.rb` is absent, PostgresMultitenant loads `db/schema.rb` and prunes tables that are not returned by:
+
+- `config.tenant_table_resolver.call`
+- `config.system_tables`
+
+## Usage
+
+```ruby
+PostgresMultitenant.switch("acme") { Project.count }
+PostgresMultitenant.create("acme")
+PostgresMultitenant.drop("acme")
+PostgresMultitenant.current #=> "public" or tenant schema
+PostgresMultitenant.tenants #=> ["acme", "beacon"]
+PostgresMultitenant.reset!
+```
+
+Schema names must be lowercase PostgreSQL-safe identifiers matching:
+
+```text
+\A[a-z][a-z0-9_]*\z
+```
+
+Reserved schemas such as `public`, `information_schema`, and `pg_*` cannot be used as tenant schemas.
+
+## Rake Tasks
+
+```bash
+bin/rails tenants:create[acme]
+bin/rails tenants:drop[acme]
+bin/rails tenants:list
+bin/rails tenants:migrate
+```
+
+`tenants:migrate` keeps tenant schemas in sync by loading `db/tenant_schema.rb` or `db/schema.rb`; it does not run Rails migrations inside tenant schemas.
+
+## Development
+
+Run the test suite:
+
+```bash
+rake test
+```
+
+Build the gem:
+
+```bash
+gem build postgres_multitenant.gemspec
+```
+
+## Security Notes
+
+- Keep `tenant_not_found_strategy = :raise` unless public-schema fallback is intentional.
+- Keep public tables and tenant tables separated by design.
+- Do not include tenant-owned data in public-schema models.
+- Review `config.tenant_table_resolver` whenever adding tenant-scoped tables.

data/lib/generators/postgres_multitenant/install/install_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module PostgresMultitenant
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a PostgresMultitenant initializer and tenant schema file.'
+
+      class_option :tenant_class_name,
+                   type: :string,
+                   default: 'Organization',
+                   desc: 'Public-schema model used to find tenants.'
+
+      class_option :tenant_foreign_key,
+                   type: :string,
+                   default: 'organization_id',
+                   desc: 'Foreign key column expected on tenant-scoped tables.'
+
+      def copy_initializer
+        template 'postgres_multitenant.rb.tt', 'config/initializers/postgres_multitenant.rb'
+      end
+
+      def copy_tenant_schema
+        copy_file 'tenant_schema.rb', 'db/tenant_schema.rb'
+      end
+    end
+  end
+end

data/lib/generators/postgres_multitenant/install/templates/postgres_multitenant.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+PostgresMultitenant.configure do |config|
+  # Public-schema model that identifies tenants by subdomain.
+  config.tenant_class_name = '<%= options[:tenant_class_name] %>'
+
+  # Required: return tenant-scoped table names without schema prefixes.
+  # Replace this with the table list or app-specific registry for your tenant data.
+  config.tenant_table_resolver = -> { [] }
+
+  # Optional: scope tenant records considered for routing and tenant migration.
+  # config.tenant_scope_proc = ->(klass) { klass.where(active: true) }
+
+  # Optional: custom subdomain lookup.
+  # config.tenant_finder = ->(subdomain) { <%= options[:tenant_class_name] %>.find_by(subdomain: subdomain) }
+
+  # Optional: custom schema naming.
+  # config.tenant_schema_name_proc = ->(tenant) { tenant.subdomain.tr('-', '_') }
+
+  # Tenant foreign key expected on tenant-scoped tables during development checks.
+  config.tenant_foreign_key = '<%= options[:tenant_foreign_key] %>'
+
+  # Optional: override request-to-subdomain extraction.
+  # config.subdomain_extractor = ->(request) { request.subdomain.presence }
+
+  # Default behavior is to raise when a tenant subdomain cannot be resolved.
+  config.tenant_not_found_strategy = :raise
+end

data/lib/generators/postgres_multitenant/install/templates/tenant_schema.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Define only tenant-scoped tables in this file. If this file is absent,
+# PostgresMultitenant falls back to db/schema.rb and prunes non-tenant tables after load.
+ActiveRecord::Schema.define do
+end

data/lib/postgres_multitenant/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/string/inflections'
+
+module PostgresMultitenant
+  class Configuration
+    attr_accessor :tenant_class_name,
+                  :tenant_finder,
+                  :tenant_scope_proc,
+                  :tenant_schema_name_proc,
+                  :tenant_foreign_key,
+                  :tenant_table_resolver,
+                  :system_tables,
+                  :default_schema,
+                  :excluded_subdomains,
+                  :subdomain_extractor,
+                  :tenant_not_found_strategy,
+                  :tenant_not_found_handler,
+                  :terminate_connections_on_drop
+
+    def initialize
+      @tenant_class_name = 'Organization'
+      @tenant_finder = nil
+      @tenant_scope_proc = nil
+      @tenant_schema_name_proc = nil
+      @tenant_foreign_key = 'organization_id'
+      @tenant_table_resolver = nil
+      @default_schema = 'public'
+      @system_tables = %w[
+        action_text_rich_texts
+        active_storage_attachments
+        active_storage_blobs
+        active_storage_variant_records
+      ]
+      @excluded_subdomains = %w[www api admin mail ftp]
+      @subdomain_extractor = nil
+      @tenant_not_found_strategy = :raise
+      @tenant_not_found_handler = nil
+      @terminate_connections_on_drop = false
+    end
+
+    def tenant_class
+      return nil if tenant_class_name.to_s.empty?
+
+      tenant_class_name.constantize
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/postgres_multitenant/connection_pool_extensions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PostgresMultitenant
+  module ConnectionPoolExtensions
+    def checkin(conn)
+      reset_schema_search_path(conn)
+      super
+    end
+
+    private
+
+    def reset_schema_search_path(conn)
+      return unless conn.respond_to?(:schema_search_path=)
+
+      conn.schema_search_path = PostgresMultitenant.configuration.default_schema
+    rescue StandardError
+      # no-op; never break checkin flow
+    end
+  end
+end

data/lib/postgres_multitenant/middleware.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/object/inclusion'
+
+module PostgresMultitenant
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request = ActionDispatch::Request.new(env)
+      subdomain = extract_subdomain(request)
+      return run_in_schema(PostgresMultitenant.configuration.default_schema, env) if subdomain.blank?
+
+      tenant = PostgresMultitenant.find_tenant_by_subdomain(subdomain) if subdomain.present?
+
+      if tenant
+        schema_name = PostgresMultitenant.schema_name_for(tenant)
+        return run_in_schema(schema_name.presence || PostgresMultitenant.configuration.default_schema, env)
+      end
+
+      handle_tenant_not_found(env, request, subdomain)
+    end
+
+    private
+
+    def extract_subdomain(request)
+      extractor = PostgresMultitenant.configuration.subdomain_extractor
+      return extractor.call(request) if extractor
+
+      host = request.host.to_s.downcase
+
+      # Skip for localhost, IP addresses, and single-part domains
+      return nil if host == 'localhost'
+      return nil if host =~ /\A\d+\.\d+\.\d+\.\d+\z/
+
+      parts = host.split('.')
+
+      # Need at least 3 parts for a subdomain (subdomain.domain.tld)
+      return nil if parts.length < 3
+
+      # Return first part as subdomain
+      subdomain = parts.first
+
+      # Skip common non-tenant subdomains
+      return nil if subdomain.in?(PostgresMultitenant.configuration.excluded_subdomains)
+
+      subdomain
+    end
+
+    def run_in_schema(schema_name, env)
+      SchemaManager.with_schema(schema_name) { @app.call(env) }
+    end
+
+    def handle_tenant_not_found(env, request, subdomain)
+      case PostgresMultitenant.configuration.tenant_not_found_strategy
+      when :raise
+        raise PostgresMultitenant::TenantNotFoundError, "No tenant found for subdomain '#{subdomain}'"
+      when :custom
+        handler = PostgresMultitenant.configuration.tenant_not_found_handler
+        raise ArgumentError, 'tenant_not_found_handler must be configured for :custom strategy' unless handler
+
+        handler.call(request, subdomain)
+      else
+        run_in_schema(PostgresMultitenant.configuration.default_schema, env)
+      end
+    end
+  end
+end

data/lib/postgres_multitenant/railtie.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PostgresMultitenant
+  class Railtie < Rails::Railtie
+    initializer 'postgres_multitenant.configure_middleware' do |app|
+      app.config.middleware.use PostgresMultitenant::Middleware
+    end
+
+    initializer 'postgres_multitenant.patch_connection_pool' do
+      ActiveSupport.on_load(:active_record) do
+        pool = ActiveRecord::ConnectionAdapters::ConnectionPool
+        pool.prepend(PostgresMultitenant::ConnectionPoolExtensions) unless pool < PostgresMultitenant::ConnectionPoolExtensions
+      end
+    end
+
+    # Load rake tasks
+    rake_tasks do
+      load File.expand_path('../tasks/postgres_multitenant.rake', __dir__)
+    end
+  end
+end

data/lib/postgres_multitenant/schema_manager.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object/blank'
+
+module PostgresMultitenant
+  class UnsupportedAdapterError < StandardError; end
+
+  # Exception raised when schema drop fails after max retries
+  class SchemaDropError < StandardError; end
+
+  class SchemaManager
+    RESERVED_SCHEMAS = %w[public information_schema].freeze
+    SYSTEM_SCHEMA_PREFIX = 'pg_'
+
+    # SECURITY: Only tenant-specific tables should be created in tenant schemas.
+    def self.tenant_tables
+      return @tenant_tables_cache if defined?(@tenant_tables_cache) && @tenant_tables_cache
+
+      resolver = PostgresMultitenant.configuration.tenant_table_resolver
+      raise StandardError, 'Configure PostgresMultitenant.tenant_table_resolver.' unless resolver
+
+      tenant_scoped_tables = resolver.call
+
+      system_tables = PostgresMultitenant.configuration.system_tables
+
+      # Combine and deduplicate
+      @tenant_tables_cache = (Array(tenant_scoped_tables) + Array(system_tables)).uniq.sort
+    end
+
+    # Validate that tenant table configuration is correct
+    # Ensures models are loaded and schema matches expectations
+    def self.validate_tenant_table_configuration!
+      detected = tenant_tables
+
+      # Ensure we found some tables
+      if detected.empty?
+        raise StandardError, 'No tenant tables detected. Configure PostgresMultitenant.tenant_table_resolver.'
+      end
+
+      # In test/development, validate that schema has tenant foreign key columns
+      if Rails.env.test? || Rails.env.development?
+        system_tables = PostgresMultitenant.configuration.system_tables
+        tenant_foreign_key = PostgresMultitenant.configuration.tenant_foreign_key
+        missing_org_id = detected.reject { |table| system_tables.include?(table) }
+                                 .select { |table| !column_exists_in_schema?(table, tenant_foreign_key) }
+
+        if missing_org_id.any?
+          Rails.logger.warn(
+            "WARNING: These tenant tables are missing #{tenant_foreign_key} column: #{missing_org_id.join(', ')}"
+          )
+        end
+      end
+
+      detected
+    end
+
+    # Helper method to check if a column exists in a table
+    def self.column_exists_in_schema?(table_name, column_name)
+      connection.column_exists?(table_name, column_name)
+    rescue ActiveRecord::StatementInvalid
+      false
+    end
+
+    def self.reset_tenant_table_cache!
+      @tenant_tables_cache = nil
+    end
+
+    class << self
+      # Create a new tenant schema and run migrations
+      def create_schema(name)
+        validate_schema_name!(name)
+
+        connection.execute("CREATE SCHEMA IF NOT EXISTS #{connection.quote_table_name(name)}")
+
+        # Load schema.rb into the new tenant schema
+        with_schema(name) do
+          load_schema_file
+        end
+      end
+
+      # Drop a tenant schema
+      def drop_schema(name)
+        validate_schema_name!(name)
+        connection.execute("DROP SCHEMA IF EXISTS #{connection.quote_table_name(name)} CASCADE")
+      end
+
+      # Switch to a tenant schema for a block
+      def with_schema(name, &block)
+        raise ArgumentError, 'Block required' unless block
+
+        name = normalize_schema_name(name)
+        validate_schema_name!(name) unless name == 'public'
+
+        original = current_schema
+        switched = false
+        switch_to(name)
+        switched = true
+        yield
+      ensure
+        switch_to(original) if switched && original
+      end
+
+      # Get current schema from search_path
+      def current_schema
+        conn = connection
+        ensure_schema_search_path_supported!(conn)
+
+        schema = conn.schema_search_path.to_s.split(',').first.to_s.strip.delete('"')
+        schema.presence || 'public'
+      end
+
+      # List all tenant schemas (excluding system schemas)
+      def tenant_schemas
+        connection.select_values(
+          ActiveRecord::Base.sanitize_sql_array([
+                                                  'SELECT schema_name FROM information_schema.schemata WHERE schema_name NOT IN (?) AND schema_name NOT LIKE ?',
+                                                  RESERVED_SCHEMAS,
+                                                  "#{SYSTEM_SCHEMA_PREFIX}%"
+                                                ])
+        )
+      end
+
+      # Check if a schema exists
+      def schema_exists?(name)
+        result = connection.select_value(
+          ActiveRecord::Base.sanitize_sql_array([
+                                                  'SELECT 1 FROM information_schema.schemata WHERE schema_name = ? LIMIT 1',
+                                                  name
+                                                ])
+        )
+        result.present?
+      end
+
+      # Reset connection to public schema
+      def reset!
+        switch_to('public')
+      end
+
+      # Drop a schema with retry logic and connection termination
+      #
+      # @param name [String] The schema name to drop
+      # @param max_attempts [Integer] Maximum number of retry attempts (default: 5)
+      # @param raise_on_failure [Boolean] Whether to raise exception on failure (default: true)
+      # @return [Boolean] true if successful, false if failed and raise_on_failure is false
+      # @raise [SchemaDropError] if max attempts exceeded and raise_on_failure is true
+      def drop_schema_with_retry(name, max_attempts: 5, raise_on_failure: true)
+        validate_schema_name!(name)
+
+        # If schema doesn't exist, return true (idempotent)
+        unless schema_exists?(name)
+          Rails.logger.info("Schema #{name} does not exist, skipping drop")
+          return true
+        end
+
+        attempts = 0
+        last_error = nil
+
+        while attempts < max_attempts
+          attempts += 1
+
+          begin
+            # Terminate active connections only when explicitly configured.
+            terminate_schema_connections(name) if PostgresMultitenant.configuration.terminate_connections_on_drop
+
+            Rails.logger.info("Dropping schema: #{name} (attempt #{attempts}/#{max_attempts})")
+            drop_schema(name)
+            Rails.logger.info("Successfully dropped schema: #{name}")
+            return true
+          rescue ActiveRecord::StatementInvalid => e
+            last_error = e
+
+            # Check if error is retryable (locked schema, active connections, etc.)
+            if e.message.include?('PG::ObjectInUse') ||
+               e.message.include?('being accessed by other users') ||
+               e.message.include?('deadlock') ||
+               e.message.include?('lock timeout')
+
+              if attempts < max_attempts
+                wait_time = 2**(attempts - 1) # Exponential backoff: 1, 2, 4, 8, 16
+                Rails.logger.warn(
+                  "Failed to drop schema #{name} (attempt #{attempts}/#{max_attempts}): " \
+                  "#{e.message}. Retrying in #{wait_time}s..."
+                )
+                sleep(wait_time)
+              else
+                # Max attempts reached
+                Rails.logger.error("Failed to drop schema #{name} after #{max_attempts} attempts: #{e.message}")
+                if raise_on_failure
+                  raise SchemaDropError,
+                        "Failed to drop schema '#{name}' after #{max_attempts} attempts: #{e.message}"
+                else
+                  return false
+                end
+              end
+            else
+              # Non-retryable error
+              Rails.logger.error("Non-retryable error dropping schema #{name}: #{e.message}")
+              if raise_on_failure
+                raise SchemaDropError, "Failed to drop schema '#{name}': #{e.message}"
+              else
+                return false
+              end
+            end
+          end
+        end
+
+        # Should not reach here, but handle it
+        if raise_on_failure
+          raise SchemaDropError, "Failed to drop schema '#{name}' after #{max_attempts} attempts: #{last_error&.message}"
+        else
+          false
+        end
+      end
+
+      # Terminate all active connections to a specific schema
+      #
+      # @param name [String] The schema name
+      def terminate_schema_connections(name)
+        Rails.logger.info("Terminating known schema-scoped idle connections for schema: #{name}")
+
+        sql = <<~SQL.squish
+          SELECT pg_terminate_backend(pg_stat_activity.pid)
+          FROM pg_stat_activity
+          WHERE pg_stat_activity.datname = current_database()
+            AND pid <> pg_backend_pid()
+            AND state = 'idle'
+            AND query ILIKE 'SET search_path TO "#{connection.quote_string(name)}"%'
+        SQL
+
+        begin
+          connection.execute(sql)
+        rescue StandardError => e
+          Rails.logger.warn("Error terminating connections for schema #{name}: #{e.message}")
+          # Don't raise - this is a best-effort operation
+        end
+      end
+
+      # Find schemas that don't have a corresponding organization
+      #
+      # @return [Array<String>] List of orphaned schema names
+      def find_orphaned_schemas
+        all_tenant_schemas = tenant_schemas
+        tenant_class = PostgresMultitenant.tenant_class
+        return [] unless tenant_class
+
+        tenant_schema_names = []
+        if tenant_class.respond_to?(:find_each)
+          tenant_class.find_each do |tenant|
+            schema_name = PostgresMultitenant.schema_name_for(tenant)
+            tenant_schema_names << schema_name if schema_name.present?
+          end
+        else
+          tenant_class.all.each do |tenant|
+            schema_name = PostgresMultitenant.schema_name_for(tenant)
+            tenant_schema_names << schema_name if schema_name.present?
+          end
+        end
+
+        orphaned = all_tenant_schemas - tenant_schema_names
+        orphaned
+      end
+
+      # Clean up all orphaned schemas (schemas without corresponding organizations)
+      #
+      # @param dry_run [Boolean] If true, only report what would be cleaned (default: false)
+      # @return [Hash] Cleanup report with :cleaned, :failed, or :would_clean keys
+      def cleanup_orphaned_schemas(dry_run: false)
+        orphaned = find_orphaned_schemas
+
+        if orphaned.empty?
+          Rails.logger.info('No orphaned schemas found')
+          return { cleaned: [], failed: [], would_clean: [] }
+        end
+
+        Rails.logger.info("Found #{orphaned.size} orphaned schema#{'s' if orphaned.size != 1}: #{orphaned.join(', ')}")
+
+        if dry_run
+          Rails.logger.info("DRY RUN: Would clean up #{orphaned.size} schema#{'s' if orphaned.size != 1}")
+          return { would_clean: orphaned }
+        end
+
+        cleaned = []
+        failed = []
+
+        orphaned.each do |schema_name|
+          begin
+            drop_schema_with_retry(schema_name, raise_on_failure: true)
+            Rails.logger.info("Successfully cleaned up orphaned schema: #{schema_name}")
+            cleaned << schema_name
+          rescue StandardError => e
+            Rails.logger.error("Failed to clean up orphaned schema #{schema_name}: #{e.message}")
+            failed << schema_name
+          end
+        end
+
+        Rails.logger.info("Cleanup complete. Cleaned: #{cleaned.size}, Failed: #{failed.size}")
+        { cleaned: cleaned, failed: failed }
+      end
+
+      private
+
+      def switch_to(name)
+        name = normalize_schema_name(name)
+        conn = connection
+        ensure_schema_search_path_supported!(conn)
+
+        quoted = conn.quote_table_name(name)
+        conn.schema_search_path =
+          if name == 'public'
+            quoted
+          else
+            "#{quoted},public"
+          end
+      end
+
+      def validate_schema_name!(name)
+        name = normalize_schema_name(name)
+
+        raise ArgumentError, 'Schema name cannot be blank' if name.blank?
+        raise ArgumentError, 'Schema name contains invalid characters' unless name =~ /\A[a-z][a-z0-9_]*\z/
+        raise ArgumentError, 'Schema name is reserved' if RESERVED_SCHEMAS.include?(name)
+        raise ArgumentError, 'Schema name cannot start with pg_' if name.start_with?(SYSTEM_SCHEMA_PREFIX)
+      end
+
+      def normalize_schema_name(name)
+        name.to_s
+      end
+
+      def ensure_schema_search_path_supported!(conn)
+        return if conn.respond_to?(:schema_search_path) && conn.respond_to?(:schema_search_path=)
+
+        raise UnsupportedAdapterError,
+              'PostgresMultitenant requires an ActiveRecord adapter with schema_search_path support, such as PostgreSQL.'
+      end
+
+      def load_schema_file
+        # SECURITY: Load only tenant-specific tables to prevent cross-schema leaks.
+        require_relative 'tenant_schema_loader'
+        TenantSchemaLoader.load_into_current_schema
+      end
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+    end
+  end
+end

data/lib/postgres_multitenant/tenant_schema_loader.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module PostgresMultitenant
+  # Loads tenant schemas without using eval on regex-extracted fragments.
+  class TenantSchemaLoader
+    class << self
+      def load_into_current_schema
+        schema_file = tenant_schema_file
+        return unless schema_file
+
+        load_full_schema_file(schema_file)
+        prune_non_tenant_tables! unless schema_file.basename.to_s == 'tenant_schema.rb'
+
+        create_rails_metadata_tables
+      end
+
+      private
+
+      def tenant_schema_file
+        tenant_schema = Rails.root.join('db', 'tenant_schema.rb')
+        return tenant_schema if File.exist?(tenant_schema)
+
+        schema = Rails.root.join('db', 'schema.rb')
+        return schema if File.exist?(schema)
+
+        nil
+      end
+
+      def load_full_schema_file(schema_file)
+        # schema.rb/tenant_schema.rb is trusted application code generated by Rails.
+        # Loading the full file avoids fragile regex extraction and eval calls.
+        Kernel.load(schema_file.to_s)
+      rescue StandardError => e
+        raise StandardError, "Failed to load tenant schema from #{schema_file}: #{e.message}"
+      end
+
+      def prune_non_tenant_tables!
+        connection = ActiveRecord::Base.connection
+        keep_tables = SchemaManager.tenant_tables + %w[ar_internal_metadata schema_migrations]
+        drop_tables = connection.tables - keep_tables
+
+        drop_tables.each do |table|
+          connection.execute("DROP TABLE IF EXISTS #{connection.quote_table_name(table)} CASCADE")
+        end
+      end
+
+      def create_rails_metadata_tables
+        connection = ActiveRecord::Base.connection
+
+        connection.transaction(requires_new: true) do
+          create_ar_internal_metadata(connection)
+          create_schema_migrations(connection)
+        end
+      end
+
+      def create_ar_internal_metadata(connection)
+        connection.execute(<<-SQL)
+          CREATE TABLE IF NOT EXISTS ar_internal_metadata (
+            key character varying NOT NULL,
+            value character varying,
+            created_at timestamp(6) without time zone NOT NULL,
+            updated_at timestamp(6) without time zone NOT NULL,
+            PRIMARY KEY (key)
+          );
+        SQL
+      end
+
+      def create_schema_migrations(connection)
+        connection.execute(<<-SQL)
+          CREATE TABLE IF NOT EXISTS schema_migrations (
+            version character varying NOT NULL,
+            PRIMARY KEY (version)
+          );
+        SQL
+      end
+    end
+  end
+end

data/lib/postgres_multitenant/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PostgresMultitenant
+  VERSION = '0.1.0'
+end

data/lib/postgres_multitenant.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative 'postgres_multitenant/version'
+require_relative 'postgres_multitenant/configuration'
+require_relative 'postgres_multitenant/schema_manager'
+require_relative 'postgres_multitenant/tenant_schema_loader'
+require_relative 'postgres_multitenant/middleware'
+require_relative 'postgres_multitenant/connection_pool_extensions'
+require_relative 'postgres_multitenant/railtie' if defined?(Rails)
+
+# PostgresMultitenant module provides multi-tenancy support for Rails applications
+# using PostgreSQL schemas.
+module PostgresMultitenant
+  class TenantNotFoundError < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def tenant_class
+      configuration.tenant_class
+    end
+
+    def find_tenant_by_subdomain(subdomain)
+      SchemaManager.with_schema('public') do
+        if configuration.tenant_finder
+          configuration.tenant_finder&.call(subdomain)
+        else
+          find_tenant_using_class(subdomain)
+        end
+      end
+    end
+
+    def schema_name_for(tenant)
+      return configuration.tenant_schema_name_proc.call(tenant) if configuration.tenant_schema_name_proc
+
+      return tenant.schema_name if tenant.respond_to?(:schema_name)
+      return tenant.subdomain.tr('-', '_') if tenant.respond_to?(:subdomain)
+
+      nil
+    end
+
+    # Convenience method to switch schemas
+    def switch(tenant_name, &block)
+      SchemaManager.with_schema(tenant_name, &block)
+    end
+
+    # Convenience method to create tenant
+    def create(tenant_name)
+      SchemaManager.create_schema(tenant_name)
+    end
+
+    # Convenience method to drop tenant
+    def drop(tenant_name)
+      SchemaManager.drop_schema(tenant_name)
+    end
+
+    # Get current tenant
+    def current
+      SchemaManager.current_schema
+    end
+
+    # List all tenants
+    def tenants
+      SchemaManager.tenant_schemas
+    end
+
+    # Reset to public schema
+    def reset!
+      SchemaManager.reset!
+    end
+
+    private
+
+    def find_tenant_using_class(subdomain)
+      klass = tenant_class
+      return unless klass
+
+      relation = if configuration.tenant_scope_proc
+                   configuration.tenant_scope_proc&.call(klass)
+                 else
+                   klass.all
+                 end
+      relation.find_by(subdomain: subdomain)
+    end
+  end
+end

data/lib/tasks/postgres_multitenant.rake

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+namespace :tenants do
+  desc 'Create a new tenant schema'
+  task :create, [:name] => :environment do |_t, args|
+    name = args[:name]
+    abort 'Usage: rake tenants:create[tenant_name]' if name.blank?
+
+    puts "Creating tenant schema: #{name}"
+    PostgresMultitenant::SchemaManager.create_schema(name)
+    puts "Successfully created tenant: #{name}"
+  end
+
+  desc 'Drop a tenant schema'
+  task :drop, [:name] => :environment do |_t, args|
+    name = args[:name]
+    abort 'Usage: rake tenants:drop[tenant_name]' if name.blank?
+
+    print "Are you sure you want to drop tenant '#{name}'? This cannot be undone. [y/N] "
+    confirm = $stdin.gets.chomp.downcase
+    abort 'Aborted.' unless confirm == 'y'
+
+    puts "Dropping tenant schema: #{name}"
+    PostgresMultitenant::SchemaManager.drop_schema(name)
+    puts "Successfully dropped tenant: #{name}"
+  end
+
+  desc 'List all tenant schemas'
+  task list: :environment do
+    tenants = PostgresMultitenant::SchemaManager.tenant_schemas
+
+    if tenants.empty?
+      puts 'No tenant schemas found.'
+    else
+      puts "Tenant schemas (#{tenants.count}):"
+      tenants.each { |t| puts "  - #{t}" }
+    end
+  end
+
+  desc 'Migrate all tenant schemas'
+  task migrate: :environment do
+    tenant_class = PostgresMultitenant.tenant_class
+    if tenant_class.nil?
+      puts 'No tenant class configured for PostgresMultitenant; skipping tenant migration.'
+      next
+    end
+
+    tenants = if PostgresMultitenant.configuration.tenant_scope_proc
+                PostgresMultitenant.configuration.tenant_scope_proc.call(tenant_class)
+              else
+                tenant_class.all
+              end
+
+    if tenants.empty?
+      puts 'No active tenants to migrate.'
+      next
+    end
+
+    puts "Migrating #{tenants.count} tenant(s)..."
+
+    tenants.each do |tenant|
+      schema_name = PostgresMultitenant.schema_name_for(tenant)
+      if schema_name.blank?
+        puts "  Skipping tenant without schema name: #{tenant.inspect}"
+        next
+      end
+      puts "  Migrating: #{schema_name}"
+      unless PostgresMultitenant::SchemaManager.schema_exists?(schema_name)
+        # If a tenant exists in the public DB but its schema is missing (common in tests/dev resets),
+        # create it first (which also loads `db/schema.rb` into that schema).
+        PostgresMultitenant::SchemaManager.create_schema(schema_name)
+        next
+      end
+
+      PostgresMultitenant::SchemaManager.with_schema(schema_name) do
+        # Tenants are not migrated via ActiveRecord migrations (public tables don't exist in tenant schemas).
+        # Instead, tenant schemas are kept in sync by re-loading tenant table definitions from `db/schema.rb`.
+        PostgresMultitenant::TenantSchemaLoader.load_into_current_schema
+      end
+    end
+
+    puts 'All tenants migrated successfully.'
+  end
+
+  desc 'Rollback all tenant schemas'
+  task :rollback, [:step] => :environment do |_t, args|
+    step = (args[:step] || 1).to_i
+    abort(
+      'Tenants do not use ActiveRecord migrations (they are synced from db/schema.rb). ' \
+      "Rollback is not supported (requested step=#{step}). " \
+      'To change tenant schema, update db/schema.rb (or migrations) and run `rake tenants:migrate`.'
+    )
+  end
+
+  desc 'Show migration status for all tenants'
+  task status: :environment do
+    abort(
+      'Tenants do not use ActiveRecord migrations (they are synced from db/schema.rb). ' \
+      'Migration status is not applicable. Use `rake tenants:list` and keep tenant schemas in sync via `rake tenants:migrate`.'
+    )
+  end
+end
+
+# Enhance db:migrate to also migrate tenants
+namespace :db do
+  task migrate: :environment do
+    # After public schema migration, sync tenant schemas to match `db/schema.rb`.
+    tenant_class = PostgresMultitenant.tenant_class
+    Rake::Task['tenants:migrate'].invoke if tenant_class&.table_exists?
+  rescue StandardError => e
+    puts "ERROR: Tenant migration failed: #{e.message}"
+    raise
+  end
+end

metadata

@@ -0,0 +1,167 @@
+--- !ruby/object:Gem::Specification
+name: postgres_multitenant
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joshua Needham - DAD Studios
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Schema-based multi-tenant isolation for Rails apps backed by PostgreSQL
+  schemas.
+email:
+- oss@postgresmultitenant.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/postgres_multitenant/install/install_generator.rb
+- lib/generators/postgres_multitenant/install/templates/postgres_multitenant.rb.tt
+- lib/generators/postgres_multitenant/install/templates/tenant_schema.rb
+- lib/postgres_multitenant.rb
+- lib/postgres_multitenant/configuration.rb
+- lib/postgres_multitenant/connection_pool_extensions.rb
+- lib/postgres_multitenant/middleware.rb
+- lib/postgres_multitenant/railtie.rb
+- lib/postgres_multitenant/schema_manager.rb
+- lib/postgres_multitenant/tenant_schema_loader.rb
+- lib/postgres_multitenant/version.rb
+- lib/tasks/postgres_multitenant.rake
+homepage: https://github.com/DAD-Studios/postgres_multitenant
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/DAD-Studios/postgres_multitenant
+  changelog_uri: https://github.com/DAD-Studios/postgres_multitenant/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Schema-based multi-tenant isolation for Rails apps.
+test_files: []