activerecord-multi-tenant 2.2.0 → 2.3.0

data/docs/source/usage-guide.rst

@@ -0,0 +1,59 @@
+.. _usage-guide:
+
+Usage Guide
+===========
+
+This section provides a comprehensive guide on how to use ``activerecord-multi-tenant`` in your Rails application.
+
+Basic Usage
+-----------
+
+To use ``activerecord-multi-tenant``, you need to declare the tenant model in your ActiveRecord models. Here's an example:
+
+.. code-block:: ruby
+
+    class PageView < ActiveRecord::Base
+      multi_tenant :customer
+      belongs_to :site
+
+      # ...
+    end
+
+    class Site < ActiveRecord::Base
+      multi_tenant :customer
+      has_many :page_views
+
+      # ...
+    end
+
+In this example, the ``PageView`` and ``Site`` models are scoped to the ``Customer`` model. This means that each user belongs to a specific customer.
+
+
+Then wrap all code that runs queries/modifications in blocks like this:
+
+.. code-block:: ruby
+
+    customer = Customer.find(session[:current_customer_id])
+    # ...
+    MultiTenant.with(customer) do
+      site = Site.find(params[:site_id])
+      site.update! last_accessed_at: Time.now
+      site.page_views.count
+    end
+
+Alternatively, if you don't want to use a block, you can set the current tenant explicitly:
+
+.. code-block:: ruby
+
+    customer = Customer.find(session[:current_customer_id])
+    MultiTenant.current_tenant = customer
+
+
+Multi-tenancy Concepts and Terminology
+--------------------------------------
+
+Multi-tenancy is a software architecture in which a single instance of software serves multiple tenants. A tenant is a group of users who share a common access with specific privileges to the software instance.
+
+In the context of ``activerecord-multi-tenant``, a tenant is typically represented by a model in your Rails application (e.g., ``Customer``), and other models (e.g., ``PageView``) are scoped to this tenant model.
+
+

data/lib/activerecord-multi-tenant/arel_visitors_depth_first.rb

@@ -1,200 +1,209 @@
+# frozen_string_literal: true
+
 module MultiTenant
   class ArelVisitorsDepthFirst < Arel::Visitors::Visitor
     def initialize(block = nil)
-      @block = block || Proc.new
+      @block = block || proc
       super()
     end
 
     private
 
-      def visit(o, _ = nil)
-        super
-        @block.call o
-      end
+    def visit(obj, _ = nil)
+      super
+      @block.call obj
+    end
 
