Powerful Features

Installation

Requirements

• Ruby 3.0+
• Rails 7.0+ (optimized for Rails 8)
• PostgreSQL 12+

Setup

Add to your Gemfile:

gem 'pg_multitenant_schemas'
bundle install

Configuration

Create config/initializers/pg_multitenant_schemas.rb:

PgMultitenantSchemas.configure do |config|
  config.connection_class = 'ApplicationRecord'
  config.tenant_model_class = 'Tenant'
  config.default_schema = 'public'
  config.excluded_subdomains = ['www', 'api', 'admin']
  config.development_fallback = true
  config.auto_create_schemas = true
end

Quick Start

Migrate All Tenants

# Migrate all tenant schemas at once
rails tenants:migrate

# Migrate a specific tenant
rails tenants:migrate_tenant[acme_corp]

# Check migration status
rails tenants:status

Create New Tenant

# Create tenant with setup (schema + migrations)
rails tenants:create[new_tenant]

# Create with attributes
rails tenants:new['{"subdomain":"acme","name":"ACME Corp"}']

Context Management

// Switch to tenant context
PgMultitenantSchemas.switch_to_tenant(tenant)

# Use with block
PgMultitenantSchemas.with_tenant(tenant) do
  User.all  # Queries tenant's schema
end

# Get current context
PgMultitenantSchemas.current_schema  #=> "tenant_123"

Rails Integration

class ApplicationController < ActionController::Base
  include PgMultitenantSchemas::Rails::ControllerConcern
  
  before_action :resolve_tenant
  
  private
  
  def resolve_tenant
    tenant = resolve_tenant_from_subdomain
    switch_to_tenant(tenant) if tenant
  end
end

API Reference

Context Class

PgMultitenantSchemas::Context.current_schema
#=> "tenant_123"

PgMultitenantSchemas::Context.current_tenant
#=> #<Tenant id=1, subdomain="acme">

PgMultitenantSchemas::Context.switch_to_tenant(tenant)
# Now all queries use tenant's schema

PgMultitenantSchemas::Context.with_tenant(tenant) do
  User.all  # Queries tenant's schema
  Order.create!(...)
end
# Context restored here

SchemaSwitcher Class

if PgMultitenantSchemas::SchemaSwitcher.schema_exists?('tenant_123')
  # Schema exists
end

PgMultitenantSchemas::SchemaSwitcher.list_schemas
#=> ["public", "tenant_123", "tenant_456"]

Migrator Class

results = PgMultitenantSchemas::Migrator.migrate_all
#=> {
#     success: ["tenant_1", "tenant_2"],
#     failed: [],
#     total_migrations: 5
#   }

PgMultitenantSchemas::Migrator.migration_status
#=> {
#     "tenant_1" => { status: :up_to_date, pending: 0 },
#     "tenant_2" => { status: :pending, pending: 2 }
#   }

Common Patterns

Subdomain-Based Routing

class ApplicationController < ActionController::Base
  include PgMultitenantSchemas::Rails::ControllerConcern
  
  before_action :authenticate_user!
  before_action :resolve_tenant_from_subdomain
  before_action :ensure_user_in_tenant
  
  private
  
  def resolve_tenant_from_subdomain
    @tenant = resolve_tenant_from_request(request)
    switch_to_tenant(@tenant) if @tenant
  end
  
  def ensure_user_in_tenant
    redirect_unless current_user.tenant == @tenant
  end
end

Background Jobs with Tenant Context

class ProcessOrderJob
  include Sidekiq::Worker
  
  def perform(order_id, tenant_id)
    tenant = Tenant.find(tenant_id)
    
    PgMultitenantSchemas.with_tenant(tenant) do
      order = Order.find(order_id)
      # Process order in tenant's schema
      order.process!
    end
  end
end

# Enqueue with tenant context
tenant = Tenant.first
ProcessOrderJob.perform_async(order.id, tenant.id)

Cross-Tenant Admin Operations

class AdminController < ApplicationController
  def platform_stats
    stats = {}
    
    Tenant.find_each do |tenant|
      PgMultitenantSchemas.with_tenant(tenant) do
        stats[tenant.subdomain] = {
          users_count: User.count,
          orders_count: Order.count,
          revenue: Order.sum(:amount)
        }
      end
    end
    
    render json: stats
  end
end

Testing with Tenants

RSpec.describe User, type: :model do
  let(:tenant) { create(:tenant) }
  
  before { PgMultitenantSchemas.switch_to_tenant(tenant) }
  after { PgMultitenantSchemas.reset! }
  
  it 'creates user in tenant schema' do
    user = create(:user)
    
    PgMultitenantSchemas.with_tenant(tenant) do
      expect(User.find(user.id)).to eq(user)
    end
  end
end

Complete Documentation

Core Components

Guides

• Testing Guide - RSpec test suite and testing patterns
• Integration Testing - PostgreSQL integration testing
• Error Handling - Exception classes and error management
• CI/CD Setup - GitHub Actions automation

Troubleshooting

• GitHub Actions Permissions
• Local Workflow Testing

Production Ready