ActiveRecord::Tenanted

ActiveRecord::Tenanted enables a Rails application to host multiple isolated tenants. It is designed so that developing a multi-tenant app feels as easy as developing a single-tenant app; your application code should not need to be aware of the tenant isolation logic.

The gem follows these guiding principles:

• Data at rest: Persisted in separate stores for each tenant, isolated physically or logically.
• Data in transit: Only sent to users with authenticated access to the specific tenant instance.
• Isolated execution: All tenant-related code execution happens within a well-defined isolated tenant context with controls around data access.

IMPORTANT

Currently, only the sqlite3 database adapter is fully supported. If you need to tenant other database types supported by Rails, contact the maintainers.

To add activerecord-tenanted to your Rails application, add the gem to your Gemfile using the following command:

bundle add activerecord-tenanted

The TenantSelector middleware automates tenant switching based on the request environment. It relies on two configuration settings: connection_class and tenant_resolver.

Behavioral Logic:

1. No Tenant Resolved: If the tenant_resolver returns a blank value, the request proceeds without a tenanted context. Application code can manually set the tenant later.
2. Tenant Resolved & Exists: If the resolver returns a name and the connection_class confirms the tenant exists, the entire request is wrapped in a with_tenant(tenant_name) block, locking the application to that tenant's database.
3. Tenant Resolved but Missing: If the resolver returns a name but the tenant does not exist in the system, the middleware raises an ActiveRecord::Tenanted::TenantDoesNotExistError (which typically results in a 404 response in a Rails application).

When ActiveRecord::Tenanted is configured, the key for an ActiveStorage::Blob is automatically prefixed with the current tenant's identifier to ensure file isolation on disk.

The generated key follows the format: {tenant}/{unique_token}

This ensures that even if multiple tenants use the same underlying disk service, their files are stored in distinct subdirectories based on the tenant name.

To ensure that ActionCable commands (like subscribing to a channel) are executed within the correct tenant context, you must include ActiveRecord::Tenanted::CableConnection::Base in your ActionCable::Connection::Base class.

This module uses identified_by :current_tenant to track the tenant and around_command :with_tenant to wrap ActionCable commands in a connection_class.with_tenant block.

For this to work, you must have configured a tenant_resolver and a connection_class in your Rails.application.config.active_record_tenanted settings.

class ApplicationCable::Connection < ActionCable::Connection::Base
  prepend ActiveRecord::Tenanted::CableConnection::Base
end

When using the DiskService for Active Storage, ActiveRecord::Tenanted requires an active tenant to be set on the connection class. If you attempt to access the disk service or generate a Blob key while ActiveRecord::Tenanted.connection_class.current_tenant is nil, a NoTenantError will be raised.

Common scenarios:

• Accessing Active Storage files in a background job or console session where the tenant context has not been explicitly set.
• Attempting to generate a new ActiveStorage::Blob without a current tenant context.

# This will raise NoTenantError if no tenant is set
ActiveStorage::DiskService.new.root

# Ensure tenant is set before accessing storage
ActiveRecord::Tenanted.with_tenant(tenant) do
  # Storage operations are now safe
end

The library enforces tenant safety to prevent accidental data leakage. You may encounter these errors:

• NoTenantError: Raised when attempting to access a tenanted model while no tenant context is active (i.e., current_tenant is nil).
• WrongTenantError: Raised when a model instance belongs to one tenant, but the current active connection context is set to a different tenant. This typically happens if you try to associate or save a record across tenant boundaries.

The ActiveRecord::Tenanted::DatabaseTasks class provides a method to register custom Rake tasks that mirror standard Rails database tasks but operate on tenanted databases. Once registered, you can use these tasks to migrate, drop, or reset tenant databases.

When running these tasks, you can target a specific tenant by setting the ARTENANT environment variable. If ARTENANT is not set, the tasks will default to all tenants (or the default tenant configured in your local environment).

# Assuming 'tasks' is an instance of ActiveRecord::Tenanted::DatabaseTasks
tasks.register_rake_tasks

The base_configs method returns an array of database configurations that are marked as tenanted. It filters the provided configurations (defaulting to ActiveRecord::Base.configurations) based on the presence of the :tenanted key in the configuration hash.

ActiveRecord::Tenanted.base_configs