-      def unary(o)
-        visit o.expr
-      end
-      alias :visit_Arel_Nodes_Else              :unary
-      alias :visit_Arel_Nodes_Group             :unary
-      alias :visit_Arel_Nodes_Cube              :unary
-      alias :visit_Arel_Nodes_RollUp            :unary
-      alias :visit_Arel_Nodes_GroupingSet       :unary
-      alias :visit_Arel_Nodes_GroupingElement   :unary
-      alias :visit_Arel_Nodes_Grouping          :unary
-      alias :visit_Arel_Nodes_Having            :unary
-      alias :visit_Arel_Nodes_Lateral           :unary
-      alias :visit_Arel_Nodes_Limit             :unary
-      alias :visit_Arel_Nodes_Not               :unary
-      alias :visit_Arel_Nodes_Offset            :unary
-      alias :visit_Arel_Nodes_On                :unary
-      alias :visit_Arel_Nodes_Ordering          :unary
-      alias :visit_Arel_Nodes_Ascending         :unary
-      alias :visit_Arel_Nodes_Descending        :unary
-      alias :visit_Arel_Nodes_UnqualifiedColumn :unary
-      alias :visit_Arel_Nodes_OptimizerHints    :unary
-      alias :visit_Arel_Nodes_ValuesList        :unary
-
-      def function(o)
-        visit o.expressions
-        visit o.alias
-        visit o.distinct
-      end
-      alias :visit_Arel_Nodes_Avg    :function
-      alias :visit_Arel_Nodes_Exists :function
-      alias :visit_Arel_Nodes_Max    :function
-      alias :visit_Arel_Nodes_Min    :function
-      alias :visit_Arel_Nodes_Sum    :function
-
-      def visit_Arel_Nodes_NamedFunction(o)
-        visit o.name
-        visit o.expressions
-        visit o.distinct
-        visit o.alias
-      end
+    def unary(obj)
+      visit obj.expr
+    end
+    alias visit_Arel_Nodes_Else              unary
+    alias visit_Arel_Nodes_Group             unary
+    alias visit_Arel_Nodes_Cube              unary
+    alias visit_Arel_Nodes_RollUp            unary
+    alias visit_Arel_Nodes_GroupingSet       unary
+    alias visit_Arel_Nodes_GroupingElement   unary
+    alias visit_Arel_Nodes_Grouping          unary
+    alias visit_Arel_Nodes_Having            unary
+    alias visit_Arel_Nodes_Lateral           unary
+    alias visit_Arel_Nodes_Limit             unary
+    alias visit_Arel_Nodes_Not               unary
+    alias visit_Arel_Nodes_Offset            unary
+    alias visit_Arel_Nodes_On                unary
+    alias visit_Arel_Nodes_Ordering          unary
+    alias visit_Arel_Nodes_Ascending         unary
+    alias visit_Arel_Nodes_Descending        unary
+    alias visit_Arel_Nodes_UnqualifiedColumn unary
+    alias visit_Arel_Nodes_OptimizerHints    unary
+    alias visit_Arel_Nodes_ValuesList        unary
+
+    def function(obj)
+      visit obj.expressions
+      visit obj.alias
+      visit obj.distinct
+    end
+    alias visit_Arel_Nodes_Avg    function
+    alias visit_Arel_Nodes_Exists function
+    alias visit_Arel_Nodes_Max    function
+    alias visit_Arel_Nodes_Min    function
+    alias visit_Arel_Nodes_Sum    function
+
+    # rubocop:disable Naming/MethodName
+
+    def visit_Arel_Nodes_NamedFunction(obj)
+      visit obj.name
+      visit obj.expressions
+      visit obj.distinct
+      visit obj.alias
+    end
 
-      def visit_Arel_Nodes_Count(o)
-        visit o.expressions
-        visit o.alias
-        visit o.distinct
-      end
+    def visit_Arel_Nodes_Count(obj)
+      visit obj.expressions
+      visit obj.alias
+      visit obj.distinct
+    end
 
-      def visit_Arel_Nodes_Case(o)
-        visit o.case
-        visit o.conditions
-        visit o.default
-      end
+    def visit_Arel_Nodes_Case(obj)
+      visit obj.case
+      visit obj.conditions
+      visit obj.default
+    end
 
-      def nary(o)
-        o.children.each { |child| visit child }
-      end
-      alias :visit_Arel_Nodes_And :nary
+    def nary(obj)
+      obj.children.each { |child| visit child }
+    end
+    alias visit_Arel_Nodes_And nary
 
