ancestry 4.2.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82bcd1895093ab9b569806ef05fc307fc2ca9ab53ffeb09199bd66fe3672ecfb
-  data.tar.gz: fe7d0d356641658be2953309c27dd28a42e81ed569690cc5e26b2721b1aa6a37
+  metadata.gz: 19e9d786304fcb6d41f135572b0475167d378bafd24f1e084bab1aa87b759dc5
+  data.tar.gz: 34d82c19057c6036e0e05080fa84569cf4343b8a2ebb19f718ea5093e398e4bf
 SHA512:
-  metadata.gz: f33384a1114d865662be0133c532249be0e7ea438a66e469947b3aaba3172378ae50309e02c4f219c1f161281a9e060bff6087a496850c26351fd83348627e79
-  data.tar.gz: 2a6cb3fb28f6c9a8228b522c590c2125c4e31056a97ac6a6cda96ea4152725fe89e375b59c894091ebcd3d5be36ad18b348c6691211bc6bea2b0a49502c9f423
+  metadata.gz: e954ca39aabe660070650e2917f5efdd115a10da25c8d7874b565278d2ba6b69b2c17b3bc6138452fec2823675f6ff7c767b10d33c999ac568133736c08fbccf
+  data.tar.gz: 4b3561088670192638cfd7016936d80cb547cf6b1f8f642af62800876fe49de22373ff6f2802442d5f5330668bca487b0b232491eb28d24090fcc6a531f6e45a

data/CHANGELOG.md

