low_card_tables 1.0.0

data/lib/low_card_tables/active_record/relation.rb

@@ -0,0 +1,35 @@
+module LowCardTables
+  module ActiveRecord
+    # This module gets included into ::ActiveRecord::Relation, and is the reason that you can say, for example:
+    #
+    #    User.where(:deleted => false)
+    #
+    # ...when :deleted is actually an attribute on a referenced low-card table. It overrides #where to call
+    # LowCardTables::HasLowCardTable::LowCardDynamicMethodManager#scope_from_query if this is a table that has any
+    # associated low-card tables; that method, in turn, knows how to create a proper WHERE clause for low-card
+    # attributes.
+    module Relation
+      # Overrides ::ActiveRecord::Relation#where to add support for low-card tables.
+      def where(*args)
+        # Escape early if this is a model that has nothing to do with any low-card tables.
+        return super(*args) unless has_any_low_card_tables?
+
+        if args.length == 1 && args[0].kind_of?(Hash)
+          # This is a gross hack -- our overridden #where calls LowCardDynamicMethodManager#scope_from_query,
+          # but that, in turn, needs to call #where, and we don't want an infinite mutual recursion. So, if we
+          # see :_low_card_direct in the Hash passed in, we remove it and then go straight to the superclass --
+          # i.e., this is the 'escape hatch' for LowCardDynamicMethodManager#scope_from_query.
+          direct = args[0].delete(:_low_card_direct)
+
+          if direct
+            super(*args)
+          else
+            _low_card_dynamic_method_manager.scope_from_query(self, args[0])
+          end
+        else
+          super(*args)
+        end
+      end
+    end
+  end
+end

data/lib/low_card_tables/active_record/scoping.rb