-      def binary(o)
-        visit o.left
-        visit o.right
-      end
-      alias :visit_Arel_Nodes_As                 :binary
-      alias :visit_Arel_Nodes_Assignment         :binary
-      alias :visit_Arel_Nodes_Between            :binary
-      alias :visit_Arel_Nodes_Concat             :binary
-      alias :visit_Arel_Nodes_DeleteStatement    :binary
-      alias :visit_Arel_Nodes_DoesNotMatch       :binary
-      alias :visit_Arel_Nodes_Equality           :binary
-      alias :visit_Arel_Nodes_FullOuterJoin      :binary
-      alias :visit_Arel_Nodes_GreaterThan        :binary
-      alias :visit_Arel_Nodes_GreaterThanOrEqual :binary
-      alias :visit_Arel_Nodes_In                 :binary
-      alias :visit_Arel_Nodes_InfixOperation     :binary
-      alias :visit_Arel_Nodes_JoinSource         :binary
-      alias :visit_Arel_Nodes_InnerJoin          :binary
-      alias :visit_Arel_Nodes_LessThan           :binary
-      alias :visit_Arel_Nodes_LessThanOrEqual    :binary
-      alias :visit_Arel_Nodes_Matches            :binary
-      alias :visit_Arel_Nodes_NotEqual           :binary
-      alias :visit_Arel_Nodes_NotIn              :binary
-      alias :visit_Arel_Nodes_NotRegexp          :binary
-      alias :visit_Arel_Nodes_IsNotDistinctFrom  :binary
-      alias :visit_Arel_Nodes_IsDistinctFrom     :binary
-      alias :visit_Arel_Nodes_Or                 :binary
-      alias :visit_Arel_Nodes_OuterJoin          :binary
-      alias :visit_Arel_Nodes_Regexp             :binary
-      alias :visit_Arel_Nodes_RightOuterJoin     :binary
-      alias :visit_Arel_Nodes_TableAlias         :binary
-      alias :visit_Arel_Nodes_When               :binary
-
-      def visit_Arel_Nodes_StringJoin(o)
-        visit o.left
-      end
+    def binary(obj)
+      visit obj.left
+      visit obj.right
+    end
+    alias visit_Arel_Nodes_As                 binary
+    alias visit_Arel_Nodes_Assignment         binary
+    alias visit_Arel_Nodes_Between            binary
+    alias visit_Arel_Nodes_Concat             binary
+    alias visit_Arel_Nodes_DeleteStatement    binary
+    alias visit_Arel_Nodes_DoesNotMatch       binary
+    alias visit_Arel_Nodes_Equality           binary
+    alias visit_Arel_Nodes_FullOuterJoin      binary
+    alias visit_Arel_Nodes_GreaterThan        binary
+    alias visit_Arel_Nodes_GreaterThanOrEqual binary
+    alias visit_Arel_Nodes_In                 binary
+    alias visit_Arel_Nodes_InfixOperation     binary
+    alias visit_Arel_Nodes_JoinSource         binary
+    alias visit_Arel_Nodes_InnerJoin          binary
+    alias visit_Arel_Nodes_LessThan           binary
+    alias visit_Arel_Nodes_LessThanOrEqual    binary
+    alias visit_Arel_Nodes_Matches            binary
+    alias visit_Arel_Nodes_NotEqual           binary
+    alias visit_Arel_Nodes_NotIn              binary
+    alias visit_Arel_Nodes_NotRegexp          binary
+    alias visit_Arel_Nodes_IsNotDistinctFrom  binary
+    alias visit_Arel_Nodes_IsDistinctFrom     binary
+    alias visit_Arel_Nodes_Or                 binary
+    alias visit_Arel_Nodes_OuterJoin          binary
+    alias visit_Arel_Nodes_Regexp             binary
+    alias visit_Arel_Nodes_RightOuterJoin     binary
+    alias visit_Arel_Nodes_TableAlias         binary
+    alias visit_Arel_Nodes_When               binary
+
+    def visit_Arel_Nodes_StringJoin(obj)
+      visit obj.left
+    end
 
-      def visit_Arel_Attribute(o)
-        visit o.relation
-        visit o.name
-      end
-      alias :visit_Arel_Attributes_Integer :visit_Arel_Attribute
-      alias :visit_Arel_Attributes_Float :visit_Arel_Attribute
-      alias :visit_Arel_Attributes_String :visit_Arel_Attribute
-      alias :visit_Arel_Attributes_Time :visit_Arel_Attribute
-      alias :visit_Arel_Attributes_Boolean :visit_Arel_Attribute
-      alias :visit_Arel_Attributes_Attribute :visit_Arel_Attribute
-      alias :visit_Arel_Attributes_Decimal :visit_Arel_Attribute
-
-      def visit_Arel_Table(o)
-        visit o.name
-      end
+    def visit_Arel_Attribute(obj)
+      visit obj.relation
+      visit obj.name
+    end
+    alias visit_Arel_Attributes_Integer visit_Arel_Attribute
+    alias visit_Arel_Attributes_Float visit_Arel_Attribute
+    alias visit_Arel_Attributes_String visit_Arel_Attribute
+    alias visit_Arel_Attributes_Time visit_Arel_Attribute
+    alias visit_Arel_Attributes_Boolean visit_Arel_Attribute
+    alias visit_Arel_Attributes_Attribute visit_Arel_Attribute
+    alias visit_Arel_Attributes_Decimal visit_Arel_Attribute
+
+    def visit_Arel_Table(obj)
+      visit obj.name
+    end
 
