acts_as_tenant Documentation

When testing, you must ensure the tenant is cleaned up after each test. For integration/request tests, use ActsAsTenant::TestTenantMiddleware to handle the test_tenant value, which survives across requests better than current_tenant.

1. Configure Middleware

In test.rb:

require_dependency 'acts_as_tenant/test_tenant_middleware'

Rails.application.configure do
  config.middleware.use ActsAsTenant::TestTenantMiddleware
end

2. Configure RSpec/Test Setup

In spec_helper.rb:

config.before(:suite) do |example|
  $default_account = Account.create!
end

config.before(:each) do |example|
  if example.metadata[:type] == :request
    ActsAsTenant.test_tenant = $default_account
  else
    ActsAsTenant.current_tenant = $default_account
  end
end

config.after(:each) do |example|
  ActsAsTenant.current_tenant = nil
  ActsAsTenant.test_tenant = nil
end

# test.rb
require_dependency 'acts_as_tenant/test_tenant_middleware'

Rails.application.configure do
  config.middleware.use ActsAsTenant::TestTenantMiddleware
end

There are three primary ways to set the current tenant in a Rails application:

1. By Subdomain

Use set_current_tenant_by_subdomain to identify the tenant using the last subdomain. It assumes the tenant model (e.g., Account) has a column named :subdomain.

class ApplicationController < ActionController::Base
  set_current_tenant_by_subdomain(:account, :subdomain)
end

To use the first subdomain instead of the last, pass subdomain_lookup: :first.

2. By Subdomain or Domain

Use set_current_tenant_by_subdomain_or_domain to check for a subdomain and fallback to a domain if the subdomain is not present.

class ApplicationController < ActionController::Base
  set_current_tenant_by_subdomain_or_domain(:account, :subdomain, :domain)
end

3. Manually via before_action

If you need custom logic to find the tenant, use set_current_tenant_through_filter and a before_action.

Note: If setting the tenant in a specific controller (other than ApplicationController), the declaration must be at the TOP of the file.

class MembersController < ActionController::Base
  set_current_tenant_through_filter
  before_action :set_tenant
  before_action :set_member, only: [:show, :edit, :update, :destroy]

  def set_tenant
    set_current_tenant(current_user.account)
  end
end

You can configure acts_as_tenant via an initializer (e.g., config/initializers/acts_as_tenant.rb).

Configuration Options

• config.require_tenant: When set to true, ActsAsTenant::NoTenant is raised if a query is made without a tenant set. This can also be a lambda that evaluates at runtime.
• config.job_scope: A lambda used to customize the query for loading the tenant in background jobs.

ActsAsTenant.configure do |config|
  config.require_tenant = true
  config.job_scope = ->{ all }
end

Conditional requirement via Lambda

You can use a lambda for require_tenant to exclude certain paths (like admin routes) from requiring a tenant:

ActsAsTenant.configure do |config|
  config.require_tenant = lambda do
    if $request_env.present?
      return false if $request_env["REQUEST_PATH"].start_with?("/admin/")
    end
    true
  end
end

ActsAsTenant.configure do |config|
  config.require_tenant = false
  config.job_scope = ->{ all }
end

To ensure the current tenant context is preserved when pushing jobs to Sidekiq and automatically restored when the worker executes, you must add the ActsAsTenant::Sidekiq middleware to both your Sidekiq client and server configurations.

Client Configuration

Add ActsAsTenant::Sidekiq::Client to your client middleware chain. This captures the current tenant's class and ID and injects them into the Sidekiq job message.

Server Configuration

Add ActsAsTenant::Sidekiq::Server to your server middleware chain. This extracts the tenant information from the job message and wraps the job execution in an ActsAsTenant.with_tenant block.

Note: The middleware automatically handles different Sidekiq versions and attempts to insert itself before RetryJobs or Batch::Server to ensure correct context during retries or batches.

Sidekiq.configure_client do |config|
  config.client_middleware do |chain|
    chain.add ActsAsTenant::Sidekiq::Client
  end
end

Sidekiq.configure_server do |config|
  config.client_middleware do |chain|
    chain.add ActsAsTenant::Sidekiq::Client
  end
  config.server_middleware do |chain|
    if defined?(Sidekiq::Middleware::Server::RetryJobs)
      chain.insert_before Sidekiq::Middleware::Server::RetryJobs, ActsAsTenant::Sidekiq::Server
    elsif defined?(Sidekiq::Batch::Server)
      chain.insert_before Sidekiq::Batch::Server, ActsAsTenant::Sidekiq::Server
    else
      chain.add ActsAsTenant::Sidekiq::Server
    end
  end
end

To enable row-level multitenancy on a model, you must first ensure the table has a foreign key column linking it to the tenant (e.g., account_id). Then, call acts_as_tenant in the model.

Important: acts_as_tenant automatically includes the belongs_to relationship. Do not manually add belongs_to :account if you are using acts_as_tenant(:account).

Basic Usage

class Project < ActiveRecord::Base
  acts_as_tenant(:account)
end

Custom Foreign and Primary Keys

If your schema uses non-standard naming, specify them explicitly:

acts_as_tenant(:account, :foreign_key => 'accountID', :primary_key => 'primaryID')

Scoping HABTM relationships

For models in a Has and Belongs to Many relationship, use the through option:

class User < ActiveRecord::Base
  acts_as_tenant :organisation, through: :organisations_users
end

Passing belongs_to options

You can pass standard belongs_to options directly to acts_as_tenant:

acts_as_tenant(:account, counter_cache: true, optional: true)