Tenant.while_tenanted and .current_tenant

current_tenant wraps current_shard, and we use a sentinel value to
indicate when the class is untenanted.

Also restructured the test scenarios a bit, dropped the scenario from
the migrations paths, and expanded scenarios to cover a primary
database named both "primary" and something custom.

Author: flavorjones

GUIDE.md

@@ -59,13 +59,15 @@ TODO:
   - [ ] make sure the logs include the tenant name (via `#new_connection`)
 
 - Active Record class methods
-  - [ ] `.tenanted`
+  - [x] `.tenanted`
     - [x] mixin `Tenant`
     - [x] should error if self is not an abstract base class
-  - [x] `tenant_config_name` and `.tenanted?`
+    - [x] `Tenant.with_tenant` and `.current_tenant`
+    - [x] use a sentinel value to avoid needing a protoshard
   - [ ] `.tenanted_with`
     - [ ] mixin `Subtenant`
     - [ ] should error if self is not an abstract base class or if target is not tenanted abstract base class
+  - [x] `tenant_config_name` and `.tenanted?`
   - [ ] `.tenanted_class` nil or the abstract base class
   - [ ] all the creation and schema migration complications (we have existing tests for this)
     - think about race conditions here, maybe use a file lock to figure it out

lib/active_record/tenanted.rb

@@ -8,7 +8,11 @@
 
 module ActiveRecord
   module Tenanted
+    # Base exception class for the library.
     class Error < StandardError; end
+
+    # Raised when database access is attempted without a current tenant having been set.
+    class NoTenantError < Error; end
   end
 end
 

lib/active_record/tenanted/tenant.rb

@@ -4,6 +4,34 @@ module ActiveRecord
   module Tenanted
     module Tenant
       extend ActiveSupport::Concern
+
+      # This is a sentinel value used to indicate that the class is not currently tenanted.
+      #
+      # It's the default value returned by `current_shard` when the class is not tenanted. The
+      # `current_tenant` method's job is to recognizes that sentinel value and return `nil`, because
+      # Active Record itself does not recognize `nil` as a valid shard value.
+      UNTENANTED_SENTINEL = Object.new # :nodoc:
+
+      included do
+        connecting_to(shard: UNTENANTED_SENTINEL, role: ActiveRecord.writing_role)
+      end
+
+      class_methods do
+        def current_tenant
+          shard = current_shard
+          shard != UNTENANTED_SENTINEL ? shard.to_s : nil
+        end
+
+        def while_tenanted(tenant_name, &block)
+          connected_to(shard: tenant_name, role: ActiveRecord.writing_role) do
+            prohibit_shard_swapping(true, &block)
+          end
+        end
+
+        def connection_pool
+          raise NoTenantError unless current_tenant
+        end
+      end
     end
   end
 end

test/scenarios/vanilla/database.yml

@@ -1,10 +1,13 @@
+#
+#  this test config has a primary database named "primary"
+#
 test:
-  tenanted:
+  primary:
     tenanted: true
     adapter: "sqlite3"
-    database: "%{storage}/test/tenanted/%%{tenant}/main.sqlite3"
-    migrations_paths: "%{__dir__}/%{scenario}/tenanted_migrations"
+    database: "%{storage}/test/primary/%%{tenant}/main.sqlite3"
+    migrations_paths: "%{__dir__}/primary_migrations"
   shared:
     adapter: "sqlite3"
-    database: "%{storage}/test/shared/%%{tenant}/main.sqlite3"
-    migrations_paths: "%{__dir__}/%{scenario}/shared_migrations"
+    database: "%{storage}/test/shared.sqlite3"
+    migrations_paths: "%{__dir__}/shared_migrations"

test/scenarios/vanilla/primary_migrations/20250203191115_create_users.rb

@@ -0,0 +1,9 @@
+class CreateUsers < ActiveRecord::Migration[8.1]
+  def change
+    create_table :users do |t|
+      t.string :email
+
+      t.timestamps
+    end
+  end
+end

test/scenarios/vanilla/shared_migrations/20250203191207_create_announcements.rb

@@ -0,0 +1,9 @@
+class CreateAnnouncements < ActiveRecord::Migration[8.1]
+  def change
+    create_table :announcements do |t|
+      t.string :message
+
+      t.timestamps
+    end
+  end
+end

test/scenarios/vanilla/tenanted_secondary.rb

@@ -3,7 +3,7 @@
 class TenantedApplicationRecord < ActiveRecord::Base
   self.abstract_class = true
 
-  tenanted "tenanted"
+  tenanted
 end
 
 class User < TenantedApplicationRecord

test/scenarios/vanilla_named_primary/database.yml

@@ -0,0 +1,13 @@
+#
+#  this test config has a primary database named "tenanted"
+#
+test:
+  tenanted:
+    tenanted: true
+    adapter: "sqlite3"
+    database: "%{storage}/test/tenanted/%%{tenant}/main.sqlite3"
+    migrations_paths: "%{__dir__}/tenanted_migrations"
+  shared:
+    adapter: "sqlite3"
+    database: "%{storage}/test/shared.sqlite3"
+    migrations_paths: "%{__dir__}/shared_migrations"

test/scenarios/vanilla_named_primary/shared_migrations/20250203191207_create_announcements.rb

@@ -0,0 +1,9 @@
+class CreateAnnouncements < ActiveRecord::Migration[8.1]
+  def change
+    create_table :announcements do |t|
+      t.string :message
+
+      t.timestamps
+    end
+  end
+end

test/scenarios/vanilla_named_primary/tenanted_migrations/20250203191115_create_users.rb

@@ -0,0 +1,9 @@
+class CreateUsers < ActiveRecord::Migration[8.1]
+  def change
+    create_table :users do |t|
+      t.string :email
+
+      t.timestamps
+    end
+  end
+end