-      def terminal(o)
-      end
-      alias :visit_ActiveSupport_Multibyte_Chars :terminal
-      alias :visit_ActiveSupport_StringInquirer  :terminal
-      alias :visit_Arel_Nodes_Lock               :terminal
-      alias :visit_Arel_Nodes_Node               :terminal
-      alias :visit_Arel_Nodes_SqlLiteral         :terminal
-      alias :visit_Arel_Nodes_BindParam          :terminal
-      alias :visit_Arel_Nodes_Window             :terminal
-      alias :visit_Arel_Nodes_True               :terminal
-      alias :visit_Arel_Nodes_False              :terminal
-      alias :visit_BigDecimal                    :terminal
-      alias :visit_Class                         :terminal
-      alias :visit_Date                          :terminal
-      alias :visit_DateTime                      :terminal
-      alias :visit_FalseClass                    :terminal
-      alias :visit_Float                         :terminal
-      alias :visit_Integer                       :terminal
-      alias :visit_NilClass                      :terminal
-      alias :visit_String                        :terminal
-      alias :visit_Symbol                        :terminal
-      alias :visit_Time                          :terminal
-      alias :visit_TrueClass                     :terminal
-
-      def visit_Arel_Nodes_InsertStatement(o)
-        visit o.relation
-        visit o.columns
-        visit o.values
-      end
+    def terminal(obj); end
+    alias visit_ActiveSupport_Multibyte_Chars terminal
+    alias visit_ActiveSupport_StringInquirer  terminal
+    alias visit_Arel_Nodes_Lock               terminal
+    alias visit_Arel_Nodes_Node               terminal
+    alias visit_Arel_Nodes_SqlLiteral         terminal
+    alias visit_Arel_Nodes_BindParam          terminal
+    alias visit_Arel_Nodes_Window             terminal
+    alias visit_Arel_Nodes_True               terminal
+    alias visit_Arel_Nodes_False              terminal
+    alias visit_BigDecimal                    terminal
+    alias visit_Class                         terminal
+    alias visit_Date                          terminal
+    alias visit_DateTime                      terminal
+    alias visit_FalseClass                    terminal
+    alias visit_Float                         terminal
+    alias visit_Integer                       terminal
+    alias visit_NilClass                      terminal
+    alias visit_String                        terminal
+    alias visit_Symbol                        terminal
+    alias visit_Time                          terminal
+    alias visit_TrueClass                     terminal
+
+    def visit_Arel_Nodes_InsertStatement(obj)
+      visit obj.relation
+      visit obj.columns
+      visit obj.values
+    end
 
-      def visit_Arel_Nodes_SelectCore(o)
-        visit o.projections
-        visit o.source
-        visit o.wheres
-        visit o.groups
-        visit o.windows
-        visit o.havings
-      end
+    def visit_Arel_Nodes_SelectCore(obj)
+      visit obj.projections
+      visit obj.source
+      visit obj.wheres
+      visit obj.groups
+      visit obj.windows
+      visit obj.havings
+    end
 
-      def visit_Arel_Nodes_SelectStatement(o)
-        visit o.cores
-        visit o.orders
-        visit o.limit
-        visit o.lock
-        visit o.offset
-      end
+    def visit_Arel_Nodes_SelectStatement(obj)
+      visit obj.cores
+      visit obj.orders
+      visit obj.limit
+      visit obj.lock
+      visit obj.offset
+    end
 
-      def visit_Arel_Nodes_UpdateStatement(o)
-        visit o.relation
-        visit o.values
-        visit o.wheres
-        visit o.orders
-        visit o.limit
-      end
+    def visit_Arel_Nodes_UpdateStatement(obj)
+      visit obj.relation
+      visit obj.values
+      visit obj.wheres
+      visit obj.orders
+      visit obj.limit
+    end
 
-      def visit_Arel_Nodes_Comment(o)
-        visit o.values
-      end
+    def visit_Arel_Nodes_Comment(obj)
+      visit obj.values
+    end
 
-      def visit_Array(o)
-        o.each { |i| visit i }
-      end
-      alias :visit_Set :visit_Array
+    def visit_Array(obj)
+      obj.each { |i| visit i }
+    end
+    alias visit_Set visit_Array
 
