--- name: activerecord-tenanted description: Expert guidance for SQLite-per-tenant Rails apps using the Basecamp activerecord-tenanted gem. Use when adding multi-tenancy, tenant databases, GlobalRecord, ApplicationRecord.with_tenant, Current.tenant, Current.account, shard swapping, db/global_migrate, or per-tenant SQLite. Do not use for Nebula-style acts_as_tenant row scoping or Fizzy same-database path tenancy. allowed-tools: Read, Grep, Glob, Write, Edit, Bash(bin/rails generate*), Bash(bin/rails db:*), Bash(bin/rails test:*), Bash(bin/rails test) --- # activerecord-tenanted (SQLite per tenant) One SQLite file per tenant via the Basecamp [`activerecord-tenanted`](https://github.com/basecamp/activerecord-tenanted) gem. Identity, sessions, and the tenant row live in a **global** database. Product data lives in `storage/tenants/{env}/{tenant_key}/main.sqlite3`. This is the Herald / Cortex / Innkeeper model. It is **not**: - **Nebula `acts_as_tenant`** — one database, `workspace_id` on every row - **Fizzy path tenancy** — one database, `Current.account` + `SCRIPT_NAME` URL prefix If the app already uses `acts_as_tenant` or Fizzy-style account slugs in a shared schema, do not introduce this gem. ## Philosophy 1. **Two base classes, two databases.** `GlobalRecord` never sees tenant data. `ApplicationRecord` never sees identities. 2. **No tenanted query without a tenant.** `User.find` outside `with_tenant` / `Current.tenant=` is a bug, even in jobs and rake tasks. 3. **The URL (or Current) chooses the shard.** The gem's default subdomain resolver is wrong for path-based apps — disable it. 4. **Jobs re-enter the tenant.** Active Job does not magically carry the shard. Pass a global id (account/tenant/project) and wrap `perform` in `with_tenant`. ## What Goes Where | Global (`GlobalRecord`) | Tenanted (`ApplicationRecord`) | |-------------------------|----------------------------------| | Identity, Session, MagicLink | The actual product records | | Tenant / Account | User (Cortex/Innkeeper — in-tenant profile) | | Membership (Identity ↔ tenant) | Everything else in that workspace | | JoinCode, API tokens | Active Storage blobs (when `tenanted_rails_records` is on) | Herald keeps `Project` global (so slugs/API keys exist before a shard is selected) and stores releases/subscribers in the account tenant. Cortex/Innkeeper put almost all product tables in the tenant DB. Both are fine — pick one and stay consistent. ## Step 1: Gem + database.yml ```ruby # Gemfile gem "activerecord-tenanted" ``` ```yaml # config/database.yml — every environment primary: adapter: sqlite3 database: storage/tenants/<%= Rails.env %>/%{tenant}/main.sqlite3 tenanted: true max_connection_pools: 50 global: adapter: sqlite3 database: storage/<%= Rails.env %>.sqlite3 migrations_paths: db/global_migrate queue: adapter: sqlite3 database: storage/<%= Rails.env %>_queue.sqlite3 migrations_paths: db/queue_migrate # cache + cable the same way ``` `%{tenant}` is the gem's placeholder. `database_tasks: false` on `primary` is optional (Herald sets it so Rails doesn't try to dump a single primary schema). Migrations: - `db/global_migrate/` — Identity, Tenant/Account, Membership, Session. Run once. - `db/migrate/` — tenanted tables. The gem runs these **per tenant**. ```bash bin/rails db:migrate # tenanted bin/rails db:migrate:global # global — check the gem's task name in the app ``` ## Step 2: Two abstract classes ```ruby # app/models/application_record.rb class ApplicationRecord < ActiveRecord::Base primary_abstract_class tenanted end # app/models/global_record.rb class GlobalRecord < ActiveRecord::Base self.abstract_class = true connects_to database: { writing: :global, reading: :global } end ``` New model: if it is a person, session, or the tenant row itself → `GlobalRecord`. If it is data inside a workspace → `ApplicationRecord`. Getting this wrong is the #1 bug. ## Step 3: Disable subdomain resolver + default tenant Path-based apps (all of ours) must not use the gem's subdomain resolver: ```ruby # config/initializers/tenanted.rb Rails.application.configure do config.active_record_tenanted.tenant_resolver = ->(request) { nil } config.active_record_tenanted.default_tenant = Rails.env.local? ? "#{Rails.env}-tenant" : nil config.active_record_tenanted.tenanted_rails_records = true config.active_record_tenanted.connection_class = "ApplicationRecord" end ``` **Production `default_tenant` must be `nil`.** Otherwise boot can fail with `ARTENANT not set`, or worse, every request shares one leftover shard. Locally a named default tenant lets console/tests boot. `tenanted_rails_records = true` stores Active Storage / Action Text in the tenant DB with prefixed keys. Pair with the `active-storage-multitenant` skill. ## Step 4: Current swaps the shard ```ruby class Current < ActiveSupport::CurrentAttributes attribute :identity, :session attribute :tenant # or :account — pick one name and use it everywhere attribute :user def tenant=(tenant) super return if ActiveRecord::Base.shard_swapping_prohibited? ApplicationRecord.current_tenant = tenant ? tenant.external_id : ActiveRecord::Tenanted::Tenant::UNTENANTED_SENTINEL end end ``` Herald uses `Current.account=` and `account.tenant_key` (`"account-#{id}"`). Cortex/Innkeeper use `Current.tenant=` and `tenant.external_id`. Same mechanism. Reset on request end (Cortex): ```ruby resets do next if ActiveRecord::Base.shard_swapping_prohibited? ApplicationRecord.current_tenant = ActiveRecord::Tenanted::Tenant::UNTENANTED_SENTINEL end ``` ## Step 5: Resolve tenant from the URL Do this in a controller concern, not the gem resolver: ```ruby module TenantScoping extend ActiveSupport::Concern included do before_action :set_current_tenant before_action :set_current_user end def set_current_tenant record = Tenant.find_by(external_id: params[:tenant_external_id]) Current.tenant = record if record end def set_current_user return unless Current.identity && Current.tenant Current.user = User.find_by(identity_id: Current.identity.id) end end ``` Routes nest under the tenant key (`/:tenant_external_id/...` or a project slug that loads Account). Unauthenticated pages (sign-in, webhooks from vendors) skip this and wrap only the tenanted work. Create the tenant database when the Tenant/Account is created: ```ruby after_create :provision_tenant_database def ensure_tenant_database! ApplicationRecord.create_tenant(tenant_key) unless database_exists? rescue ActiveRecord::Tenanted::TenantExistsError # parallel tests / retries end ``` ## Step 6: Jobs, rake, console ```ruby def perform(tenant_external_id, record_id) ApplicationRecord.with_tenant(tenant_external_id) do Current.tenant = Tenant.find_by(external_id: tenant_external_id) Record.find(record_id).do_work end end ``` Never serialize a tenanted Active Record as a GID and expect `perform` to load it — the job runs untenanted. Pass the **global** tenant key plus the record id. Rake / one-off: ```ruby Tenant.find_each do |tenant| ApplicationRecord.with_tenant(tenant.external_id) do puts Project.count end end ``` Public inbound webhooks with no tenant in the URL: iterate tenants (Innkeeper) or look up a global token that points at a tenant, then `with_tenant`. Don't query `User` at the top of the job. ## Tests Every test that touches tenanted models must set a tenant. Use a helper: ```ruby def with_tenant(tenant = tenants(:acme), &block) ApplicationRecord.with_tenant(tenant.external_id, &block) end ``` Integration tests: hit a URL that includes the tenant prefix so `TenantScoping` runs. Don't stub `Current.tenant` and then assert on HTTP — the shard won't match the request. ## Anti-Patterns 1. **`acts_as_tenant :workspace` in an app that's already tenanted** — two tenancy systems. Nebula is the other model; don't mix. 2. **Putting Identity or Session on ApplicationRecord** — those tables must survive switching shards. 3. **`User.find` in a job without `with_tenant`** — silent empty results or `TenantNotSet`. 4. **Leaving the subdomain resolver on** — path-based apps resolve the wrong tenant or none. 5. **`default_tenant` in production** — every process shares one database file. 6. **Assuming integer PKs in tenant DBs** — our tenanted tables are UUIDs. See `uuid-primary-keys`. 7. **Creating blobs without a current tenant** — "Cannot generate a Blob key without a tenant." Use `with_tenant` and the Active Storage skill. ## Related - Identity vs User, memberships, join codes: `identity-membership` - Tenanted Active Storage / Lexxy: `active-storage-multitenant` - Outbound webhooks that run in a tenant: `outgoing-webhooks` - Passwordless sign-in (global Identity): `magic-link-auth` See [reference.md](reference.md) for database.yml, Herald vs Cortex naming, and shard-swap gotchas.