riscfuture / hierarchy

Use PostgreSQL LTREE type with ActiveRecord

Hierarchy

Use PostgreSQL LTREE columns in ActiveRecord

Author	Tim Morgan
Version	1.0.6 (Nov 27, 2010)
License	Released under the MIT license.

About

The LTREE column type is a PostgreSQL-specific type (available from the ltree extension) for representing hierarchies. It is more efficient than the typical way of accomplishing hierarchical structures in SQL, the parent_id column (or similar).

This gem lets you use an LTREE-utilizing hierarchy in ActiveRecord. Including this gem in your project gets you a module you can include in your models, providing an abundance of methods to help you navigate and manipulate the hierarchy.

Installation

Important Note: This gem requires Ruby 1.9+ and Rails 3.0+.

Firstly, add the gem to your Rails project's Gemfile:

gem 'hierarchy'

Then, run the generator to install the migration:

rails generate hierarchy

Note that this migration must precede any tables using LTREEs, so reorder the migration if you have to.

Usage

Because this gem was hastily extracted from a personal project, it's a little constraining in how it can be used. (Sorry.) Currently the gem requires that your table schema have a column named @path@ of type LTREE, defined as in the example below:

path LTREE NOT NULL DEFAULT ''

Once you've got that column in your model, feel free to include the Hierarchy module:

class Person < ActiveRecord::Base
  include Hierarchy
end

You can now define hierarchy by setting a model's parent, like so:

person.parent = mother #=> Sets the `path` column appropriately

You also have access to a wealth of ways to traverse the hierarchy:

person.children.where(gender: :male)
person.top_level?
Person.treeified #=> returns a traversible tree of all people

For more information on what you can do, see the {Hierarchy} module documentation.

Development

If you wish to develop for Hierarchy, the first thing you will want to do is get specs up and running. This requires a call to bundle install (obviously) and setting up your test database.

As you can see in the spec/spec_helper.rb file, the specs require that a PostgreSQL database named hierarchy_test exist and be owned by a hierarchy_tester user. Unfortunately I haven't written a way to configure this (though patches are welcome). So, the following commands should suffice to get you started:

createuser hierarchy_tester # answer "no" to all prompts
createdb -O hierarchy_tester hierarchy_test

With those steps done you should be able to run rake spec and see the Glorious Green.

hierarchy's Issues

Treeifying different models

Am I right that for now there is no support for making trees of records of different models? Like:
Things.Furniture.Table
Things.Fruits.Apple

Uninitialized constant ActiveSupport::Memoizable on Heroku

Hi!
I can't deploy app to Heroku with gem "hierarchy"
Error "Uninitialized constant ActiveSupport::Memoizable"

   uninitialized constant ActiveSupport::Memoizable
   /tmp/build_b2032c6e-2bcc-43ef-b916-40af31c5dc5c/vendor/bundle/ruby/1.9.1/

gems/hierarchy-1.0.6/lib/hierarchy.rb:30:in block in <module:Hierarchy>' /tmp/build_b2032c6e-2bcc-43ef-b916-40af31c5dc5c/vendor/bundle/ruby/1.9.1/ gems/activesupport-4.0.0/lib/active_support/concern.rb:114:inclass_eval'
/tmp/build_b2032c6e-2bcc-43ef-b916-40af31c5dc5c/vendor/bundle/ruby/1.9.1/
gems/activesupport-4.0.0/lib/active_support/concern.rb:114:in append_features' /tmp/build_b2032c6e-2bcc-43ef-b916-40af31c5dc5c/app/models/son.rb:2:ini
nclude'

Without "include Hierarchy" in model app deploying fine

Dependencies

Hello,

I notice some pretty explicit dependencies in the gemspec, to rails and pg.
AFAIK, both aren't really necessary (ActiveRecord might be though).

This might be a problem as, for example, the pg gem isn't available in jruby (instead, there is activerecord-jdbcpostgresql-adapter).
And, for someone who would be using AR, but not rails, this would inject a really unnecessary dependency.

If you were using travis, you could be testing this gem on all rubies automatically.
If you set it up, I'd be willing to take some time and make it available on jruby.

Deep trees

I haven't found the way for defining trees with more than one level of children. I can have parent (top), and this parent can have children (level 1), but this children can't have their own children, accessible from top parent.