Closure Tree

Methods like #rebuild and #find_or_create_by_path are not safe for concurrent execution and can cause data corruption or duplicate nodes. Closure Tree uses with_advisory_lock to ensure correctness across PostgreSQL and MySQL.

Disabling locks: You can disable advisory locks by passing with_advisory_lock: false. Warning: If you disable this and perform multi-threaded writes without an alternative mutex, you will eventually experience data corruption.

Customizing lock names: You can customize the advisory lock name to avoid collisions or to implement multi-tenancy. Supported types:

• Static String: advisory_lock_name: 'custom_lock'
• Proc (1-arity): Receives the model class. advisory_lock_name: ->(model_class) { ... }
• Model Method: Delegates to a class method. advisory_lock_name: :custom_lock_name
• Proc (2-arity): Receives the model class and the instance. This is recommended for scoped/multi-tenant models to ensure each tenant has its own lock.

# Static string
class Tag < ApplicationRecord
  has_closure_tree advisory_lock_name: 'custom_tag_lock'
end

# Dynamic via Proc (1-arity)
class Tag < ApplicationRecord
  has_closure_tree advisory_lock_name: ->(model_class) { "#{Rails.env}_#{model_class.name.underscore}" }
end

# Delegate to model method
class Tag < ApplicationRecord
  has_closure_tree advisory_lock_name: :custom_lock_name

  def self.custom_lock_name
    "tag_lock_#{current_tenant_id}"
  end
end

# Per-instance lock names (2-arity) for multi-tenancy
class Node < ApplicationRecord
  has_closure_tree scope: :company_id,
                   advisory_lock_name: ->(klass, instance) {
                     company = instance&.company_id
                     company ? "ct_#{klass.name}_#{company}" : "ct_#{klass.name}"
                   }
end

You can build a hierarchy using several methods:

• Root nodes: Create a node with a nil parent.
• Children collection: Use .children.create(...) or the << operator on the children association.
• add_child method: Use the add_child method on a parent node.
• Direct parent assignment: Set the parent attribute when creating a new record.

Once created, you can access the lineage using .ancestry_path or fetch a node and all its descendants using .self_and_descendants.

# Create a root node
grandparent = Tag.create(name: 'Grandparent')

# Create children via collection
parent = grandparent.children.create(name: 'Parent')
child2 = Tag.new(name: 'Second Child')
parent.children << child2

# Create children via add_child
child3 = Tag.new(name: 'Third Child')
parent.add_child child3

# Create children via parent assignment
Tag.create(name: 'Fourth Child', parent: parent)

# Accessing data
grandparent.self_and_descendants.collect(&:name)
#=> ["Grandparent", "Parent", "First Child", "Second Child", "Third Child", "Fourth Child"]

child1.ancestry_path
#=> ["Grandparent", "Parent", "First Child"]

When including has_closure_tree in your ActiveRecord model, you can pass an options hash to customize the tree behavior.

Key options include:

• :parent_column_name: The foreign key column for the parent (defaults to "parent_id").
• :hierarchy_class_name: The name of the hierarchy class (defaults to ModelName + "Hierarchy").
• :hierarchy_table_name: The name of the hierarchy table (defaults to model_name_hierarchies).
• :dependent: Defines behavior when a node is destroyed:
  • :nullify (default): Sets parent column to null; children become roots.
  • :adopt: Moves children to the grandparent.
  • :delete_all: Deletes all descendants (skips destroy hooks).
  • :destroy: Destroys all descendants (runs destroy hooks).
  • nil: Does nothing to descendants.
• :name_column: The column used by path-based lookup methods (e.g., find_by_path).
• :order: Sets up deterministic ordering.
• :scope: Restricts root nodes and sibling ordering to specific columns (e.g., scope: :user_id or scope: [:user_id, :group_id]).
• :touch: Cascades touch calls to all children.
• :advisory_lock_timeout_seconds: Sets a timeout for the advisory lock; raises WithAdvisoryLock::FailedToAcquireLock if the timeout is reached.

When using numeric_order: true, root nodes are assigned global order values by default. To prevent performance issues in multi-tree databases or to isolate trees, use the scope option. This ensures that root nodes, sibling reordering, and child reordering are all constrained by the specified column(s).

You can also disable root ordering entirely using dont_order_roots: true, though this will cause prepend_sibling, append_sibling, and roots_and_descendants_preordered to raise a RootOrderingDisabledError.

# Scope by a single column
class Block < ApplicationRecord
  has_closure_tree order: 'sort_order', numeric_order: true, scope: :user_id
end

# Scope by multiple columns
class Block < ApplicationRecord
  has_closure_tree order: 'sort_order', numeric_order: true, scope: [:user_id, :group_id]
end

# Disable root ordering
class Block < ApplicationRecord
  has_closure_tree order: 'sort_order', numeric_order: true, dont_order_roots: true
end