thinkoodle/rails-skills

activerecord-tenanted

Expert guidance for SQLite-per-tenant Rails apps using the Basecamp activerecord-tenanted gem.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/thinkoodle/rails-skills --skill activerecord-tenanted

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

activerecord-tenanted (SQLite per tenant)

One SQLite file per tenant via the 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, MagicLinkThe actual product records
Tenant / AccountUser (Cortex/Innkeeper — in-tenant profile)
Membership (Identity ↔ tenant)Everything else in that workspace
JoinCode, API tokensActive 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 for database.yml, Herald vs Cortex naming, and shard-swap gotchas.

du même dépôt

Autres Skills

Tous les Skills
thinkoodle
Communauté

action-cable

Expert guidance for implementing real-time features with Action Cable in Rails applications. Use when working with websockets, channels, subscriptions, broadcasting, live updates, push notifications, or Solid Cable. Covers connection authentication, channel creation, streaming, client-side JS, testing, and deployment. Clarifies when to use Action Cable directly vs Turbo Streams broadcasting.

Installations / 1h
1
GitHub Stars
7
Mis à jour
8 sept.
thinkoodle
Communauté

action-controller

Expert guidance for writing Rails controllers with Action Controller. Use when writing controller actions, strong parameters, beforeaction filters, rendering responses, redirects, flash messages, sessions, cookies, rescuefrom error handling, streaming, CSRF protection, or HTTP authentication. Covers params permitting (especially nested params — the 1 source of agent bugs), callbacks, request/response objects, and security. Trigger on "controller", "action", "strong parameters", "params", "before

Installations / 1h
1
GitHub Stars
7
Mis à jour
8 sept.
thinkoodle
Communauté

action-mailbox

Expert guidance for receiving and processing inbound emails with Action Mailbox in Rails. Use when setting up inbound email processing, routing emails to mailboxes, configuring ingress providers (Mailgun, SendGrid, Postfix, etc.), handling attachments, bouncing emails, or testing with fixtures. Covers "action mailbox", "inbound email", "receive email", "process email", "email routing", "mailbox", "incoming email", "email processing", "ingress", "InboundEmail".

Installations / 1h
1
GitHub Stars
7
Mis à jour
8 sept.
thinkoodle
Communauté

active-model

Build plain Ruby objects that integrate with Rails forms, validations, serialization, and Action Pack — without a database. Use when building form objects, search forms, API wrappers, configuration objects, virtual models, or any PORO that needs model-like behavior. Triggers on "active model", "form object", "plain Ruby object", "non-database model", "ActiveModel", "PORO", "service object validation", "virtual model", "tableless model", "search form", "ActiveModel::API", "ActiveModel::Model".

Installations / 1h
1
GitHub Stars
7
Mis à jour
8 sept.