Allow ancestry to define a primary ancestry key

Introduce primary_ancestry_key class variable and ancestry_id instance
method as the indirection point for which column values are stored in
ancestry paths. Defaults to :id. On Rails 7.2+, auto-detects from
primary_key. On older Rails, must be passed explicitly via
has_ancestry primary_key: :code.

Replaces bare id/node.id with ancestry_id/node.ancestry_id throughout
static modules (instance_methods.rb, class_methods.rb) and builder.
Replaces scope.primary_key with scope.primary_ancestry_key for record
lookups by ancestry values.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kbrock

lib/ancestry/class_methods.rb

@@ -7,7 +7,7 @@ def to_node(object)
       if object.is_a?(ancestry_base_class)
         object
       else
-        unscoped_where { |scope| scope.find(object.try(primary_key) || object) }
+        unscoped_where { |scope| scope.find_by!(primary_ancestry_key => object.try(primary_ancestry_key) || object) }
       end
     end
 
@@ -52,17 +52,17 @@ def arrange(options = {})
     # @returns Hash{Node => {Node => {}, Node => {}}}
     # If a node's parent is not included, the node will be included as if it is a top level node
     def arrange_nodes(nodes, orphan_strategy: :rootify)
-      node_ids = Set.new(nodes.map(&:id))
+      node_ids = Set.new(nodes.map(&:ancestry_id))
       index = Hash.new { |h, k| h[k] = {} }
 
       if orphan_strategy == :rootify
         nodes.each_with_object({}) do |node, arranged|
-          index[node.parent_id][node] = children = index[node.id]
+          index[node.parent_id][node] = children = index[node.ancestry_id]
           arranged[node] = children unless node_ids.include?(node.parent_id)
         end
       else
         nodes.each_with_object({}) do |node, arranged|
-          index[node.parent_id][node] = children = index[node.id]
+          index[node.parent_id][node] = children = index[node.ancestry_id]
           if node.parent_id.nil?
             arranged[node] = children
           elsif !node_ids.include?(node.parent_id)
@@ -150,14 +150,14 @@ def self._check_ancestry_integrity!(klass, column, options = {})
           # ... check validity of ancestry column
           if !node.sane_ancestor_ids?
             raise Ancestry::AncestryIntegrityException, I18n.t("ancestry.invalid_ancestry_column",
-                                                               :node_id => node.id,
+                                                               :node_id => node.ancestry_id,
                                                                :ancestry_column => node.read_attribute(column))
           end
           # ... check that all ancestors exist
           node.ancestor_ids.each do |ancestor_id|
-            unless klass.exists?(ancestor_id)
+            unless klass.exists?(klass.primary_ancestry_key => ancestor_id)
               raise Ancestry::AncestryIntegrityException, I18n.t("ancestry.reference_nonexistent_node",
-                                                                 :node_id => node.id,
+                                                                 :node_id => node.ancestry_id,
                                                                  :ancestor_id => ancestor_id)
             end
           end
@@ -197,20 +197,20 @@ def restore_ancestry_integrity!
               end
             end
             # ... save parent id of this node in parent_ids array if it exists
-            parent_ids[node.id] = node.parent_id if exists? node.parent_id
+            parent_ids[node.ancestry_id] = node.parent_id if exists?(primary_ancestry_key => node.parent_id)
 
             # Reset parent id in array to nil if it introduces a cycle
-            parent_id = parent_ids[node.id]
-            until parent_id.nil? || parent_id == node.id
+            parent_id = parent_ids[node.ancestry_id]
+            until parent_id.nil? || parent_id == node.ancestry_id
               parent_id = parent_ids[parent_id]
             end
-            parent_ids[node.id] = nil if parent_id == node.id
+            parent_ids[node.ancestry_id] = nil if parent_id == node.ancestry_id
           end
 
           # For each node ...
           scope.find_each do |node|
             # ... rebuild ancestry from parent_ids array
-            ancestor_ids, parent_id = [], parent_ids[node.id]
+            ancestor_ids, parent_id = [], parent_ids[node.ancestry_id]
             until parent_id.nil?
               ancestor_ids, parent_id = [parent_id] + ancestor_ids, parent_ids[parent_id]
             end