@@ -0,0 +1,87 @@
+require 'active_support/concern'
+
+module LowCardTables
+  module ActiveRecord
+    # This module gets included into ::ActiveRecord::Scoping. It overrides #scope to do one thing, and one thing only:
+    # it checks to see if you're defining a scope that constrains on low-card columns, statically. ('Statically' here
+    # means the deprecated-in-Rails-4.0+ style of 'scope :foo, where(...)' rather than 'scope :foo { where(...) }'.)
+    # If it finds that you're trying to define such a scope, it throws an error.
+    #
+    # Why does it do this? Statically-defined scopes have their #where calls evaluated only once, at class-load time.
+    # But part of the design of the low-card system is that new low-card rows can be added at runtime, and new rows
+    # may well fit whatever constraint you're applying in this scope. The low-card system translates calls such as this:
+    #
+    #     where(:deleted => false)
+    #
+    # into clauses like this:
+    #
+    #     WHERE user_status_id IN (1, 3, 4, 5, 8, 9, 12)
+    #
+    # Because new rows can be added at any time, the list of status IDs needs to be able to be computed dynamically.
+    # Static scopes prevent this, so we detect this condition here and raise an exception when it occurs.
+    #
+    # This sort of problem, by the way, is one of the reasons why static scope definitions are deprecated in Rails
+    # 4.x.
+    module Scoping
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Overrides #scope to check for statically-defined scopes against low-card attributes, as discussed in the
+        # comment for LowCardTables::ActiveRecord::Scoping.
+        def scope(name, scope_options = {}, &block)
+          # First, go invoke the superclass method.
+          out = super(name, scope_options, &block)
+
+          # We're safe if it's not a statically-defined scope.
+          return out if block
+          # We're also safe if this class doesn't refer to any low-card tables, because then it could not possibly
+          # have been constraining on any low-card columns.
+          return out if (! self.has_any_low_card_tables?)
+          # If you defined a scope that isn't an actual ::ActiveRecord::Relation, you're fine.
+          return out unless scope_options.kind_of?(::ActiveRecord::Relation)
+
+          # ::ActiveRecord::Relation#where_values gets you a list of the 'where clauses' applied in the relation.
+          used_associations = scope_options.where_values.map do |where_value|
+            # Let's grab the SQL...
+            sql = if where_value.respond_to?(:to_sql)
+              where_value.to_sql
+            elsif where_value.kind_of?(String)
+              where_value
+            end
+
+            # ...and just search it for the foreign-key name. Is this foolproof? No; it's possible that you'll get some
+            # false positives. Is this a big deal? No -- because changing a static scope to dynamic really has no
+            # drawbacks at all, so there's a trivial fix for any false positives.
+            self._low_card_associations_manager.associations.select do |association|
+              foreign_key = association.foreign_key_column_name
+              sql =~ /#{foreign_key}/i
+            end
+          end.flatten
+
+          # Here's where we check for our problem and blow up if it's there.
+          if used_associations.length > 0
+            raise LowCardTables::Errors::LowCardStaticScopeError, %{You defined a named scope, #{name.inspect}, on model #{self.name}. This scope
+appears to constrain on the following foreign keys, which point to low-card tables.
+Because this scope is defined statically (e.g., 'scope :foo, where(...)' rather than
+'scope :foo { where(...) }'), these conditions will only be evaluated a single time,
+at startup.
+
+This means that if additional low-card rows get created that match the criteria for
+this scope, they will never be picked up no matter what (as the WHERE clause is
+frozen in time forever), and you will miss critical data.
+
+The fix for this is simple: define this scope dynamically (i.e., enclose the
+call to #where in a block). This will cause the conditions to be evaluated every
+time you use it, thus updating the set of IDs used on every call, properly.
+
+The foreign keys you appear to be constraining on are:
+
+#{used_associations.map(&:foreign_key_column_name).sort.join(", ")}}
+          end
+
+          out
+        end
+      end
+    end
+  end
+end

data/lib/low_card_tables/errors.rb

@@ -0,0 +1,74 @@
+module LowCardTables
+  # This module contains definitions of all exception classes used by +low_card_tables+. Note that +low_card_tables+
+  # does not try to wrap any exception bubbled up by methods it calls as a LowCardError; rather, these are just used
+  # to raise exceptions specific to +low_card_tables+.
+  #
+  # Any errors that are raised due to programming errors -- i.e., defensive detection of things that should never,
+  # ever occur in the real world -- are left as ordinary StandardError instances, since you almost certainly don't
+  # want to ever catch them.
+  module Errors
+    # All errors raised by LowCardTables inherit from this error. All errors raised are subclasses of this error, and
+    # are never direct instances of this class.
+    class LowCardError < StandardError; end
+
+    # The superclass of the two errors below -- errors having to do with the schema of the low-card table.
+    class LowCardColumnError < LowCardError; end
+
+    # Raised when the client specifies a column in a low-card table that doesn't actually exist -- for example, when
+    # trying to create new rows, or match against existing rows.
+    class LowCardColumnNotPresentError < LowCardColumnError; end
+    # Raised when the client does not specify a column in a call that requires all columns to be specified -- for
+    # example, when trying to find the ID of a row by its attributes.
+    class LowCardColumnNotSpecifiedError < LowCardColumnError; end
+
+    # Raised when there is no unique index present on the low-card table across all value columns. This index is
+    # required for operation of +low_card_tables+; various facilities in its support for migrations (and an explicit
+    # API call) will create or remove it for you at your request, or just maintain it automatically.
+    class LowCardNoUniqueIndexError < LowCardError; end
+
+    # Raised when you explicitly ask for a row or rows by ID, and no such ID exists in the database. +ids+ is included
+    # as an attribute of the error class, and contains an array of the IDs that were not found.
+    class LowCardIdNotFoundError < LowCardError
+      def initialize(message, ids)
+        super(message)
+        @ids = ids
+      end
+
+      attr_reader :ids
+    end
+
+    # The superclass of the error below -- raised when there's a problem with associations from a referring class to
+    # one or more low-card tables.
+    class LowCardAssociationError < LowCardError; end
+    # Raised internally when asked for an association from a referring class by name, and no such association exists.
+    class LowCardAssociationNotFoundError < LowCardAssociationError; end
+
+    # Raised when a client tries to call #save or #save! on an associated low-card row (e.g., my_user.status.save!);
+    # this is disallowed because it circumvents the entire purpose/idea of the low-card system.
+    class LowCardCannotSaveAssociatedLowCardObjectsError < LowCardError; end
+
+    # Raised when you try to create a low-card row or rows that the database treats as invalid. Typically, this means
+    # you violated a database constraint when trying to create those rows.
+    class LowCardInvalidLowCardRowsError < LowCardError; end
+
+    # Raised when you try to define a scope involving a low-card table in a static way, rather than dynamic. (e.g., you
+    # say, in class User, scope :alive, where(:deleted => false)) These scopes have their 'where' definitions evaluated
+    # only once, at class definition time, and, as such, cannot ever pick up any new IDs of low-card rows that later
+    # get created that match their definition. As such, we completely disallow their creation, and raise this error if
+    # you try.
+    #
+    # The solution is trivial, and is to define them dynamically --
+    # <tt>scope :alive, -> { where(:deleted => false) }</tt>. This is what ActiveRecord >= 4.0 requires, anyway -- the
+    # static form is deprecated.
+    class LowCardStaticScopeError < LowCardError; end
+
+    # Raised when you try to use +low_card_tables+ with a database that isn't supported. It's very easy to support new
+    # databases; you just have to teach the RowManager how to obtain an exclusive table lock on your type of database.
+    class LowCardUnsupportedDatabaseError < LowCardError; end
+
+    # Raised when we detect that there are more than (by default) 5,000 rows in a low-card table; this is taken as a
+    # sign that you screwed up and added an attribute to your table that isn't actually of low cardinality. You can
+    # adjust this threshold, if necessary, using the option +:max_row_count+ on your +is_low_card_table+ definition.
+    class LowCardTooManyRowsError < LowCardError; end
+  end
+end

data/lib/low_card_tables/has_low_card_table/base.rb

@@ -0,0 +1,114 @@
+require 'active_support/concern'
+require 'low_card_tables/has_low_card_table/low_card_associations_manager'
+require 'low_card_tables/has_low_card_table/low_card_objects_manager'
+require 'low_card_tables/has_low_card_table/low_card_dynamic_method_manager'
+
+module LowCardTables
+  module HasLowCardTable
+    # This module gets included (once) into any class that has declared a reference to at least one low-card table,
+    # using #has_low_card_table. It is just a holder for several related objects that do all the actual work of
+    # implementing the referring side of the low-card system.
+    module Base
+      # Documentation for class methods that get included via the ClassMethods module (which ActiveSupport::Concern
+      # picks up).
+
+      ##
+      # :singleton-method: has_low_card_table
+      # :call-seq:
+      #   has_low_card_table(association_name, options = nil)
+      #
+      # Declares that this model class has a reference to a low-card table. +association_name+ is the name of the
+      # association to create. +options+ can contain:
+      #
+      # [:delegate] If nil, no methods will be created in this class that delegate to the low-card table at all.
+      #             If an Array, only methods matching those strings/symbols will be created.
+      #             If a Hash, must contain a single key, +:except+, which maps to an Array; all methods except those
+      #             methods will be created.
+      #             Not specifying +:delegate+ causes it to delegate all methods in the low-card table.
+      # [:prefix] If true, then delegated methods will be named with a prefix of the association name -- for example,
+      #           +status_deleted+, +status_donation_level+, and so on.
+      #           If a String or Symbol, then delegated methods will be named with that prefix -- for example,
+      #           +foo_deleted+, +foo_donation_level+, and so on.
+      #           Not specifying +:prefix+ is the same as saying +:prefix+ => +nil+, which causes methods not to be
+      #           prefixed with anything.
+      # [:foreign_key] Specifies the column in the referring table that contains the foreign key to the low-card table,
+      #                just as in ActiveRecord associations. If not specified, it defaults to
+      #                #{self.name.underscore}_#{association_name}_id -- for example, +user_status_id+.
+      # [:class] Specifies the model class of the low-card table, as a String, Symbol, or Class object. If not
+      #          specified, defaults to ("#{self.name.underscore.singularize}_#{association_name}".camelize.constantize)
+      #          -- for example, +UserStatus+.
+
+      ##
+      # :singleton-method: low_card_value_collapsing_update_scheme
+      # :call-seq:
+      #    low_card_value_collapsing_update_scheme(scheme)
+      #
+      # Tells the low-card tables system what to do when a low-card table we refer to removes a column, which causes
+      # it to collapse rows and thus necessitiates updating the referring column.
+      #
+      # * If called with no arguments, returns the current scheme.
+      # * If passed an integer >= 1, automatically updates referring columns in this table, in chunks of that many
+      #   rows. This is the default, with a value of 10,000.
+      # * If passed an object that responds to #call, then, when columns need to be updated, the passed object is called
+      #   with a Hash. This Hash has, as keys, instances of the low-card model class; these are the rows that will be
+      #   preserved. Each key maps to an Array of one or more instances of the low-card model class; these are the
+      #   rows that are to be replaced with the key. The passed object is then responsible for updating any values that
+      #   correspond to rows in a value Array with the corresponding key value.
+      # * If passed +:none+, then no updating is performed at all. You're on your own -- and you will have dangling
+      #   foreign keys if you do nothing.
+
+      extend ActiveSupport::Concern
+
+
+      module ClassMethods
+        # Several methods go straight to the LowCardAssociationsManager.
+        delegate :has_low_card_table, :_low_card_association, :_low_card_update_collapsed_rows, :low_card_value_collapsing_update_scheme, :to => :_low_card_associations_manager
+
+        # This overrides the implementation in LowCardTables::ActiveRecord::Base -- the only way we get included in
+        # a class is if that class has declared has_low_card_table to at least one table.
+        def has_any_low_card_tables?
+          true
+        end
+
+        # The LowCardAssociationsManager keeps track of which low-card tables this table refers to; see its
+        # documentation for more information.
+        def _low_card_associations_manager
+          @_low_card_associations_manager ||= LowCardTables::HasLowCardTable::LowCardAssociationsManager.new(self)
+        end
+
+        # The LowCardDynamicMethodManager is responsible for maintaining the right delegated method names in the
+        # _low_card_dynamic_methods_module; see its documentation for more information.
+        def _low_card_dynamic_method_manager
+          @_low_card_dynamic_method_manager ||= LowCardTables::HasLowCardTable::LowCardDynamicMethodManager.new(self)
+        end
+
+        # This maintains a single module that gets included into this class; it is the place where we add all
+        # delegated methods. We use a module rather than defining them directly on this class so that users can still
+        # override them and use #super to call our implementation, if desired.
+        def _low_card_dynamic_methods_module
+          @_low_card_dynamic_methods_module ||= begin
+            out = Module.new
+            self.const_set(:LowCardDynamicMethods, out)
+            include out
+            out
+          end
+        end
+      end
+
+      # Updates the current values of all low-card reference columns according to the current attributes. This is
+      # automatically called in a #before_save hook; you can also call it yourself at any time. Note that this can
+      # cause new low-card rows to be created, if the current combination of attributes for a given low-card table
+      # has not been used before.
+      def low_card_update_foreign_keys!
+        self.class._low_card_associations_manager.low_card_update_foreign_keys!(self)
+      end
+
+      # Returns the LowCardObjectsManager, which is responsible for maintaining the set of low-card objects accessed
+      # by this model object -- the instances of the low-card class that are "owned" by this object. See that class's
+      # documentation for more information.
+      def _low_card_objects_manager
+        @_low_card_objects_manager ||= LowCardTables::HasLowCardTable::LowCardObjectsManager.new(self)
+      end
+    end
+  end
+end

data/lib/low_card_tables/has_low_card_table/low_card_association.rb

@@ -0,0 +1,273 @@
+module LowCardTables
+  module HasLowCardTable
+    # A LowCardAssociation represents a single association between a referring model class and a referred-to low-card
+    # model class. Note that this represents an association between _classes_, not between _objects_ -- that is, there
+    # is one instance of this class for a relationship from one referring class to one referred-to class, no matter
+    # how many model objects are instantiated.
+    class LowCardAssociation
+      # Returns the name of the association -- this will always have been the first arguent to +has_low_card_table+.
+      attr_reader :association_name
+
+      # Creates a new instance. model_class is the Class (which must inherit from ActiveRecord::Base) that is the
+      # referring model; association_name is the name of the association. options can contain any of the options
+      # accepted by LowCardTables::HasLowCardTables::Base#has_low_card_table.
+      def initialize(model_class, association_name, options)
+        @model_class = model_class
+        @association_name = association_name.to_s
+        @options = options.with_indifferent_access
+
+        # We call this here so that if things are configured incorrectly, you'll get an exception at the moment you
+        # try to associate the tables, rather than at runtime when you try to actually use them. Blowing up early is
+        # good. :)
+        foreign_key_column_name
+
+        low_card_class.low_card_referred_to_by(model_class)
+      end
+
+      # Returns a Hash that maps the names of methods that should be added to the referring class to the names of
+      # methods they should invoke on the low-card class. This takes into account both the +:delegate+ option (via
+      # its internal call to #delegated_method_names) and the +:prefix+ option.
+      def class_method_name_to_low_card_method_name_map
+        return { } if options.has_key?(:delegate) && (! options[:delegate])
+
+        out = { }
+
+        delegated_method_names.each do |column_name|
+          desired_method_name = case options[:prefix]
+          when true then "#{association_name}_#{column_name}"
+          when String, Symbol then "#{options[:prefix]}_#{column_name}"
+          when nil then column_name
+          else raise ArgumentError, "Invalid :prefix option: #{options[:prefix].inspect}"
+          end
+
+          out[desired_method_name] = column_name
+          out[desired_method_name + "="] = column_name + "="
+        end
+
+        out
+      end
+
+      # Returns an Array of names of methods on the low-card table that should be delegated to. This may be different
+      # than the names of methods on the referring class, because of the :prefix option.
+      def delegated_method_names
+        value_column_names = low_card_class.low_card_value_column_names.map(&:to_s)
+
+        if options.has_key?(:delegate) && (! options[:delegate])
+          [ ]
+        elsif options[:delegate].kind_of?(Array) || options[:delegate].kind_of?(String) || options[:delegate].kind_of?(Symbol)
+          out = Array(options[:delegate]).map(&:to_s)
+          extra = out - value_column_names
+
+          if extra.length > 0
+            raise ArgumentError, "You told us to delegate the following methods to low-card class #{low_card_class}, but that model doesn't have these columns: #{extra.join(", ")}; it has these columns: #{value_column_names.join(", ")}"
+          end
+          out
+        elsif options[:delegate] && options[:delegate].kind_of?(Hash) && options[:delegate].keys.map(&:to_s) == %w{except}
+          excluded = (options[:delegate][:except] || options[:delegate]['except']).map(&:to_s)
+          extra = excluded - value_column_names
+
+          if extra.length > 0
+            raise ArgumentError, "You told us to delegate all but the following methods to low-card class #{low_card_class}, but that model doesn't have these columns: #{extra.join(", ")}; it has these columns: #{value_column_names.join(", ")}"
+          end
+
+          value_column_names - excluded
+        elsif (! options.has_key?(:delegate)) || options[:delegate] == true
+          value_column_names
+        else
+          raise ArgumentError, "Invalid value for :delegate: #{options[:delegate].inspect}"
+        end
+      end
+
+      # Given an instance of the referring class, returns an instance of the low-card class that is configured correctly
+      # for the current value of the referring column.
+      def create_low_card_object_for(model_instance)
+        ensure_correct_class!(model_instance)
+
+        id = get_id_from_model(model_instance)
+
+        out = nil
+        if id
+          template = low_card_class.low_card_row_for_id(id)
+          out = template.dup
+          out.id = nil
+          out
+        else
+          out = low_card_class.new
+        end
+
+        out
+      end
+
+      # Computes the correct name of the foreign-key column based on the options passed in.
+      def foreign_key_column_name
+        @foreign_key_column_name ||= begin
+          out = options[:foreign_key]
+
+          unless out
+            out = "#{@model_class.name.underscore}_#{association_name}"
+            out = $1 if out =~ %r{/[^/]+$}i
+            out = out + "_id"
+          end
+
+          out = out.to_s if out.kind_of?(Symbol)
+
+          column = model_class.columns.detect { |c| c.name.strip.downcase == out.strip.downcase }
+          unless column
+            raise ArgumentError, %{You said that #{model_class} has_low_card_table :#{association_name}, and we
+have a foreign-key column name of #{out.inspect}, but #{model_class} doesn't seem
+to have a column named that at all. Did you misspell it? Or perhaps something else is wrong?
+
+The model class has these columns: #{model_class.columns.map(&:name).sort.join(", ")}}
+          end
+
+          out
+        end
+      end
+
+      # When a low-card table has a column removed, it will typically have duplicate rows; these duplicate rows are
+      # then deleted. But then referring tables need to be updated. This method gets called at that point, with a map
+      # of <winner row> => <array of loser rows>, and the +collapsing_update_scheme+ declared by this referring
+      # model class. It is responsible for handling whatever collapsing update scheme has been declared properly.
+      def update_collapsed_rows(collapse_map, collapsing_update_scheme)
+        if collapsing_update_scheme.respond_to?(:call)
+          collapsing_update_scheme.call(collapse_map)
+        elsif collapsing_update_scheme == :none
+          # nothing to do
+        else
+          row_chunk_size = collapsing_update_scheme
+          current_id = @model_class.order("#{@model_class.primary_key} ASC").first.id
+
+          while true
+            current_id = update_collapsed_rows_batch(current_id, row_chunk_size, collapse_map)
+            break if (! current_id)
+          end
+        end
+      end
+
+      # Updates the foreign key for this association on the given model instance. This is called by
+      # LowCardTables::HasLowCardTable::Base#low_card_update_foreign_keys!, which is primarily invoked by a
+      # +:before_save+ filter and alternatively can be invoked manually.
+      def update_foreign_key!(model_instance)
+        hash = { }
+
+        low_card_object = model_instance._low_card_objects_manager.object_for(self)
+
+        low_card_class.low_card_value_column_names.each do |value_column_name|
+          hash[value_column_name] = low_card_object[value_column_name]
+        end
+
+        new_id = low_card_class.low_card_find_or_create_ids_for(hash)
+
+        unless get_id_from_model(model_instance) == new_id
+          set_id_on_model(model_instance, new_id)
+        end
+      end
+
+      # Figures out what the low-card class this association should use is; this uses convention, with some overrides.
+      #
+      # By default, for a class User that <tt>has_low_card_table :status</tt>, it looks for a class UserStatus. This
+      # is intentionally different from Rails' normal conventions, where it would simply look for a class Status. This
+      # is because low-card tables are almost always unique to their owning table -- _i.e._, the case where multiple
+      # tables say +has_low_card_table+ to the same low-card table is very rare. (This is just because having multiple
+      # tables that have -- <em>and always will have</em> -- the same set of low-card attributes is also quite rare.)
+      # Hence, we use a little more default specificity in the naming.
+      def low_card_class
+        @low_card_class ||= begin
+          # e.g., class User has_low_card_table :status => UserStatus
+          out = options[:class] || "#{model_class.name.underscore.singularize}_#{association_name}"
+
+          out = out.to_s if out.kind_of?(Symbol)
+          out = out.camelize if out.kind_of?(String)
+
+          if out.kind_of?(String)
+            begin
+              out = out.constantize
+            rescue NameError => ne
+              raise ArgumentError, %{You said that #{model_class} has_low_card_table :#{association_name}, and we have a
+:class of #{out.inspect}, but, when we tried to load that class (via #constantize),
+we got a NameError. Perhaps you misspelled it, or something else is wrong?
+
+NameError: (#{ne.class.name}): #{ne.message}}
+            end
+          end
+
+          unless out.kind_of?(Class)
+            raise ArgumentError, %{You said that #{model_class} has_low_card_table :#{association_name} with a
+:class of #{out.inspect}, but that isn't a String or Symbol that represents a class,
+or a valid Class object itself.}
+          end
+
+          unless out.respond_to?(:is_low_card_table?) && out.is_low_card_table?
+            raise ArgumentError, %{You said that #{model_class} has_low_card_table :#{association_name},
+and we have class #{out} for that low-card table (which is a Class), but it
+either isn't an ActiveRecord model or, if so, it doesn't think it is a low-card
+table itself (#is_low_card_table? returns false).
+
+Perhaps you need to declare 'is_low_card_table' on that class?}
+          end
+
+          out
+        end
+      end
+
+      private
+      attr_reader :options, :model_class
+
+      # This is the method that actually updates rows in the referring table when a column is removed from a low-card
+      # table (and hence IDs are collapsed). It's called repeatedly, in a loop, from #update_collapsed_rows. One call
+      # of this method updates one 'chunk' of rows, where the row-chunk size is whatever was specified by a call to
+      # LowCardTables::HasLowCardTable::Base#low_card_value_collapsing_update_scheme. When it's done, it either returns
+      # +nil+, if there are no more rows to update, or the ID of the next row that should be updated, if there are.
+      #
+      # +starting_id+ is the primary-key value that this chunk should start at. (We always update rows in ascending
+      # primary-key order, starting with the smallest primary key.) +row_chunk_size+ is the number of rows that should
+      # be updated. +collapse_map+ contains only objects of the low-card class, mapping 'winners' to arrays of 'losers'.
+      # (That is, we must update all rows containing any ID found in an array of values to the corresponding ID found
+      # in the key.)
+      #
+      # Note that this method goes out of its way to not have a common bug: if you simply update rows from
+      # +starting_id+ to <tt>starting_id + row_chunk_size</tt>, then large gaps in the ID space will destroy performance
+      # completely. Rather than ever doing math on the primary key, we just tell the database to order rows in primary-
+      # key order and do chunks of the appropriate size.
+      def update_collapsed_rows_batch(starting_id, row_chunk_size, collapse_map)
+        starting_at_starting_id = model_class.where("#{model_class.primary_key} >= :starting_id", :starting_id => starting_id)
+
+        # Databases will return no rows if asked for an offset past the end of the table.
+        one_past_ending_row = starting_at_starting_id.order("#{model_class.primary_key} ASC").offset(row_chunk_size).first
+        one_past_ending_id = one_past_ending_row.id if one_past_ending_row
+
+        base_scope = starting_at_starting_id
+        if one_past_ending_id
+          base_scope = base_scope.where("#{model_class.primary_key} < :one_past_ending_id", :one_past_ending_id => one_past_ending_id)
+        end
+
+        # Do a series of updates -- one per entry in the +collapse_map+.
+        collapse_map.each do |collapse_to, collapse_from_array|
+          conditional = base_scope.where([ "#{foreign_key_column_name} IN (:collapse_from)", { :collapse_from => collapse_from_array.map(&:id) } ])
+          conditional.update_all([ "#{foreign_key_column_name} = :collapse_to", { :collapse_to => collapse_to.id } ])
+        end
+
+        one_past_ending_id
+      end
+
+      # Fetches the ID from the referring model, by simply grabbing the value of its foreign-key column.
+      def get_id_from_model(model_instance)
+        model_instance[foreign_key_column_name]
+      end
+
+      # Sets the ID on the referring model, by setting the value of its foreign-key column.
+      def set_id_on_model(model_instance, new_id)
+        model_instance[foreign_key_column_name] = new_id
+      end
+
+      # Ensures that the given +model_instance+ is an instance of the referring model class.
+      def ensure_correct_class!(model_instance)
+        unless model_instance.kind_of?(model_class)
+          raise %{Whoa! The LowCardAssociation '#{association_name}' for class #{model_class} somehow
+was passed a model of class #{model_instance.class} (model: #{model_instance}),
+which is not of the correct class.}
+        end
+      end
+    end
+  end
+end