multi-tenancy

Multi-Tenancy in Rails

Most B2B SaaS Rails apps need multi-tenancy. AI agents default to either too-loose (forgetting tenant_id filters) or too-aggressive (one database per tenant for an MVP). The right answer is almost always row-scoped tenancy with a defense-in-depth gem.

The opinion

Default to row-scoped tenancy with a tenant_id (or account_id / organization_id) column on every tenant-owned table. Use acts_as_tenant for automatic scoping that fails closed when tenant isn't set. Resolve tenant by subdomain or path. Pass tenant to every background job. Per-schema and per-database tenancy exist but should be reserved for compliance / data-residency reasons (HIPAA, GDPR, single-tenant Enterprise plans).

Why row-scoped:

• One database, one schema, one migration. Operationally simple.
• Easy cross-tenant analytics (one query, not 1000).
• Cost: query overhead per row vs separate table — negligible on a tenant_id index.

Counter-positions:

• apartment gem (schema-per-tenant) — strong isolation, but breaks Rails 6+ multi-DB, fragile under migrations. Largely unmaintained.
• Database-per-tenant — strongest isolation, hardest ops. Reserve for regulated industries or Enterprise tier.

Pattern 1: acts_as_tenant setup

# Gemfile
gem "acts_as_tenant"

# config/initializers/acts_as_tenant.rb
ActsAsTenant.configure do |config|
  config.require_tenant = true  # raise if a tenant model is queried without a tenant set
end

require_tenant = true is the line that prevents the worst category of bugs: forgetting to scope and leaking another tenant's data.

# app/models/account.rb
class Account < ApplicationRecord
  has_many :users, dependent: :destroy
  has_many :posts, dependent: :destroy
end

# app/models/post.rb
class Post < ApplicationRecord
  acts_as_tenant :account
  validates :title, presence: true
end

Migration:

class AddAccountIdToPosts < ActiveRecord::Migration[8.0]
  def change
    add_reference :posts, :account, null: false, foreign_key: true, index: true
  end
end