@@ -3,6 +3,18 @@
 Doing our best at supporting [SemVer](http://semver.org/) with
 a nice looking [Changelog](http://keepachangelog.com).
 
+## Version [4.3.0] <sub><sup>2023-03-09</sub></sup>
+
+* Fix: materialized_path2 strategy [#597](https://github.com/stefankroes/ancestry/pull/597) (thx @kshnurov)
+* Fix: descendants ancestry is now updated in after_update callbacks [#589](https://github.com/stefankroes/ancestry/pull/589) (thx @kshnurov)
+* Document updated grammar [#594](https://github.com/stefankroes/ancestry/pull/594) (thx @omarr-gamal)
+* Documented `update_strategy` [#588](https://github.com/stefankroes/ancestry/pull/588) (thx @victorfgs)
+* Fix: fixed has_parent? when non-default primary id [#585](https://github.com/stefankroes/ancestry/pull/585) (thx @Zhong-z)
+* Documented column collation and testing [#601](https://github.com/stefankroes/ancestry/pull/601) [#607](https://github.com/stefankroes/ancestry/pull/607) (thx @kshnurov)
+* Added initializer with default_ancestry_format [#612](https://github.com/stefankroes/ancestry/pull/612) [#613](https://github.com/stefankroes/ancestry/pull/613)
+* ruby 3.2 support [#596](https://github.com/stefankroes/ancestry/pull/596) (thx @petergoldstein)
+* arrange is 3x faster and uses 20-30x less memory [#415](https://github.com/stefankroes/ancestry/pull/415)
+
 ## Version [4.2.0] <sub><sup>2022-06-09</sub></sup>
 
 * added strategy: materialized_path2 [#571](https://github.com/stefankroes/ancestry/pull/571)
@@ -270,7 +282,8 @@ Missed 2 commits (which are feature adds)
 * Validations
 
 
-[HEAD]: https://github.com/stefankroes/ancestry/compare/v4.2.0...HEAD
+[HEAD]: https://github.com/stefankroes/ancestry/compare/v4.3.0...HEAD
+[4.3.0]: https://github.com/stefankroes/ancestry/compare/v4.2.0...v4.3.0
 [4.2.0]: https://github.com/stefankroes/ancestry/compare/v4.1.0...v4.2.0
 [4.1.0]: https://github.com/stefankroes/ancestry/compare/v4.0.0...v4.1.0
 [4.0.0]: https://github.com/stefankroes/ancestry/compare/v3.2.1...v4.0.0

data/README.md

@@ -2,29 +2,58 @@
 
 # Ancestry
 
-Ancestry is a gem that allows the records of a Ruby on Rails
-ActiveRecord model to be organised as a tree structure (or hierarchy). It employs
-the materialised path pattern and exposes all the standard tree structure
-relations (ancestors, parent, root, children, siblings, descendants), allowing all
-of them to be fetched in a single SQL query. Additional features include STI
-support, scopes, depth caching, depth constraints, easy migration from older
-gems, integrity checking, integrity restoration, arrangement of
-(sub)trees into hashes, and various strategies for dealing with orphaned
-records.
-
-NOTE:
+## Overview
+
+Ancestry is a gem that allows rails ActiveRecord models to be organized as
+a tree structure (or hierarchy). It employs the materialized path pattern
+which allows operations to be performed efficiently.
+
+# Features
+
+There are a few common ways of storing hierarchical data in a database:
+materialized path, closure tree table, adjacency lists, nested sets, and adjacency list with recursive queries.
+
+## Features from Materialized Path
+
+- Store hierarchy in an easy to understand format. (e.g.: `/1/2/3/`)
+- Store hierarchy in the original table with no additional tables.
+- Single SQL queries for relations (`ancestors`, `parent`, `root`, `children`, `siblings`, `descendants`)
+- Single query for creating records.
+- Moving/deleting nodes only affect child nodes (rather than updating all nodes in the tree)
+
+## Features from Ancestry gem Implementation
+
+- relations are implemented as `scopes`
+- `STI` support
+- Arrangement of subtrees into hashes
+- Multiple strategies for querying materialized_path
+- Multiple strategies for dealing with orphaned records
+- depth caching
+- depth constraints
+- counter caches
+- Multiple strategies for moving nodes
+- Easy migration from `parent_id` based gems
+- Integrity checking
+- Integrity restoration
+- Most queries use indexes on `id` or `ancestry` column. (e.g.: `LIKE '#{ancestry}/%'`)
+
+Since a Btree index has a limitaton of 2704 characters for the `ancestry` column,
+the maximum depth of an ancestry tree is 900 items at most. If ids are 4 digits long,
+then the max depth is 540 items.
+
+When using `STI` all classes are returned from the scopes unless you specify otherwise using `where(:type => "ChildClass")`.
+
+## Supported Rails versions
 
 - Ancestry 2.x supports Rails 4.1 and earlier
 - Ancestry 3.x supports Rails 5.0 and 4.2
-- Ancestry 4.0 only supports rails 5.0 and higher
+- Ancestry 4.x only supports rails 5.2 and higher
 
 # Installation
 
-Follow these simple steps to apply Ancestry to any ActiveRecord model:
+Follow these steps to apply Ancestry to any ActiveRecord model:
 
-## Install
-
-* Add to Gemfile:
+## Add to Gemfile
 
 ```ruby
 # Gemfile
@@ -32,73 +61,68 @@ Follow these simple steps to apply Ancestry to any ActiveRecord model:
 gem 'ancestry'
 ```
 
-* Install required gems:
-
 ```bash
 $ bundle install
 ```
 
-
 ## Add ancestry column to your table
-* Create migration:
 
 ```bash
-$ rails g migration add_ancestry_to_[table] ancestry:string:index
-# or use different column name of your choosing. e.g. name:
-# rails g migration add_name_to_[people] name:string:index
+$ rails g migration add_[ancestry]_to_[table] ancestry:string:index
+```
+
+```ruby
+class AddAncestryToTable < ActiveRecord::Migration[6.1]
+  def change
+    change_table(:table) do |t|
+      # postgrel
+      t.string "ancestry", collation: 'C', null: false
+      t.index "ancestry"
+      # mysql
+      t.string "ancestry", collation: 'utf8mb4_bin', null: false
+      t.index "ancestry"
+    end
+  end
+end
 ```
 
-*   Migrate your database:
+There are additional options for the columns in [Ancestry Database Columnl](#ancestry-database-column) and
+an explanation for `opclass` and `collation`.
 
 ```bash
 $ rake db:migrate
 ```
 
-Depending upon your comfort with databases, you may want to create the column
-with `C` or `POSIX` encoding. This is a more primitive encoding and just compares
-bytes. Since this column will just contains numbers and slashes, it works much
-better. It also works better for the uuid case as well.
-
-Alternatively, if you create a [`text_pattern_ops`](https://www.postgresql.org/docs/current/indexes-opclass.html) index for your postgresql column, subtree selection will use an efficient index for you regardless of whether you created the column with `POSIX` encoding.
+## Configure ancestry defaults
 
-If you opt out of this, and are trying to run tests on postgres, you may need to
-set the environment variable `COLLATE_SYMBOLS=false`. Sorry to say that a discussion
-on this topic is out of scope. The important take away is postgres sort order is
-not consistent across operating systems but other databases do not have this same
-issue.
+```ruby
+# config/initializers/ancestry.rb
 
-NOTE: A Btree index (as is recommended) has a limitaton of 2704 characters for the ancestry column. This means you can't have an tree with a depth that is too great (~> 900 items at most).
+# use the newer format
+Ancestry.default_ancestry_format = :materialized_path2
+# Ancestry.default_update_strategy = :sql
+```
 
 ## Add ancestry to your model
-* Add to app/models/[model.rb]:
 
 ```ruby
 # app/models/[model.rb]
 
 class [Model] < ActiveRecord::Base
-   has_ancestry # or alternatively as below:
-   # has_ancestry ancestry_column: :name ## if you've used a different column name
+   has_ancestry
 end
 ```
 
 Your model is now a tree!
 
-# Using acts_as_tree instead of has_ancestry
-
-In version 1.2.0, the **acts_as_tree** method was **renamed to has_ancestry**
-in order to allow usage of both the acts_as_tree gem and the ancestry gem in a
-single application. The `acts_as_tree` method will continue to be supported in the future.
-
 # Organising records into a tree
 
-You can use the parent attribute to organise your records into a tree. If you
-have the id of the record you want to use as a parent and don't want to fetch
-it, you can also use parent_id. Like any virtual model attributes, parent and
-parent_id can be set using parent= and parent_id= on a record or by including
-them in the hash passed to new, create, create!, update_attributes and
-update_attributes!. For example:
+You can use `parent_id` and `parent` to add a node into a tree. They can be
+set as attributes or passed into methods like `new`, `create`, and `update`.
 
-`TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')`.
+```ruby
+TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')
+```
 
 Children can be created through the children relation on a node: `node.children.create :name => 'Stinky'`.
 
@@ -127,31 +151,47 @@ The yellow nodes are those returned by the method.
 |`has_siblings?`                |                                                     |                                 |
 |`sibling_of?(node)`            |                                                     |                                 |
 
+When using `STI` all classes are returned from the scopes unless you specify otherwise using `where(:type => "ChildClass")`.
+
 <sup id="fn1">1. [other root records are considered siblings]<a href="#ref1" title="Jump back to footnote 1.">↩</a></sup>
 
-# `has_ancestry` options
+# has_ancestry options
 
-The has_ancestry method supports the following options:
+The `has_ancestry` method supports the following options:
 
-    :ancestry_column       Pass in a symbol to store ancestry in a different column
+    :ancestry_column       Column name to store ancestry
+                           'ancestry' (default)
+    :ancestry_format       Format for ancestry column (see Ancestry Formats section):
+                           :materialized_path (default)     1/2/3, root nodes ancestry=nil
+                           :materialized_path2 (preferred) /1/2/3/, root nodes ancestry=/
     :orphan_strategy       Instruct Ancestry what to do with children of a node that is destroyed:
                            :destroy   All children are destroyed as well (default)
                            :rootify   The children of the destroyed node become root nodes
                            :restrict  An AncestryException is raised if any children exist
                            :adopt     The orphan subtree is added to the parent of the deleted node
                                       If the deleted node is Root, then rootify the orphan subtree
-    :cache_depth           Cache the depth of each node in the 'ancestry_depth' column (default: false)
-                           If you turn depth_caching on for an existing model:
-                           - Migrate: add_column [table], :ancestry_depth, :integer, :default => 0
-                           - Build cache: TreeNode.rebuild_depth_cache!
-    :depth_cache_column    Pass in a symbol to store depth cache in a different column
-    :primary_key_format    Supply a regular expression that matches the format of your primary key
-                           By default, primary keys only match integers ([0-9]+)
-    :touch                 Instruct Ancestry to touch the ancestors of a node when it changes, to
-                           invalidate nested key-based caches. (default: false)
-    :counter_cache         Boolean whether to create counter cache column accessor. 
-                           Default column name is `children_count`. 
-                           Pass symbol to use different column name (default: false)
+    :cache_depth           Cache the depth of each node (See Depth Cache section)
+                           false (default)
+
+    :depth_cache_column    column name to store depth cache
+                           'ancestry_depth' (default)
+    :primary_key_format    regular expression that matches the format of the primary key
+                           '[0-9]+'           (default) integer ids
+                           '[-A-Fa-f0-9]{36}'           UUIDs
+    :touch                 Instruct Ancestry to touch the ancestors of a node when it changes
+                           false (default) don't invalide nested key-based caches
+    :counter_cache         Whether to create counter cache column accessor.
+                           false (default) don't store a counter cache
+                           true            store counter cache in `children_count`.
+                           String          name of column to store counter cache.
+    :update_strategy       Choose the strategy to update descendants nodes
+                           :ruby (default) All descendants are updated using the ruby algorithm.
+                                           This triggers update callbacks for each descendant node
+                           :sql            All descendants are updated using a single SQL statement.
+                                           This strategy does not trigger update callbacks for the descendants.
+                                           This strategy is available only for PostgreSql implementations
+
+Legacy configuration using `acts_as_tree` is still available. Ancestry defers to `acts_as_tree` if that gem is installed.
 
 # (Named) Scopes
 
@@ -183,7 +223,7 @@ It is possible thanks to some convenient rails magic to create nodes through the
 
 # Selecting nodes by depth
 
-With depth caching enabled (see has_ancestry options), an additional five named
+With depth caching enabled (see [has_ancestry options](#has_ancestry-options)), an additional five named
 scopes can be used to select nodes by depth:
 
     before_depth(depth)     Return nodes that are less deep than depth (node.depth < depth)
@@ -203,16 +243,13 @@ can be fetched directly from the ancestry column without needing a query. Use
     node.descendants(:from_depth => 2, :to_depth => 4)
     node.subtree.from_depth(10).to_depth(12)
 
-# STI support
-
-To use with STI: create a STI inheritance hierarchy and build a tree from the different
-classes/models. All Ancestry relations that were described above will return nodes of any model type. If
-you do only want nodes of a specific subclass, a type condition is required.
-
 # Arrangement
 
+## `arrange`
+
 A subtree can be arranged into nested hashes for easy navigation after database retrieval.
-`TreeNode.arrange` could, for instance, return:
+
+The resulting format is a hash of hashes
 
 ```ruby
 {
@@ -225,24 +262,22 @@ A subtree can be arranged into nested hashes for easy navigation after database
 }
 ```
 
-The `arrange` method can work on a scoped class (`TreeNode.find_by(:name => 'Crunchy').subtree.arrange`),
-and can take ActiveRecord find options. If you want ordered hashes, pass the order to the method instead of
-the scope as follows:
-
-`TreeNode.find_by(:name => 'Crunchy').subtree.arrange(:order => :name)`.
+There are many ways to call `arrange`:
 
-The `arrange_serializable` method returns the arranged nodes as a nested array of hashes. Order
-can be passed in the same fashion as to the `arrange` method:
-`TreeNode.arrange_serializable(:order => :name)` The result can easily be serialized to json with `to_json`
-or other formats. You can also supply your own serialization logic with blocks.
-
-Using `ActiveModel` serializers:
+```ruby
+TreeNode.find_by(:name => 'Crunchy').subtree.arrange
+TreeNode.find_by(:name => 'Crunchy').subtree.arrange(:order => :name)
+```
 
-`TreeNode.arrange_serializable { |parent, children| MySerializer.new(parent, children: children) }`.
+## `arrange_serializable`
 
-Or plain hashes:
+If a hash of arrays is preferred, `arrange_serializable` can be used. The results
+work well with `to_json`.
 
 ```ruby
+TreeNode.arrange_serializable(:order => :name)
+# use an active model serializer
+TreeNode.arrange_serializable { |parent, children| MySerializer.new(parent, children: children) }
 TreeNode.arrange_serializable do |parent, children|
   {
      my_id: parent.id,
@@ -254,54 +289,232 @@ end
 # Sorting
 
 The `sort_by_ancestry` class method: `TreeNode.sort_by_ancestry(array_of_nodes)` can be used
-to sort an array of nodes as if traversing in preorder. (Note that since materialised path
+to sort an array of nodes as if traversing in preorder. (Note that since materialized path
 trees do not support ordering within a rank, the order of siblings is
 dependant upon their original array order.)
 
+
+# Ancestry Database Column
+
+## Collation Indexes
+
+Sorry, using collation or index operator classes makes this a little complicated. The
+root of the issue is that in order to use indexes, the ancestry column needs to
+compare strings using ascii rules.
+
+It is well known that `LIKE '/1/2/%'` will use an index because the wildchard (i.e.: `%`)
+is on the right hand side of the `LIKE`. While that is true for ascii strings, it is not
+necessarily true for unicode. Since ancestry only uses ascii characters, telling the database
+this constraint will optimize the `LIKE` statemens.
+
+## Collation Sorting
+
+As of 2018, standard unicode collation ignores punctuation for sorting. This ignores
+the ancestry delimiter (i.e.: `/`) and returns data in the wrong order. The exception
+being Postgres on a mac, which ignores proper unicode collation and instead uses
+ISO-8859-1 ordering (read: ascii sorting).
+
+Using the proper column storage and indexes will ensure that data is returned from the
+database in the correct order. It will also ensure that developers on Mac or Windows will
+get the same results as linux production servers, if that is your setup.
+
+## Migrating Collation
+
+If you are reading this and want to alter your table to add collation to an existing column,
+remember to drop existing indexes on the `ancestry` column and recreate them.
+
+## ancestry_format materialized_path and nulls
+
+If you are using the legacy `ancestry_format` of `:materialized_path`, then you need to the
+collum to allow `nulls`. Change the column create accordingly: `null: true`.
+
+Chances are, you can ignore this section as you most likely want to use `:materialized_path2`.
+
+## Postgres Storage Options
+
+### ascii field collation
+
+The currently suggested way to create a postgres field is using `'C'` collation:
+
+```ruby
+t.string "ancestry", collation: 'C', null: false
+t.index "ancestry"
+```
+
+### ascii index
+
+If you need to use a standard collation (e.g.: `en_US`), then use an ascii index:
+
+```ruby
+t.string "ancestry", null: false
+t.index  "ancestry", opclass: :varchar_pattern_ops
+```
+
+This option is mostly there for users who have an existing ancestry column and are more
+comfortable tweaking indexes rather than altering the ancestry column.
+
+### binary column
+
+When the column is binary, the database doesn't convert strings using locales.
+Rails will convert the strings and send byte arrays to the database.
+At this time, this option is not suggested. The sql is not as readable, and currently
+this does not support the `:sql` update_strategy.
+
+```ruby
+t.binary "ancestry", limit: 3000, null: false
+t.index  "ancestry"
+```
+You may be able to alter the database to gain some readability:
+
+```SQL
+ALTER DATABASE dbname SET bytea_output to 'escape';
+```
+
+## Mysql Storage options
+
+### ascii field collation
+
+The currently suggested way to create a postgres field is using `'C'` collation:
+
+```ruby
+t.string "ancestry", collation: 'utf8mb4_bin', null: false
+t.index "ancestry"
+```
+
+### binary collation
+
+Collation of `binary` acts much the same way as the `binary` column:
+
+```ruby
+t.string "ancestry", collate: 'binary', limit: 3000, null: false
+t.index  "ancestry"
+```
+
+### binary column
+
+```ruby
+t.binary "ancestry", limit: 3000, null: false
+t.index  "ancestry"
+```
+
+### ascii character set
+
+Mysql supports per column character sets. Using a character set of `ascii` will
+set this up.
+
+```SQL
+ALTER TABLE table
+  ADD COLUMN ancestry VARCHAR(2700) CHARACTER SET ascii;
+```
+
+# Ancestry Formats
+
+You can choose from 2 ancestry formats:
+
+- `:materialized_path` - legacy format (currently the default for backwards compatibility reasons)
+- `:materialized_path2` - newer format. Use this if it is a new column
+
+```
+:materialized_path    1/2/3,  root nodes ancestry=nil
+    descendants SQL: ancestry LIKE '1/2/3/%' OR ancestry = '1/2/3'
+:materialized_path2  /1/2/3/, root nodes ancestry=/
+    descendants SQL: ancestry LIKE '/1/2/3/%'
+```
+
+If you are unsure, choose `:materialized_path2`. It allows a not NULL column,
+faster descenant queries, has one less `OR` statement in the queries, and
+the path can be formed easily in a database query for added benefits.
+
+There is more discussion in [Internals](#internals) or [Migrating ancestry format](#migrate-ancestry-format)
+For migrating from `materialized_path` to `materialized_path2` see [Ancestry Column](#ancestry-column)
+
+## Migrating Ancestry Format
+
+To migrate from `materialized_path` to `materialized_path2`:
+
+```ruby
+klass = YourModel
+# set all child nodes
+klass.where.not(klass.arel_table[klass.ancestry_column].eq(nil)).update_all("#{klass.ancestry_column} = CONCAT('#{klass.ancestry_delimiter}', #{klass.ancestry_column}, '#{klass.ancestry_delimiter}')")
+# set all root nodes
+klass.where(klass.arel_table[klass.ancestry_column].eq(nil)).update_all("#{klass.ancestry_column} = '#{klass.ancestry_root}'")
+
+change_column_null klass.table_name, klass.ancestry_column, false
+```
+
 # Migrating from plugin that uses parent_id column
 
-Most current tree plugins use a parent_id column (has_ancestry,
-awesome_nested_set, better_nested_set, acts_as_nested_set). With Ancestry it is
-easy to migrate from any of these plugins. To do so, use the
-`build_ancestry_from_parent_ids!` method on your ancestry model.
+It should be relatively simple to migrating from a plugin that uses a `parent_id`
+column, (e.g.: `awesome_nested_set`, `better_nested_set`, `acts_as_nested_set`).
 
-<details>
-<summary>Details</summary>
+When running the installation steps, also remove the old gem from your `Gemfile`,
+and remove the old gem's macros from the model.
 
-1.  Add ancestry column to your table
-    *   Create migration: **rails g migration [add_ancestry_to_](table)
-        ancestry:string**
-    *   Add index to migration: **add_index [table], :ancestry** (UP) /
-        **remove_index [table], :ancestry** (DOWN)
-    *   Migrate your database: **rake db:migrate**
+Then populate the `ancestry` column from rails console:
+
+```ruby
+Model.build_ancestry_from_parent_ids!
+# Model.rebuild_depth_cache!
+Model.check_ancestry_integrity!
+```
 
+It is time to run your code. Most tree methods should work fine with ancestry
+and hopefully your tests only require a few minor tweaks to get up and runnnig.
 
-2.  Remove old tree gem and add in Ancestry to Gemfile
-    *   See 'Installation' for more info on installing and configuring gems
+Once you are happy with how your app is running, remove the old `parent_id` column:
 
+```bash
+$ rails g migration remove_parent_id_from_[table]
+```
 
-3.  Change your model
-    *   Remove any macros required by old plugin/gem from
-        `[app/models/](model).rb`
-    *   Add to `[app/models/](model).rb`: `has_ancestry`
+```ruby
+class RemoveParentIdFromToTable < ActiveRecord::Migration[6.1]
+  def change
+    remove_column "table", "parent_id", type: :integer
+  end
+end
+```
 
+```bash
+$ rake db:migrate
+```
 
-4.  Generate ancestry columns
-    *   In rails console: **[model].build_ancestry_from_parent_ids!**
-    *   Make sure it worked ok: **[model].check_ancestry_integrity!**
+# Depth cache
 
+## Depth Cache Migration
 
-5.  Change your code
-    *   Most tree calls will probably work fine with ancestry
-    *   Others must be changed or proxied
-    *   Check if all your data is intact and all tests pass
+To add depth_caching to an existing model:
 
+## Add column
 
-6.  Drop parent_id column:
-    *   Create migration: `rails g migration [remove_parent_id_from_](table)`
-    *   Add to migration: `remove_column [table], :parent_id`
-    *   Migrate your database: `rake db:migrate`
-</details>
+```ruby
+class AddDepthCachToTable < ActiveRecord::Migration[6.1]
+  def change
+    change_table(:table) do |t|
+      t.integer "ancestry_depth", default: 0
+    end
+  end
+end
+```
+
+## Add ancestry to your model
+
+```ruby
+# app/models/[model.rb]
+
+class [Model] < ActiveRecord::Base
+   has_ancestry depth_cache: true
+end
+```
+
+## Update existing values
+
+Add a custom script or run from rails console.
+Some use migrations, but that can make the migration suite fragile. The command of interest is:
+
+```ruby
+Model.rebuild_depth_cache!
+```
 
 # Running Tests
 
@@ -317,26 +530,6 @@ appraisal rake test
 appraisal sqlite3-ar-50 rake test
 ```
 
-# Internals
-
-Ancestry stores a path from the root to the parent for every node.
-This is a variation on the materialised path database pattern.
-It allows Ancestry to fetch any relation (siblings,
-descendants, etc.) in a single SQL query without the complicated algorithms
-and incomprehensibility associated with left and right values. Additionally,
-any inserts, deletes and updates only affect nodes within the affected node's
-own subtree.
-
-In the example above, the `ancestry` column is created as a `string`. This puts a
-limitation on the depth of the tree of about 40 or 50 levels. To increase the
-maximum depth of the tree, increase the size of the `string` or use `text` to
-remove the limitation entirely. Changing it to a text will however decrease
-performance because an index cannot be put on the column in that case.
-
-The materialised path pattern requires Ancestry to use a 'like' condition in
-order to fetch descendants. The wild character (`%`) is on the right of the
-query, so indexes should be used.
-
 # Contributing and license
 
 Question? Bug report? Faulty/incomplete documentation? Feature request? Please

data/lib/ancestry/array_pattern_validator.rb

@@ -0,0 +1,27 @@
+module Ancestry
+  class ArrayPatternValidator < ActiveModel::EachValidator
+    def initialize(options)
+      raise ArgumentError, "Pattern unspecified, Specify using :pattern" unless options[:pattern]
+
+      options[:pattern] = /\A#{options[:pattern].to_s}\Z/ unless options[:pattern].to_s.include?('\A')
+      options[:id] = true unless options.key?(:id)
+      options[:integer] = true unless options.key?(:integer)
+
+      super
+    end
+
+    def validate_each(record, attribute, value)
+      if options[:id] && value.include?(record.id)
+        record.errors.add(attribute, I18n.t("ancestry.exclude_self", {:class_name => self.class.name.humanize}))
+      end
+
+      if value.any? { |v| v.to_s !~ options[:pattern] }
+        record.errors.add(attribute, "illegal characters")
+      end
+
+      if options[:integer] && value.any? { |v| v < 1 }
+        record.errors.add(attribute, "non positive ancestor id")
+      end
+    end
+  end
+end