-      def visit_Hash(o)
-        o.each { |k, v| visit(k); visit(v) }
+    def visit_Hash(obj)
+      obj.each do |k, v|
+        visit(k)
+        visit(v)
       end
+    end
 
-      DISPATCH = dispatch_cache
+    DISPATCH = dispatch_cache
 
-      def get_dispatch_cache
-        DISPATCH
-      end
+    # rubocop:disable Naming/AccessorMethodName
+    def get_dispatch_cache
+      DISPATCH
+    end
+    # rubocop:enable Naming/AccessorMethodName
+    # rubocop:enable Naming/MethodName
   end
 end

data/lib/activerecord-multi-tenant/controller_extensions.rb

@@ -1,16 +1,22 @@
+# frozen_string_literal: true
+
+# Extension to the controller to allow setting the current tenant
+# set_current_tenant and current_tenant methods are introduced
+# to set and get the current tenant in the controllers that uses
+# the MultiTenant module.
 module MultiTenant
   module ControllerExtensions
     def set_current_tenant_through_filter
-      self.class_eval do
-        if respond_to?(:helper_method)
-          helper_method :current_tenant
-        end
+      class_eval do
+        helper_method :current_tenant if respond_to?(:helper_method)
 
         private
 
+        # rubocop:disable Naming/AccessorMethodName
         def set_current_tenant(current_tenant_object)
           MultiTenant.current_tenant = current_tenant_object
         end
+        # rubocop:enable Naming/AccessorMethodName
 
         def current_tenant
           MultiTenant.current_tenant
@@ -20,6 +26,11 @@ module MultiTenant
   end
 end
 
+# This block is executed when the file is loaded and
+# makes the base class; ActionController::Base to
+# extend the ControllerExtensions module.
+# This will add the set_current_tenant and current_tenant
+# in all the controllers that inherit from ActionController::Base
 ActiveSupport.on_load(:action_controller) do |base|
   base.extend MultiTenant::ControllerExtensions
 end

data/lib/activerecord-multi-tenant/copy_from_client.rb

@@ -1,4 +1,7 @@
 module MultiTenant
+  # Designed to be mixed into an ActiveRecord model to provide
+  # a copy_from_client method that allows for efficient bulk insertion of
+  # data into a PostgreSQL database using the COPY command
   class CopyFromClientHelper
     attr_reader :count
 
@@ -28,6 +31,7 @@ module MultiTenant
   end
 end
 
+# Add copy_from_client to ActiveRecord::Base
 ActiveSupport.on_load(:active_record) do |base|
   base.extend(MultiTenant::CopyFromClient)
 end

data/lib/activerecord-multi-tenant/fast_truncate.rb

@@ -1,5 +1,6 @@
 # Truncates only the tables that have been modified, according to sequence
 # values
+# Faster alternative to DatabaseCleaner.clean_with(:truncation, pre_count: true)
 module MultiTenant
   module FastTruncate
     def self.run(exclude: ['schema_migrations'])
@@ -13,7 +14,8 @@ module MultiTenant
         needs_truncate boolean;
       BEGIN
         FOR t IN SELECT schemaname, tablename FROM pg_tables WHERE schemaname = 'public' AND tablename NOT IN (%s) LOOP
