rails-tenantify 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c660926719f56e3805e0d1622366992096727f7cd25e409b6a95fb9c15152cb
-  data.tar.gz: 3f0c9b560f399bfb374518a575a14c36e3b0489b35ffd3c5e948eb8c6c321335
+  metadata.gz: 7564a95a2b8be9ed97bb29115162b1c16140676551f09bb4f2f75247bb7d6c28
+  data.tar.gz: 854c340a1a2eb188fff7cc1743d54df24029f636338bdf5ba20c9a743b7492bc
 SHA512:
-  metadata.gz: '083c79279cb7edd789d63e134b1a0e0f9d11e2f616468e759b545d6c417675486f25b7efd71f1fb80e15e613c9b46a079480d1791a9816548785bb96873d1d95'
-  data.tar.gz: 4dc62b900ccaced8c5ee4b652fb750275eda1ca92fcf876632f4efe87b8bdaddf6c4e29384d34bd1e41fee61791748c6c362d630f92cc6ecc658cbbc51261c4f
+  metadata.gz: dd44ab9ef42d723a50e76e21d498b3401c150017ae755060c79549f50047af2bc22d874ec5c0e8c651a085371bcf7973a47ee3e2f631bbebb789adaa43fd428b
+  data.tar.gz: e693933f5076251b9e0a2053e6c6e0ad7d905dd9bc328f137716ca8fdfe075454ecf775f026c5bcb411b56e3dcef7b8bf107ba5f373cf2be2b01b0bcd7fabd17

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.2] - 2026-06-01
+
+### Fixed
+
+- Pin `connection_pool` `< 3`, `minitest` `< 6`, and `sqlite3` `< 2` in the Gemfile so Ruby 3.1 CI can run (latest majors require Ruby >= 3.2)
+
+## [0.1.1] - 2026-06-01
+
+### Fixed
+
+- Add `lib/rails-tenantify.rb` so Bundler/Rails load the full gem API ([#1](https://github.com/sghani001/rails-tenantify/issues/1))
+- Guard `Tenantify::Railtie` so it always requires `tenantify` first — fixes `undefined method 'configure' for Tenantify:Module` in Rails initializers
+
 ## [0.1.0] - 2026-06-01
 
 Published as **`rails-tenantify`** on RubyGems (`gem "rails-tenantify"`). The name `tenantify` is already used by an unrelated gem from 2016.

data/README.md

@@ -1,52 +1,109 @@
-# rails-tenantify
+# rails-tenantify 🏢
 
-**Modern row-level multi-tenancy for Rails 7+ / Ruby 3.1+**
-
-The RubyGems package is [`rails-tenantify`](https://rubygems.org/gems/rails-tenantify). The library is required as `tenantify` (same pattern as `rails-persona` → `persona`).
+> Row-level multi-tenancy for Rails — scoped models, job-safe context, zero schema-per-tenant complexity.
 
+[![Gem Version](https://img.shields.io/gem/v/rails-tenantify.svg)](https://rubygems.org/gems/rails-tenantify)
+[![Downloads](https://img.shields.io/gem/dt/rails-tenantify.svg)](https://rubygems.org/gems/rails-tenantify)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![CI](https://github.com/sghani001/rails-tenantify/actions/workflows/ci.yml/badge.svg)](https://github.com/sghani001/rails-tenantify/actions/workflows/ci.yml)
+![Rails](https://img.shields.io/badge/Rails-7.0%2B-red)
+![Ruby](https://img.shields.io/badge/Ruby-3.1%2B-cc342d)
+![SQLite](https://img.shields.io/badge/SQLite-compatible-blue)
+![PostgreSQL](https://img.shields.io/badge/PostgreSQL-compatible-blue)
+![Stable](https://img.shields.io/badge/stable-0.1.2-brightgreen)
 
-Tenantify is a maintained alternative to `acts_as_tenant`: automatic model scoping, controller resolution, background-job context, bulk-write guards, and test helpers — built for Rails 7 and 8.
+**rails-tenantify** is a lightweight Rails gem for **row-level multi-tenancy**. Unlike [apartment](https://github.com/influitive/apartment), which switches entire databases or schemas per tenant, rails-tenantify keeps a single database and scopes records with a foreign key — the same model as [acts_as_tenant](https://github.com/ErwinM/acts_as_tenant), but maintained for **Rails 7+**, with **retry-safe jobs**, **bulk-write guards**, and **first-class test helpers**.
 
-## Installation
+The RubyGems package is [`rails-tenantify`](https://rubygems.org/gems/rails-tenantify). Require the library as `tenantify` (same pattern as `rails-persona` → `persona`).
+
+---
+
+## Compatibility
+
+| | Version |
+|---|---|
+| Ruby | >= 3.1 |
+| Rails | >= 7.0 (tested on 7.1) |
+| Database | SQLite3, PostgreSQL, MySQL |
+
+---
 
-Add to your `Gemfile`:
+## Why rails-tenantify over acts_as_tenant?
+
+| | acts_as_tenant | rails-tenantify |
+|---|---|---|
+| Maintenance | Stagnant / issue backlog | Actively maintained |
+| Rails 7 / 8 | Partial | Full |
+| Sidekiq retry loses tenant | Known issue ([#356](https://github.com/ErwinM/acts_as_tenant/issues/356)) | Tenant ID in payload + middleware |
+| `update_all` / `delete_all` scoped | Unreliable | Raises unless intentionally bypassed |
+| Cross-tenant association checks | Manual | Built-in validation |
+| Tenant override protection | None | `:log`, `:raise`, or `:ignore` |
+| API / header resolver | DIY | `set_tenant_by :header` |
+| RSpec helpers | Partial | `with_tenant` / `without_tenant` |
+| Test suite | Aging | RSpec, CI on Ruby 3.1–3.3 |
+
+---
+
+## Installation
 
 ```ruby
-gem "rails-tenantify"
+gem "rails-tenantify", "~> 0.1.2", require: "rails-tenantify"
 ```
 
 ```bash
 bundle install
 ```
 
+> **Requires v0.1.1+** — fixes `undefined method 'configure' for Tenantify:Module`. Use **v0.1.2+** on Ruby 3.1.
+
 Create `config/initializers/tenantify.rb`:
 
 ```ruby
 Tenantify.configure do |config|
   config.tenant_model = "Organization"
   config.on_tenant_not_found = :raise   # :raise, :redirect, :null_tenant
-  config.audit_overrides = :log         # :log, :raise, :ignore
+  config.audit_overrides   = :log       # :log, :raise, :ignore
 end
 ```
 
+Add a tenant reference to scoped models (example):
+
+```bash
+rails g migration AddOrganizationToProjects organization:references
+rails db:migrate
+```
+
+---
+
 ## Quick start
 
-### Models
+### 1. Define your tenant model
+
+```ruby
+class Organization < ApplicationRecord
+  # e.g. subdomain: "acme" for acme.yourapp.com
+end
+```
+
+### 2. Scope models to a tenant
 
 ```ruby
 class Project < ApplicationRecord
   include Tenantify::Scoped
+
+  belongs_to_tenant :organization
+  has_many :tasks
+end
+
+class Task < ApplicationRecord
+  include Tenantify::Scoped
+
   belongs_to_tenant :organization
+  belongs_to :project
 end
 ```
 
-- Adds a `default_scope` for the current tenant
-- Sets the tenant foreign key on create
-- Validates the tenant cannot change after create
-- Validates associated records belong to the same tenant
-
-### Controllers
+### 3. Resolve tenant in controllers
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -57,68 +114,225 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-Resolvers live under `Tenantify::Resolvers` (`Subdomain`, `Header`). JWT and custom-domain resolvers are planned for upcoming releases.
+### 4. Use scoped queries in the request
+
+```ruby
+# Tenantify.current_tenant is set by the controller
+Project.all          # => only current organization's projects
+Project.create!(name: "Q2 Roadmap")  # organization_id set automatically
+```
+
+---
+
+## Tenant context
+
+```ruby
+Tenantify.current_tenant           # => #<Organization id: 1 ...>
+Tenantify.current_tenant_id        # => 1
+Tenantify.tenant_scoped?           # => true
+
+Tenantify.switch_to(other_org) do
+  Project.all                      # scoped to other_org
+end
+# previous tenant restored
+
+Tenantify.without_tenant do
+  Project.delete_all               # bypasses default scope + bulk guards
+end
+```
+
+---
+
+## Controller resolvers
+
+| Resolver | Usage | Finds tenant by |
+|----------|--------|-----------------|
+| `:subdomain` | `set_tenant_by :subdomain` | `request.subdomain` → `Organization.find_by(subdomain: ...)` |
+| `:header` | `set_tenant_by :header, header: "X-Tenant-ID"` | Header value → `Organization.find_by(id: ...)` |
+
+Exclude reserved subdomains:
+
+```ruby
+set_tenant_by :subdomain, exclude: %w[www admin]
+```
+
+When no tenant is found, behavior is controlled by `on_tenant_not_found`:
+
+```ruby
+# :raise        → Tenantify::TenantNotFoundError
+# :redirect     → redirect_to fallback path
+# :null_tenant  → leave current_tenant nil
+set_tenant_by :subdomain, fallback: "/login"
+```
+
+Pluggable classes live under `Tenantify::Resolvers` (`Subdomain`, `Header`).
+
+---
+
+## Background jobs (ActiveJob + Sidekiq)
 
-### Background jobs
+Tenant context is **serialized when the job is enqueued** and **restored on perform** — including Sidekiq retries.
 
 ```ruby
 class ReportJob < ApplicationJob
   def perform
-    Tenantify.current_tenant  # restored from enqueue time
+    Tenantify.current_tenant   # same org as when the job was enqueued
+    Project.find_each { |p| p.update!(status: "exported") }
   end
 end
+
+# In a request:
+Tenantify.current_tenant = current_organization
+ReportJob.perform_later
 ```
 
-`Tenantify::Job` is included automatically for ActiveJob. Sidekiq workers get tenant metadata via middleware when Sidekiq is present.
+For native Sidekiq workers (non–ActiveJob), middleware injects `tenant_id` into the job hash and wraps execution in `Tenantify.switch_to`.
+
+---
+
+## Bulk-write protection
 
-### Switching context
+`update_all`, `delete_all`, and `destroy_all` on tenant-scoped models raise `Tenantify::TenantMismatchError` unless the relation is already limited to the current tenant:
 
 ```ruby
-Tenantify.switch_to(organization) do
-  Project.all # scoped to organization
-end
+Tenantify.current_tenant = org
+Project.update_all(status: "archived")   # OK — scoped to org
+
+Project.unscoped.update_all(status: "x") # raises TenantMismatchError
 
 Tenantify.without_tenant do
-  Project.delete_all # bypasses bulk-write protection
+  Project.update_all(status: "migrated") # OK — intentional bypass
 end
 ```
 
-### Tests
+---
+
+## Cross-tenant association validation
+
+```ruby
+Tenantify.current_tenant = org_a
+project_a = Project.create!(name: "Alpha")
+
+task = Task.new(name: "Bad", organization: org_b, project: project_a)
+task.valid?   # => false
+task.errors[:project]  # => ["belongs to a different tenant"]
+```
+
+---
+
+## Tenant override auditing
+
+```ruby
+Tenantify.configure { |c| c.audit_overrides = :raise }
+
+Tenantify.current_tenant = org_a
+Tenantify.current_tenant = org_b
+# => Tenantify::TenantOverrideError
+```
+
+Use `:log` to warn via `Rails.logger` without raising.
+
+---
+
+## Test helpers (RSpec / Minitest)
 
 ```ruby
 RSpec.configure do |config|
   config.include Tenantify::TestHelpers
 end
 
-with_tenant(organization) do
-  Project.create!(name: "Demo")
+it "creates under a tenant" do
+  with_tenant(org_a) do
+    project = Project.create!(name: "Demo")
+    expect(project.organization_id).to eq(org_a.id)
+  end
+end
+
+without_tenant do
+  Project.delete_all
 end
+
+# Minitest
+setup    { Tenantify::TestHelpers.set_tenant(org_a) }
+teardown { Tenantify::TestHelpers.clear_tenant }
 ```
 
-## Bulk-write protection
+---
 
-`update_all`, `delete_all`, and `destroy_all` on tenant-scoped models raise `Tenantify::TenantMismatchError` unless the relation is already scoped to the current tenant, or you use `Tenantify.without_tenant`.
+## Configuration
 
-## Errors
+```ruby
+# config/initializers/tenantify.rb
+Tenantify.configure do |config|
+  config.tenant_model          = "Organization"  # required
+  config.on_tenant_not_found   = :raise            # :raise, :redirect, :null_tenant
+  config.audit_overrides       = :log              # :log, :raise, :ignore
+end
+```
+
+---
+
+## Comparison with other approaches
+
+| Approach | How it works | rails-tenantify advantage |
+|----------|----------------|---------------------------|
+| **acts_as_tenant** | Row-level FK scope | Modern Rails, jobs, bulk guards, maintained |
+| **apartment** | Schema / DB per tenant | Simpler ops — one DB, one migration path |
+| **acts_as_subtenant** | Nested tenants | Flat, explicit `belongs_to_tenant` |
+| **Custom `default_scope`** | Hand-rolled | Override protection, jobs, tests included |
+
+---
+
+## API reference
+
+| Method / macro | Description |
+|----------------|-------------|
+| `Tenantify.configure` | Global configuration block |
+| `Tenantify.current_tenant` | Current tenant object (thread-local) |
+| `Tenantify.current_tenant=` | Set tenant (respects `audit_overrides`) |
+| `Tenantify.current_tenant_id` | Current tenant id or `nil` |
+| `Tenantify.tenant_scoped?` | Whether default scope is active |
+| `Tenantify.tenant_class` | Constantized `tenant_model` class |
+| `Tenantify.switch_to(tenant) { }` | Temporary tenant switch |
+| `Tenantify.without_tenant { }` | Disable scoping and bulk guards |
+| `include Tenantify::Scoped` | Model concern for row-level scope |
+| `belongs_to_tenant :association` | FK macro + validations + default scope |
+| `include Tenantify::Controller` | Controller concern |
+| `set_tenant_by :subdomain` | Subdomain resolver |
+| `set_tenant_by :header` | Header resolver |
+| `Tenantify::Job` | ActiveJob tenant serialize / restore (auto-included) |
+| `with_tenant(tenant) { }` | Test helper — block switch |
+| `without_tenant { }` | Test helper — disable scope |
+| `Tenantify::TestHelpers.clear_tenant` | Reset thread-local state |
+
+### Errors
 
 | Error | When |
 |-------|------|
 | `Tenantify::TenantNotFoundError` | Resolver cannot find a tenant |
 | `Tenantify::TenantMismatchError` | Unsafe bulk write without tenant scope |
 | `Tenantify::TenantOverrideError` | Unsafe `current_tenant=` when `audit_overrides` is `:raise` |
+| `Tenantify::Error` | Base error (e.g. missing `tenant_model`) |
+
+---
 
 ## Roadmap
 
 | Version | Focus |
 |---------|--------|
+| **0.1.2** (current) | Ruby 3.1 CI — pin `connection_pool` < 3 |
+| **0.1.1** | Fix Rails boot / `Tenantify.configure` entrypoint |
 | **0.1.0** | Core scoping, subdomain/header resolvers, ActiveJob, Sidekiq, test helpers |
 | **0.2.0** | GoodJob, Solid Queue |
 | **0.3.0** | JWT resolver, API improvements |
 | **0.4.0** | Custom domains, Active Storage |
-| **1.0.0** | Stable API, full docs |
+| **0.6.0** | Hotwire / Turbo, GraphQL context |
+| **1.0.0** | Stable API, full documentation |
 
 See [CHANGELOG.md](CHANGELOG.md) for release notes.
 
+---
+
 ## Development
 
 ```bash
@@ -126,10 +340,12 @@ bundle install
 bundle exec rspec
 ```
 
+---
+
 ## Contributing
 
-Bug reports and pull requests are welcome at [github.com/sghani001/rails-tenantify](https://github.com/sghani001/rails-tenantify).
+Bug reports and pull requests are welcome at https://github.com/sghani001/rails-tenantify.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — © Syed M. Ghani

data/lib/rails-tenantify.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Bundler requires this file for the +rails-tenantify+ gem (see Gemfile + gemspec name).
+# Without it, Rails may load Tenantify::Railtie alone and define an incomplete Tenantify module.
+require "tenantify"
+require "tenantify/railtie" if defined?(Rails::Railtie)

data/lib/tenantify/railtie.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Rails may load this file before lib/tenantify.rb; ensure the full API is defined.
+require "tenantify" unless Tenantify.respond_to?(:configure)
+
 require "rails/railtie"
 
 module Tenantify

data/lib/tenantify/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tenantify
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/tenantify.rb

@@ -14,7 +14,6 @@ require_relative "tenantify/controller"
 require_relative "tenantify/job"
 require_relative "tenantify/switcher"
 require_relative "tenantify/test_helpers"
-require_relative "tenantify/railtie" if defined?(Rails)
 
 module Tenantify
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-tenantify
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Syed M. Ghani
@@ -93,7 +93,7 @@ dependencies:
         version: '1.4'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -103,7 +103,7 @@ dependencies:
         version: '1.4'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '2'
 description: |
   Tenantify provides row-level multi-tenancy for Rails 7+ applications: model scoping,
   controller tenant resolution, ActiveJob and Sidekiq context propagation, bulk-write
@@ -117,6 +117,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- lib/rails-tenantify.rb
 - lib/tenantify.rb
 - lib/tenantify/configuration.rb
 - lib/tenantify/controller.rb
@@ -155,7 +156,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Modern multi-tenancy for Rails — row-level tenant scoping with jobs, controllers,