@@ -229,7 +229,7 @@ def build_ancestry_from_parent_ids!(column = :parent_id, parent_id = nil, ancest
           node.without_ancestry_callbacks do
             node.update_attribute :ancestor_ids, ancestor_ids
           end
-          build_ancestry_from_parent_ids! column, node.id, ancestor_ids + [node.id]
+          build_ancestry_from_parent_ids! column, node.ancestry_id, ancestor_ids + [node.ancestry_id]
         end
       end
     end
@@ -274,7 +274,7 @@ def self._rebuild_parent_id_cache!(klass, parent_cache_column)
     def self._rebuild_counter_cache!(klass, column, counter_col, verbose: false)
       child_sql = klass.child_ancestry_sql
       tbl = klass.table_name
-      pk = klass.primary_key
+      pk = klass.primary_ancestry_key
 
       fixed =
         if verbose
@@ -311,7 +311,7 @@ def self._rebuild_counter_cache!(klass, column, counter_col, verbose: false)
     # Builder generates thin wrappers that delegate here with baked-in column.
 
     def self._ancestry_exclude_self(record)
-      record.errors.add(:base, I18n.t("ancestry.exclude_self", class_name: record.class.model_name.human)) if record.ancestor_ids.include?(record.id)
+      record.errors.add(:base, I18n.t("ancestry.exclude_self", class_name: record.class.model_name.human)) if record.ancestor_ids.include?(record.ancestry_id)
     end
 
     def self._update_descendants_with_new_ancestry(record)
@@ -350,7 +350,7 @@ def self._apply_orphan_strategy_adopt(record)
 
       record.class.ancestry_base_class.descendants_of(record).each do |descendant|
         descendant.without_ancestry_callbacks do
-          descendant.update_attribute :ancestor_ids, descendant.ancestor_ids - [record.id]
+          descendant.update_attribute :ancestor_ids, descendant.ancestor_ids - [record.ancestry_id]
         end
       end
     end

lib/ancestry/has_ancestry.rb

@@ -8,7 +8,7 @@ def has_ancestry(options = {})
         raise Ancestry::AncestryException, I18n.t("ancestry.option_must_be_hash")
       end
 
-      extra_keys = options.keys - [:ancestry_column, :orphan_strategy, :cache_depth, :depth_cache_column, :touch, :counter_cache, :primary_key_format, :update_strategy, :ancestry_format, :format, :parent, :root, :associations]
+      extra_keys = options.keys - [:ancestry_column, :orphan_strategy, :cache_depth, :depth_cache_column, :touch, :counter_cache, :primary_key_format, :primary_key, :update_strategy, :ancestry_format, :format, :parent, :root, :associations]
       if (key = extra_keys.first)
         raise Ancestry::AncestryException, I18n.t("ancestry.unknown_option", key: key.inspect, value: options[key].inspect)
       end
@@ -28,6 +28,18 @@ def has_ancestry(options = {})
       class_variable_set('@@ancestry_base_class', self)
       cattr_reader :ancestry_base_class, instance_reader: false
 
+      # Define the column used to identify nodes in ancestry paths
+      # ActiveRecord::VERSION::STRING < "7.2" hits DB for primary_key, so fall back to :id
+      pk = if options[:primary_key]
+        options[:primary_key]
+      elsif ActiveRecord::VERSION::STRING >= "7.2"
+        primary_key
+      else
+        :id
+      end
+      class_variable_set('@@primary_ancestry_key', pk.to_sym)
+      cattr_reader :primary_ancestry_key, instance_reader: false
+
       # Include instance methods
       include Ancestry::InstanceMethods
 
@@ -113,6 +125,7 @@ def has_ancestry(options = {})
       # This extends ClassMethods (scopes, helpers) and includes instance methods
       generated_mod = Ancestry::InstanceMethodsBuilder.build(
         format_module, column, root,
+        primary_key: primary_ancestry_key,
         integer_pk: integer_pk,
         depth_cache_column: depth_cache_column,
         counter_cache_column: counter_cache_column,

lib/ancestry/instance_methods.rb

@@ -2,6 +2,14 @@
 
 module Ancestry
   module InstanceMethods
+    def ancestry_id
+      read_attribute(self.class.primary_ancestry_key)
+    end
+
+    def ancestry_id_before_last_save
+      attribute_before_last_save(self.class.primary_ancestry_key)
+    end
+
     # Validate that descendants' depths don't exceed max depth when moving them
     # Called from generated ancestry_depth_of_descendants with baked column names
     def validate_depth_of_descendants(depth_cache_column, depth_change)
@@ -29,7 +37,7 @@ def ancestry_sync_parent_cache(parent_cache_column, value, association_name = :p
 
     # Sync root cache column and reset association after ancestry change
     def ancestry_sync_root_cache(root_cache_column, value, association_name = :root)
-      write_attribute(root_cache_column, value.first || id) if root_cache_column
+      write_attribute(root_cache_column, value.first || ancestry_id) if root_cache_column
       association(association_name).reset if association_cached?(association_name)
     end
 
@@ -38,7 +46,7 @@ def ancestry_lookup_parent(association_name = :parent)
       if association(association_name).loaded?
         association(association_name).target
       else
-        unscoped_where { |scope| scope.find_by(scope.primary_key => parent_id) }
+        unscoped_where { |scope| scope.find_by(scope.primary_ancestry_key => parent_id) }
       end
     end
 
@@ -47,14 +55,14 @@ def ancestry_lookup_root(association_name = :root)
       if association(association_name).loaded?
         association(association_name).target || self
       else
-        unscoped_where { |scope| scope.find_by(scope.primary_key => root_id) } || self
+        unscoped_where { |scope| scope.find_by(scope.primary_ancestry_key => root_id) } || self
       end
     end
 
     # Add root cache update to SQL update clause for descendants
     def add_root_cache_to_update_clause(update_clause, root_cache_column)
-      old_root_id = ancestor_ids_before_last_save.first || id_before_last_save
-      new_root_id = ancestor_ids.first || id
+      old_root_id = ancestor_ids_before_last_save.first || ancestry_id_before_last_save
+      new_root_id = ancestor_ids.first || ancestry_id
       if old_root_id != new_root_id
         update_clause[root_cache_column] = new_root_id
       end
@@ -85,7 +93,7 @@ def ancestry_callbacks_disabled?
     # works with after save context (hence before_last_save)
     def unscoped_current_and_previous_ancestors
       unscoped_where do |scope|
-        scope.where(scope.primary_key => (ancestor_ids + ancestor_ids_before_last_save).uniq)
+        scope.where(scope.primary_ancestry_key => (ancestor_ids + ancestor_ids_before_last_save).uniq)
       end
     end
 

lib/ancestry/instance_methods_builder.rb

@@ -13,7 +13,7 @@ module InstanceMethodsBuilder
     # @param parent_cache_column [String, nil] column name for parent cache, or nil
     # @param root_cache_column [String, nil] column name for root cache, or nil
     # @return [Module] a named module with baked-in instance methods
-    def self.build(format_module, column, root, primary_key: :id, integer_pk: nil, depth_cache_column: nil, counter_cache_column: nil, parent_cache_column: nil, root_cache_column: nil, parent_association: false, root_association: false)
+    def self.build(format_module, column, root, primary_key:, integer_pk: nil, depth_cache_column: nil, counter_cache_column: nil, parent_cache_column: nil, root_cache_column: nil, parent_association: false, root_association: false)
       pk = primary_key
       parse_method = integer_pk ? :parse_integer : :parse
       format_name = format_module.name.split("::").last
@@ -84,15 +84,15 @@ def sibling_of?(node)
         def child_ancestry
           raise(Ancestry::AncestryException, I18n.t("ancestry.no_child_for_new_record")) if new_record?
 
-          #{format_module}.child_ancestry_value(attribute_in_database(:#{column}), id)
+          #{format_module}.child_ancestry_value(attribute_in_database(:#{column}), ancestry_id)
         end
 
         def child_ancestry_before_last_save
           if new_record? || (respond_to?(:previously_new_record?) && previously_new_record?)
             raise Ancestry::AncestryException, I18n.t("ancestry.no_child_for_new_record")
           end
 
-          #{format_module}.child_ancestry_value(attribute_before_last_save(:#{column}), id)
+          #{format_module}.child_ancestry_value(attribute_before_last_save(:#{column}), ancestry_id)
         end
 
         def ancestry_changed?
@@ -123,7 +123,7 @@ def parent_id
         alias parent_id? ancestors?
 
         def root_id
-          has_parent? ? ancestor_ids.first : id
+          has_parent? ? ancestor_ids.first : ancestry_id
         end
 
         def depth
@@ -136,45 +136,45 @@ def is_root?
         alias root? is_root?
 
         def path_ids
-          ancestor_ids + [id]
+          ancestor_ids + [ancestry_id]
         end
 
         def path_ids_before_last_save
-          ancestor_ids_before_last_save + [id]
+          ancestor_ids_before_last_save + [ancestry_id]
         end
 
         def path_ids_in_database
-          ancestor_ids_in_database + [id]
+          ancestor_ids_in_database + [ancestry_id]
         end
 
         # Predicates
 
         def ancestor_of?(node)
-          node.ancestor_ids.include?(id)
+          node.ancestor_ids.include?(ancestry_id)
         end
 
         def parent_of?(node)
-          id == node.parent_id
+          ancestry_id == node.parent_id
         end
 
         def child_of?(node)
-          parent_id == node.id
+          parent_id == node.ancestry_id
         end
 
         def root_of?(node)
-          id == node.root_id
+          ancestry_id == node.root_id
         end
 
         def descendant_of?(node)
-          ancestor_ids.include?(node.id)
+          ancestor_ids.include?(node.ancestry_id)
         end
 
         def indirect_of?(node)
-          ancestor_ids[0..-2].include?(node.id)
+          ancestor_ids[0..-2].include?(node.ancestry_id)
         end
 
         def in_subtree_of?(node)
-          id == node.id || descendant_of?(node)
+          ancestry_id == node.ancestry_id || descendant_of?(node)
         end
 
         # Scope-delegating navigation methods
@@ -238,7 +238,7 @@ def leaf_ids(depth_options = {})
         end
 
         def siblings
-          self.class.ancestry_base_class.siblings_of(self).where.not(:#{pk} => id)
+          self.class.ancestry_base_class.siblings_of(self).where.not(:#{pk} => ancestry_id)
         end
 
         def sibling_ids