-          EXECUTE 'SELECT EXISTS (SELECT * from pg_class c WHERE c.relkind = ''S'' AND c.relname=''' || t.tablename || '_id_seq'')' into seq_exists;
+          EXECUTE 'SELECT EXISTS (SELECT * from pg_class c WHERE c.relkind = ''S''
+           AND c.relname=''' || t.tablename || '_id_seq'')' into seq_exists;
           IF seq_exists THEN
             EXECUTE 'SELECT is_called FROM ' || t.tablename || '_id_seq' INTO needs_truncate;
           ELSE
@@ -28,7 +30,7 @@ module MultiTenant
         IF array_length(tables, 1) > 0 THEN
           EXECUTE 'TRUNCATE TABLE ' || array_to_string(tables, ', ') || ' RESTART IDENTITY CASCADE';
         END IF;
-      END$$;), exclude.map { |t| "'" + t + "'" }.join('\n'))
+      END$$;), exclude.map { |t| "'#{t}'" }.join('\n'))
     end
   end
 end

data/lib/activerecord-multi-tenant/habtm.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# This module extension is a monkey patch to the ActiveRecord::Associations::ClassMethods module.
+# It overrides the has_and_belongs_to_many method to add the tenant_id to the join table if the
+# tenant_enabled option is set to true.
+
+module ActiveRecord
+  module Associations
+    module ClassMethods
+      # rubocop:disable Naming/PredicateName
+      def has_and_belongs_to_many_with_tenant(name, options = {}, &extension)
+        # rubocop:enable Naming/PredicateName
+        has_and_belongs_to_many_without_tenant(name, **options, &extension)
+
+        middle_reflection = _reflections[name.to_s].through_reflection
+        join_model = middle_reflection.klass
+
+        # get tenant_enabled from options and if it is not set, set it to false
+        tenant_enabled = options[:tenant_enabled] || false
+
+        return unless tenant_enabled
+
+        tenant_class_name = options[:tenant_class_name]
+        tenant_column = options[:tenant_column]
+
+        match = tenant_column.match(/(\w+)_id/)
+        tenant_field_name = match ? match[1] : 'tenant'
+
+        join_model.class_eval do
+          belongs_to tenant_field_name.to_sym, class_name: tenant_class_name
+          before_create :tenant_set
+
+          private
+
+          # This method sets the tenant_id on the join table and executes before creation of the join table record.
+          define_method :tenant_set do
+            if tenant_enabled
+              raise MultiTenant::MissingTenantError, 'Tenant Id is not set' unless MultiTenant.current_tenant_id
+
+              send("#{tenant_column}=", MultiTenant.current_tenant_id)
+            end
+          end
+        end
+      end
+
+      alias has_and_belongs_to_many_without_tenant has_and_belongs_to_many
+      alias has_and_belongs_to_many has_and_belongs_to_many_with_tenant
+    end
+  end
+end

data/lib/activerecord-multi-tenant/migrations.rb

@@ -46,7 +46,8 @@ module MultiTenant
         execute "SELECT citus_run_on_all_workers($$#{sql}$$)" # initial citus_tools.sql with different names
       when nil
         # Do nothing, this is regular Postgres
-      else # 6.1 and newer
+      else
+        # 6.1 and newer
         execute "SELECT run_command_on_workers($$#{sql}$$)"
       end
     end
@@ -69,6 +70,7 @@ module ActiveRecord
   module ConnectionAdapters # :nodoc:
     module SchemaStatements
       alias orig_create_table create_table
+
       def create_table(table_name, options = {}, &block)
         ret = orig_create_table(table_name, **options.except(:partition_key), &block)
         if options[:id] != false && options[:partition_key] && options[:partition_key].to_s != 'id'
@@ -86,18 +88,25 @@ module ActiveRecord
     private
 
     alias initialize_without_citus initialize
+
     def initialize(connection, options = {})
       initialize_without_citus(connection, options)
 
-      citus_version = begin
-        ActiveRecord::Migration.citus_version
-      rescue StandardError
-        # Handle the case where this gem is used with MySQL https://github.com/citusdata/activerecord-multi-tenant/issues/166
-        nil
-      end
+      citus_version =
+        begin
+          ActiveRecord::Migration.citus_version
+        rescue StandardError
+          # Handle the case where this gem is used with MySQL https://github.com/citusdata/activerecord-multi-tenant/issues/166
+          nil
+        end
       @distribution_columns =
         if citus_version.present?
-          @connection.execute('SELECT logicalrelid::regclass AS table_name, column_to_column_name(logicalrelid, partkey) AS dist_col_name FROM pg_dist_partition').to_h do |v|
+          query_to_execute = <<-SQL.strip
+            SELECT logicalrelid::regclass AS table_name,
+                   column_to_column_name(logicalrelid, partkey) AS dist_col_name
+            FROM pg_dist_partition
+          SQL
+          @connection.execute(query_to_execute).to_h do |v|
             [v['table_name'], v['dist_col_name']]
           end
         else
@@ -107,6 +116,7 @@ module ActiveRecord
 
     # Support for create_distributed_table & create_reference_table
     alias table_without_citus table
+
     def table(table, stream)
       table_without_citus(table, stream)
       table_name = remove_prefix_and_suffix(table)