low_card_tables 1.0.0

data/lib/low_card_tables/has_low_card_table/low_card_associations_manager.rb

@@ -0,0 +1,143 @@
+require 'low_card_tables/has_low_card_table/low_card_association'
+require 'low_card_tables/errors'
+
+module LowCardTables
+  module HasLowCardTable
+    # The LowCardAssociationsManager is a relatively simple object; it manages the LowCardAssociation objects for a
+    # given model class that refers to at least one low-card table. Conceptually, it does little more than maintain
+    # an Array of such associations.
+    #
+    # (Note that storing this data as an Array is important: part of the contract of the low-card system is that
+    # later calls to +has_low_card_table+ supersede earlier calls, so order is key. Yes, Ruby hashes are ordered in
+    # recent Ruby versions...but we support 1.8.7, too.)
+    class LowCardAssociationsManager
+      # Returns an Array of all LowCardAssociation objects for the given +model_class+.
+      attr_reader :associations
+
+      # Creates a new instance. You should only ever create one instance per model class.
+      def initialize(model_class)
+        if (! superclasses(model_class).include?(::ActiveRecord::Base))
+          raise ArgumentError, "You must supply an ActiveRecord model, not: #{model_class}"
+        elsif model_class.is_low_card_table?
+          raise ArgumentError, "A low-card table can't itself have low-card associations: #{model_class}"
+        end
+
+        @model_class = model_class
+        @associations = [ ]
+        @collapsing_update_scheme = :default
+
+        install_methods!
+      end
+
+      # Called when +has_low_card_table+ is declared within the model class; this does all the actual work of
+      # setting up the association. This removes any previous associations with the same name; again, we have a
+      # 'last caller wins' policy.
+      def has_low_card_table(association_name, options = { })
+        unless association_name.kind_of?(Symbol) || (association_name.kind_of?(String) && association_name.strip.length > 0)
+          raise ArgumentError, "You must supply an association name, not: #{association_name.inspect}"
+        end
+
+        association_name = association_name.to_s.strip.downcase
+        @associations.delete_if { |a| a.association_name.to_s.strip.downcase == association_name }
+
+        @associations << LowCardTables::HasLowCardTable::LowCardAssociation.new(@model_class, association_name, options)
+
+        @model_class._low_card_dynamic_method_manager.sync_methods!
+      end
+
+      # Called when someone has called ::ActiveRecord::Base#reset_column_information on the low-card model in question.
+      # This simply tells the LowCardDynamicMethodManager to sync the methods on this model class, thus updating the
+      # set of delegated methods to match the new columns.
+      def low_card_column_information_reset!(low_card_model)
+        @model_class._low_card_dynamic_method_manager.sync_methods!
+      end
+
+      # Retrieves the low-card association with the given name. Raises LowCardTables::Errors::LowCardAssociationNotFoundError
+      # if not found.
+      def _low_card_association(name)
+        maybe_low_card_association(name) || (raise LowCardTables::Errors::LowCardAssociationNotFoundError, "There is no low-card association named '#{name}' for #{@model_class.name}; there are associations named: #{@associations.map(&:association_name).sort.join(", ")}.")
+      end
+
+      # Just like _low_card_association, but returns nil when an association is not found, rather than raising an error.
+      def maybe_low_card_association(name)
+        @associations.detect { |a| a.association_name.to_s.strip.downcase == name.to_s.strip.downcase }
+      end
+
+      # Updates all foreign keys that the given model_instance has to their correct values, given the set of attributes
+      # that are associated with that model instance.
+      def low_card_update_foreign_keys!(model_instance)
+        ensure_correct_class!(model_instance)
+
+        @associations.each do |association|
+          association.update_foreign_key!(model_instance)
+        end
+      end
+
+      DEFAULT_COLLAPSING_UPDATE_VALUE = 10_000
+
+      # Gets, or sets, the current scheme for updating rows in this table when a low-card table has a column removed and
+      # thus needs to have rows collapsed. Passing +nil+ or no arguments retrieves the current scheme; passing anything
+      # else sets it. You can set this to:
+      #
+      # [:default] Rows will be updated in chunks of +DEFAULT_COLLAPSING_UPDATE_VALUE+ rows.
+      # [:none] Nothing will be done; you are entirely on your own, and will have dangling foreign keys.
+      # [a positive integer] Rows will be updated in chunks of this many rows at once.
+      # [something that responds to :call] This object will have #call invoked on it when rows need to be updated; it
+      #                                    will be passed the map of 'winners' to 'losers', and is responsible for
+      #                                    updating rows any way you want.
+      def low_card_value_collapsing_update_scheme(new_scheme = nil)
+        if (! new_scheme)
+          @collapsing_update_scheme
+        elsif new_scheme == :default || new_scheme == :none
+          @collapsing_update_scheme = new_scheme
+        elsif new_scheme.kind_of?(Integer)
+          raise ArgumentError, "You must specify an integer >= 1, not #{new_scheme.inspect}" unless new_scheme >= 1
+          @collapsing_update_scheme = new_scheme
+        elsif new_scheme.respond_to?(:call)
+          @collapsing_update_scheme = new_scheme
+        else
+          raise ArgumentError, "Invalid collapsing update scheme: #{new_scheme.inspect}"
+        end
+      end
+
+      # Called when a low-card model has just collapsed rows, presumably because it has had a column removed. This is
+      # responsible for updating each foreign-key column, using the proper low_card_value_collapsing_update_scheme.
+      def _low_card_update_collapsed_rows(low_card_model, collapse_map)
+        update_scheme = @collapsing_update_scheme
+        update_scheme = DEFAULT_COLLAPSING_UPDATE_VALUE if update_scheme == :default
+
+        @associations.each do |association|
+          if association.low_card_class == low_card_model
+            association.update_collapsed_rows(collapse_map, update_scheme)
+          end
+        end
+      end
+
+      private
+      # Makes sure that +model_instance+ is an instance of the model class this LowCardAssociationsManager is for.
+      def ensure_correct_class!(model_instance)
+        unless model_instance.kind_of?(@model_class)
+          raise ArgumentError, %{Somehow, you passed #{model_instance}, an instance of #{model_instance.class}, to the LowCardAssociationsManager for #{@model_class}.}
+        end
+      end
+
+      # Installs any methods we need on the model class -- right now, this is just our +before_save+ hook.
+      def install_methods!
+        @model_class.send(:before_save, :low_card_update_foreign_keys!)
+      end
+
+      # Fetches the entire superclass chain of a Class, up to, but not including, Object.
+      def superclasses(c)
+        out = [ ]
+
+        c = c.superclass
+        while c != Object
+          out << c
+          c = c.superclass
+        end
+
+        out
+      end
+    end
+  end
+end

data/lib/low_card_tables/has_low_card_table/low_card_dynamic_method_manager.rb

@@ -0,0 +1,224 @@
+module LowCardTables
+  module HasLowCardTable
+    # This object is responsible for maintaining the set of methods that get automatically delegated when you declare
+    # +has_low_card_table+ on an ::ActiveRecord model -- it both maintains the set of methods defined on the
+    # _low_card_dynamic_methods_module for that class, and directs the calls in the right place at runtime.
+    #
+    # Secondarily, it also is responsible for transforming query specifications -- #scope_from_query takes the set of
+    # constraints you passed, as a Hash, to ::ActiveRecord::Relation#where, and transforms them using low-card
+    # information. So:
+    #
+    #    { :deleted => true, :deceased => false }
+    #
+    # might become
+    #
+    #    { :user_status_id => [ 1, 3, 9, 17 ] }
+    #
+    # While it might seem odd for that functionality to live in this class, it actually makes sense; this is the
+    # class that knows what method names in the low-card class those keys map to, after all.
+    class LowCardDynamicMethodManager
+      def initialize(model_class)
+        @model_class = model_class
+        @method_delegation_map = { }
+      end
+
+      # Given an instance of the model class we're maintaining methods for, the name of a method to invoke, and
+      # arguments passed to that method, runs the correct method. This is therefore a dispatcher -- rather than attempt
+      # to define the methods on the _low_card_dynamic_methods_module at all times to directly call the right low-card
+      # object, we simply have them all call through here, instead, and do the dispatch at runtime. This simplifies
+      # the nature of the dynamic methods considerably.
+      def run_low_card_method(object, method_name, args)
+        ensure_correct_class!(object)
+
+        method_data = @method_delegation_map[method_name.to_s]
+        unless method_data
+          raise NameError, "Whoa -- we're trying to call a delegated low-card method #{method_name.inspect} on #{object}, of class #{object.class}, but somehow the LowCardDynamicMethodManager has no knowledge of that method?!? We know about: #{@method_delegation_map.keys.sort.inspect}"
+        end
+
+        (association, association_method_name) = method_data
+
+        if association_method_name == :_low_card_object
+          # e.g., my_user.status
+          object._low_card_objects_manager.object_for(association)
+        elsif association_method_name == :_low_card_foreign_key
+          # e.g., my_user.user_status_id
+          object._low_card_objects_manager.foreign_key_for(association)
+        elsif association_method_name == :_low_card_foreign_key=
+          # e.g., my_user.user_status_id =
+          object._low_card_objects_manager.set_foreign_key_for(association, *args)
+        else
+          # e.g., my_user.deleted =
+          low_card_object = object.send(association.association_name)
+          low_card_object.send(association_method_name, *args)
+        end
+      end
+
+      # Given a base ::ActiveRecord::Relation scope (which can of course just be a model class itself), and a set of
+      # query constraints as passed into ::ActiveRecord::Relation#where (which must be a Hash -- for the other forms
+      # of #where, our override of ::ActiveRecord::Relation#where doesn't call this method but just passes through to
+      # the underlying method), returns a new scope that is the result of applying those constraints correctly to
+      # the +base_scope+.
+      #
+      # The constraints in the query_hash need not all be, or even any be, constraints on a low-card table; any non-
+      # low-card constraints are simply passed through verbatim. But constraints on a low-card table -- whether they're
+      # implicit, like
+      #
+      #    User.where(:deleted => false)
+      #
+      # or explicit, like
+      #
+      #    User.where(:status => { :deleted => false })
+      #
+      # ...are transformed into explicit references to the low-card foreign-key column:
+      #
+      #    User.where(:user_status_id => [ 1, 3, 4, 7, 8, 10 ])
+      def scope_from_query(base_scope, query_hash)
+        non_low_card_constraints = { }
+        low_card_association_to_constraint_map = { }
+
+        # We iterate through the query hash, building up two hashes:
+        #
+        # * non_low_card_constraints is the set of all constraints that have nothing to do with a low-card table;
+        # * low_card_association_to_constraint_map maps low-card association names to a Hash of the constraints applied
+        #   to that association; the constraints in the Hash use key names that are the actual low-card column names
+        #   (i.e., we translate them from whatever delegated method names were present in the referring class)
+        query_hash.each do |query_key, query_value|
+          low_card_delegation = @method_delegation_map[query_key.to_s]
+
+          # Does this constraint even mention a low-card column or association name?
+          if low_card_delegation
+            (association, method) = low_card_delegation
+
+            # e.g., User.where(:status => { ... })
+            if method == :_low_card_object
+              if (! query_value.kind_of?(Hash))
+                raise ArgumentError, %{You are trying to constrain on #{@model_class.name}.#{query_key}, which is a low-card association,
+but the value you passed, #{query_value.inspect}, is not a Hash. Either pass a Hash,
+or constrain on #{association.foreign_key_column_name} explicitly, and find IDs
+yourself, using #{association.low_card_class.name}#ids_matching.}
+              end
+
+              low_card_association_to_constraint_map[association] ||= { }
+              low_card_association_to_constraint_map[association].merge!(query_value)
+            # e.g., User.where(:user_status_id => ...)
+            elsif method == :_low_card_foreign_key
+              non_low_card_constraints[query_key] = query_value
+            # e.g., User.where(:deleted => false)
+            else
+              low_card_association_to_constraint_map[association] ||= { }
+              low_card_association_to_constraint_map[association][method] = query_value
+            end
+          else
+            # e.g., User.where(:name => ...)
+            non_low_card_constraints[query_key] = query_value
+          end
+        end
+
+        out = base_scope
+        # See the comment in LowCardTables::ActiveRecord::Relation -- this is so that when we call #where, below,
+        # we don't end up creating infinite mutual recursion. +_low_card_direct+ is our 'escape hatch'.
+        out = base_scope.where(non_low_card_constraints.merge(:_low_card_direct => true)) if non_low_card_constraints.size > 0
+
+        # This is gross. In ActiveRecord v3, doing something like this:
+        #
+        #    Model.where(:x => [ 1, 2, 3 ]).where(:x => [ 3, 4, 5 ])
+        #
+        # ...results in "... WHERE x IN (3, 4, 5)" -- i.e., it's last-clause wins, and the first one is totally
+        # ignored. While this sucks in general (in my opinion), it's genuinely a problem for our system; we need to
+        # be able to say Model.where(:deleted => false).where(:deceased => false) and only get back non-deleted, alive
+        # users -- and, underneath, both those queries transform to conditions on :user_status_id.
+        #
+        # Our workaround is to instead use text-based queries for these conditions, because:
+        #
+        #    Model.where("x IN :ids", :ids => [ 1, 2, 3 ]).where("x IN :ids", :ids => [ 3, 4, 5 ])
+        #
+        # ...results in "... WHERE x IN (1, 2, 3) AND x IN (3, 4, 5)", which gives us the right value. (ActiveRecord
+        # doesn't ever parse SQL you hand to it, so it has no way of knowing these are conditions on the same column --
+        # so it keeps both clauses.)
+        #
+        # ActiveRecord 4 does the right thing here (IMHO) and behaves identically whether you pass in a Hash or a text
+        # clause. However, our hack works fine with both versions, so we'll keep it for now.
+        low_card_association_to_constraint_map.each do |association, constraints|
+          ids = association.low_card_class.low_card_ids_matching(constraints)
+          out = out.where("#{association.foreign_key_column_name} IN (:ids)", :ids => ids)
+        end
+
+
+        out
+      end
+
+      # This method is responsible for doing two things:
+      #
+      # * Most importantly, it sets up @method_delegation_map. This maps the name of every dynamic method that can be
+      #   invoked on an instance of the model class to the low-card method that it should delegate to. (It calls
+      #   LowCardTables::HasLowCardTable::LowCardAssociation#class_method_name_to_low_card_method_name_map to figure
+      #   out what methods should be delegated for each association.) There are a few 'special' method names:
+      #   +:_low_card_object+ means 'return the associated low-card object itself' (e.g., my_user.status);
+      #   +:_low_card_foreign_key+ means 'return the associated low-card foreign key' (e.g., my_user.user_status_id);
+      #   +:_low_card_foreign_key=+ means 'set the associated low-card foreign key'.
+      # * Secondly, it makes sure that, for each of these methods, the _low_card_dynamic_methods_module has installed
+      #   a method that delegates to #run_low_card_method on this object -- and that no other methods are installed
+      #   on that module.
+      #
+      # This method implements the 'last association wins' policy, by simply going through the asssociations in
+      # order of definition and letting them overwrite previous associations' method names, if they collide.
+      #
+      # Rather than trying to dynamically add and remove methods as associations are added, columns are removed, etc.,
+      # it is _far_ simpler to do what we do here: simply rebuild the map from scratch on each call -- and then apply
+      # the differences to the _low_card_dynamic_methods_module.
+      def sync_methods!
+        currently_delegated_methods = @method_delegation_map.keys
+
+        @method_delegation_map = { }
+
+        associations.each do |association|
+          @method_delegation_map[association.association_name.to_s] = [ association, :_low_card_object ]
+          @method_delegation_map[association.foreign_key_column_name.to_s] = [ association, :_low_card_foreign_key ]
+          @method_delegation_map[association.foreign_key_column_name.to_s + "="] = [ association, :_low_card_foreign_key= ]
+
+          association.class_method_name_to_low_card_method_name_map.each do |desired_name, association_method_name|
+            desired_name = desired_name.to_s
+            @method_delegation_map[desired_name] = [ association, association_method_name ]
+          end
+        end
+
+        remove_delegated_methods!(currently_delegated_methods - @method_delegation_map.keys)
+        add_delegated_methods!(@method_delegation_map.keys - currently_delegated_methods)
+      end
+
+      private
+      # Returns all associations that should be used for this object.
+      def associations
+        @model_class._low_card_associations_manager.associations
+      end
+
+      # Makes sure the given object is an instance of the class we're handling dynamic methods for.
+      def ensure_correct_class!(object)
+        unless object.kind_of?(@model_class)
+          raise ArgumentError, "You passed #{object.inspect}, an instance of #{object.class.name}, to the LowCardDynamicMethodManager for #{@model_class}."
+        end
+      end
+
+      # Removes all methods with any of the specified names from the _low_card_dynamic_methods_module.
+      def remove_delegated_methods!(method_names)
+        mod = @model_class._low_card_dynamic_methods_module
+
+        method_names.each do |method_name|
+          mod.module_eval("remove_method :#{method_name}")
+        end
+      end
+
+      # Adds delegated methods for all the given names to the _low_card_dynamic_methods_module.
+      def add_delegated_methods!(method_names)
+        mod = @model_class._low_card_dynamic_methods_module
+
+        method_names.each do |delegated_method|
+          mod.module_eval(%{
+  def #{delegated_method}(*args)
+    self.class._low_card_dynamic_method_manager.run_low_card_method(self, :#{delegated_method}, args)
+  end})
+        end
+      end
+    end
+  end
+end

data/lib/low_card_tables/has_low_card_table/low_card_objects_manager.rb

@@ -0,0 +1,80 @@
+module LowCardTables
+  module HasLowCardTable
+    # Unlike the LowCardAssociationsManager, the LowCardObjectsManager belongs to a particular _instance_ of a model
+    # class that refers to a low-card table. Its responsibility is straightforward: it holds onto the actual instances
+    # of the low-card class that we return in response to someone accessing a low-card association. (More concretely:
+    # when you say my_user.status, you get back an instance of UserStatus; if you say my_user.status again, you get back
+    # the same instance of UserStatus. This class is responsible for creating that object in the first place, and
+    # holding onto it so that the same one gets returned all the time.)
+    #
+    # In an ordinary Rails association, you'd get back live, normal instances of the associated class -- just like if
+    # you'd said, say, <tt>UserStatus.find(...)</tt> in the first place. However, this is inappropriate for low-card
+    # associations, because the whole 'trick' of the low-card system is that changing the attributes of the
+    # conceptually-associated +UserStatus+ object actually just changes <em>which +UserStatus+ object you're pointing
+    # at</em>, rather than actually changing a +UserStatus+ row at all.
+    #
+    # We perform a simple trick here instead, composed of three parts:
+    #
+    # * Returned objects from low-card associations are actually clones (Object#dup) of the normal low-card objects
+    #   you'd ordinarily get; this is necessary so that clients can assign attributes to them in any way they want,
+    #   and there's no "crosstalk".
+    # * Returned objects have their ID removed (through a simple <tt>object.id = nil</tt>); this prevents a whole class
+    #   of common coding mistakes. Say you retrieve the low-card object associated with a particular referring object,
+    #   and then modify some of its attributes. Without this change, you'd now be in a situation where you have an
+    #   associated ActiveRecord object (the low-card object) that has a particular set of attributes, and a particular
+    #   ID...and yet, when you call #save -- which will succeed! -- that particular ID doesn't have that set of
+    #   attributes at all. It would be way too easy to write code that looks completely correct, and yet fails; for
+    #   example, you could grab the ID of that associated object and assign it to other referring rows. So we strip the
+    #   ID off completely.
+    # * Returned objects cannot be directly saved at all; if you call #save or #save! on them, you'll get an exception,
+    #   telling you not to do that. The low-card system itself needs to be in complete control of what rows get created,
+    #   and be able to change referring IDs instead.
+    #
+    # These tricks actually happen in LowCardTables::HasLowCardTable::LowCardAssociation#create_low_card_object_for
+    # and LowCardTables::LowCardTable::Base#_low_card_disable_save_when_needed!, but it makes sense to document them
+    # here, since this class is most clearly given this responsibility.
+    class LowCardObjectsManager
+      # Creates a new instance of the LowCardObjectsManager, tied to a particular _instance_ of a low-card model.
+      # That is, +model_instance+ should be an instance of +UserStatus+ or something similar.
+      def initialize(model_instance)
+        @model_instance = model_instance
+        @objects = { }
+      end
+
+      # Returns the low-card object that corresponds to the given LowCardAssociation for this model instance.
+      def object_for(association)
+        association_name = association.association_name.to_s.strip.downcase
+        @objects[association_name] ||= begin
+          association = model_instance.class._low_card_associations_manager._low_card_association(association_name)
+          association.create_low_card_object_for(model_instance)
+        end
+      end
+
+      # Returns the foreign key for the given LowCardAssociation for this model instance. This wouldn't really have to
+      # go through this class for any great reason right now, but, given that #set_foreign_key_for does, it makes a lot
+      # of sense to keep the logic here.
+      def foreign_key_for(association)
+        model_instance[association.foreign_key_column_name]
+      end
+
+      # Sets the foreign key for the given LowCardAssociation for this model instance. We allow users to do this
+      # directly (e.g., <tt>my_user.user_status_id = 17</tt>) so that they can, for example, store +UserStatus+ IDs
+      # out-of-band (in memcache, Redis, or whatever) for any reasons they want. When they do assign the foreign-key
+      # value, we need to invalidate the associated low-card object, since any previous data there is now no longer
+      # valid.
+      def set_foreign_key_for(association, new_value)
+        model_instance[association.foreign_key_column_name] = new_value
+        invalidate_object_for(association)
+        new_value
+      end
+
+      private
+      # Removes the mapped object for a given association -- this simply deletes the object from our hash.
+      def invalidate_object_for(association)
+        @objects.delete(association.association_name)
+      end
+
+      attr_reader :model_instance
+    end
+  end
+end

data/lib/low_card_tables/low_card_table/base.rb

@@ -0,0 +1,184 @@
+require 'active_support/concern'
+require 'low_card_tables/low_card_table/cache_expiration/has_cache_expiration'
+require 'low_card_tables/low_card_table/row_manager'
+
+module LowCardTables
+  module LowCardTable
+    # LowCardTables::LowCardTable::Base is the module that's included into any ActiveRecord model that you declare
+    # +is_low_card_table+ on. As such, it defines the API that's available on low-card tables. (The standard
+    # ActiveRecord API does, of course, still remain available, so you can also use that if you want.)
+    #
+    # Be careful of the distinction between the ClassMethods and instance methods here. ClassMethods are available on
+    # the low-card table as a whole; instance methods apply, of course, to each row individually.
+    module Base
+      extend ActiveSupport::Concern
+
+      # All low-card tables can have their cache-expiration policy set individually.
+      include LowCardTables::LowCardTable::CacheExpiration::HasCacheExpiration
+
+      # Set up cache-policy inheritance -- see HasCacheExpiration for more details.
+      included do
+        low_card_cache_policy_inherits_from ::LowCardTables
+      end
+
+      # This method is a critical entry point from the rest of the low-card system. For example, given our usual
+      # User/UserStatus example -- when you save a User object, the low-card system grabs the associated UserStatus
+      # object and creates a hash, mapping all of the columns in UserStatus to their corresponding values. Next, it
+      # iterates through its in-memory cache, using this method to determine which of the rows in the cache matches
+      # the hash it extracted -- and, when it finds one, that's the row it uses to get the low-card ID to assign
+      # in the associated table.
+      #
+      # *IMPORTANT*: this is not the _only_ context in which this method is used, but merely one example.
+      #
+      # It's possible to override this method to alter behavior; for example, you could use this to translate symbols
+      # to integers, pin values, or otherwise transform data. But be extremely careful when you do this, as you're
+      # playing with a very low-level part of the low-card system.
+      #
+      # Note that the hashes supplied can be partial or complete; that is, they may specify any subset of the values
+      # in this table, or all of them. This method must work accordingly -- if the hashes are partial, then, if this
+      # row's values for the keys that are specified match, then it should return true.
+      #
+      # This is the highest-level, most 'bulk' method -- it asks whether this row matches _any_ of the hashes in the
+      # supplied array.
+      def _low_card_row_matches_any_hash?(hashes)
+        hashes.detect { |hash| _low_card_row_matches_hash?(hash) }
+      end
+
+      # This is called by #_low_card_row_matches_any_hash?, in a loop; it asks whether this row matches the hash
+      # provided. See #_low_card_row_matches_any_hash? for more details. You can override this method instead of that
+      # one, if its semantics work better for your purposes, since its behavior will affect that of
+      # #_low_card_row_matches_any_hash?.
+      def _low_card_row_matches_hash?(hash)
+        hash.keys.all? { |key| _low_card_column_matches?(key, hash[key]) }
+      end
+
+      # This is called by _low_card_row_matches_hash?, in a loop; it asks whether the given column (+key+) matches
+      # the given value (+value+). See #_low_card_row_matches_any_hash? for more details. You can override this method
+      # instead of #_low_card_row_matches_any_hash? or #_low_card_row_matches_hash?, if its semantics work better for
+      # your purposes, since its behavior will affect those methods as well.
+      def _low_card_column_matches?(key, value)
+        self[key.to_s] == value
+      end
+
+      # This method is called from methods like #low_card_rows_matching, when passed a block -- its job is simply to
+      # see if this row is matched by the given block. It's hard to imagine a different implementation than this one,
+      # but it's here in case you want to override it.
+      def _low_card_row_matches_block?(block)
+        block.call(self)
+      end
+
+      module ClassMethods
+        # Declares that this is a low-card table. This should only ever be used on tables that are,
+        # in fact, low-card tables.
+        #
+        # options can contain:
+        #
+        # [:exclude_column_names] Excludes the specified Array of column names from being treated
+        #                         as low-card columns; this happens by default to created_at and
+        #                         updated_at. These columns will not be touched by the low-card
+        #                         code, meaning they have to be nullable or have defaults.
+        # [:max_row_count] The low-card system has a check built in to start raising errors if you
+        #                  appear to be storing data in a low-card table that is, in fact, not actually
+        #                  of low cardinality. The effect that doing this has is to explode the number
+        #                  of rows in the low-card table, so the check simply tests the total number
+        #                  of rows in the table. This defaults to 5,000
+        #                  (in LowCardTables::LowCardTable::Cache::DEFAULT_MAX_ROW_COUNT). If you really
+        #                  do have a valid low-card table with more than this number of rows, you can
+        #                  override that limit here.
+        def is_low_card_table(options = { })
+          self.low_card_options = options
+          _low_card_disable_save_when_needed!
+        end
+
+        # See LowCardTables::HasLowCardTable::LowCardObjectsManager for more details. In short, you should never be
+        # saving low-card objects directly; you should rather let the low-card Gem create such rows for you
+        # automatically, based on the attributes you assign to the model.
+        #
+        # This method is invoked only once, when #is_low_card_table is called.
+        def _low_card_disable_save_when_needed!
+          send(:define_method, :save_low_card_row!) do |*args|
+            begin
+              @_low_card_saves_allowed = true
+              save!(*args)
+            ensure
+              @_low_card_saves_allowed = false
+            end
+          end
+
+          send(:define_method, :save_low_card_row) do |*args|
+            begin
+              @_low_card_saves_allowed = true
+              save(*args)
+            ensure
+              @_low_card_saves_allowed = false
+            end
+          end
+
+          %w{save save!}.each do |method_name|
+            send(:define_method, method_name) do |*args|
+              if @_low_card_saves_allowed
+                super(*args)
+              else
+                raise LowCardTables::Errors::LowCardCannotSaveAssociatedLowCardObjectsError, %{You just tried to save a model that represents a row in a low-card table.
+You can't do this, because the entire low-card system relies on the fact that low-card rows
+are immutable once created. Changing this row would therefore change the logical state of
+many, many rows that are associated with this one, and that is almost certainly not what
+you want.
+
+Instead, simply modify the low-card attributes directly -- typically on the associated object
+(e.g., my_user.deleted = true), or on the low-card object (my_user.status.deleted = true),
+and then save the associated object instead (my_user.save!). This will trigger the low-card
+system to recompute which low-card row the object should be associated with, and update it
+as needed, which is almost certainly what you actually want.
+
+If you are absolutely certain you know what you're doing, you can call #save_low_card_row!
+on this object, and it will save, but make sure you understand ALL the implications first.}
+              end
+            end
+          end
+        end
+
+        # Is this a low-card table? Since this module has been included into the class in question (which happens via
+        # #is_low_card_table), then the answer is always, 'yes'.
+        def is_low_card_table?
+          true
+        end
+
+        # This is a method provided by ActiveRecord::Base. When the set of columns on a low-card table has changed, we
+        # need to tell the row manager, so that it can flush its caches.
+        def reset_column_information
+          out = super
+          _low_card_row_manager.column_information_reset!
+          out
+        end
+
+        # This returns the set of low-card options specified for this class in #is_low_card_table.
+        def low_card_options
+          @_low_card_options ||= { }
+        end
+
+        # This sets the set of low-card options.
+        def low_card_options=(options)
+          @_low_card_options = options
+        end
+
+        # Returns the associated LowCardTables::LowCardTable::RowManager object for this class, which is where an awful
+        # lot of the real work happens.
+        def _low_card_row_manager
+          @_low_card_row_manager ||= LowCardTables::LowCardTable::RowManager.new(self)
+        end
+
+        # All of these methods get delegated to the LowCardRowManager, which does most of the actual work. We prefix
+        # them all with +low_card_+ in order to ensure that we can't possibly collide with methods provided by other
+        # Gems or by client code, since many of the names are pretty generic (e.g., +all_rows+).
+        [ :all_rows, :row_for_id, :rows_for_ids, :rows_matching, :ids_matching, :find_ids_for, :find_or_create_ids_for,
+          :find_rows_for, :find_or_create_rows_for, :flush_cache!, :referring_models, :value_column_names, :referred_to_by,
+          :collapse_rows_and_update_referrers!, :ensure_has_unique_index!, :remove_unique_index! ].each do |delegated_method_name|
+          define_method("low_card_#{delegated_method_name}") do |*args|
+            _low_card_row_manager.send(delegated_method_name, *args)
+          end
+        end
+      end
+    end
+  end
+end