oqgraph_rails 0.0.1

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    oqgraph_rails (0.0.1)
+      activerecord
+      minitest
+      mysql2
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.2.6)
+      activesupport (= 3.2.6)
+      builder (~> 3.0.0)
+    activerecord (3.2.6)
+      activemodel (= 3.2.6)
+      activesupport (= 3.2.6)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.6)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.0)
+    i18n (0.6.0)
+    minitest (3.1.0)
+    multi_json (1.3.6)
+    mysql2 (0.3.11)
+    tzinfo (0.3.33)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  oqgraph_rails!

data/LICENCE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Stuart Coyle
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,243 @@
+# OQGraph Rails
+
+This gem can be used with ActiveRecord to access the features of the OQGraph
+MySQL plugin. 
+
+Please take a look at the Open Query Graph engine page at http://openquery.com/products/graph-engine
+
+This provides fast graph operations on the database. It does a similar thing to the 
+acts_as_graph gem, which does all the graph work on the application server. There are 
+pros and cons of both approaches, It really depends on your needs. Both libraries 
+use the C++ Boost graph library at the bottom layers. OQGraph has expensive 
+insert operations but is very fast at delivering the graph data and finding paths in a single SQL query.
+
+This gem requires the use of MySQL or MariaDB with the OQGraph engine plugin.
+For details of this see: http://openquery.com/products/graph-engine
+
+## Concepts
+
+The term graph we are using here is a mathematical one not a pretty picture (sorry designers). 
+For more see: http://en.wikipedia.org/wiki/Graph_(mathematics) 
+A graph consists of nodes (aka vertices) connected by edges (aka links, paths). 
+In a directed graph an edge has a direction. That is, it has an 'from' node and and a 'to' node.
+When tracing a path on the graph you can only go in the direction of the edge.
+The OQGraph gem operates on directed graphs. To create a non directed graph you have to create two edges,
+one each way between each node.
+
+Edges can be assigned positive floating point values called weights. Weights default to 1.0
+The weights are used in shortest path calculations, a path is shorter if the sum of weights over each edge is smaller.
+
+## What you can do with OQGraph?
+
+Imagine your shiny new social networking app, FarceBook.
+You have lots and lots of users each with several friends. How do you find the friends of friends?
+Or even the friends of friends of friends...right up to the six degrees of separation perhaps?
+
+Well you can do it, with some really slow and nasty SQL queries. Relational databases are good at set
+based queries but no good at graph or tree based queries. The OQGraph engine is good at graph based queries, 
+it enables you in one simple SQL query to find all friends of friends. 
+
+Do this: 
+
+```
+    user.reachable
+```
+
+If you really want to you can rename the reachable method so you can do this in your User model:
+
+```
+    alias :friends, :reachable
+```
+
+Then I can call: 
+
+```
+    user.friends
+```
+
+and I get the whole tree of friends of friends etc...
+             
+Imagine you have a maze to solve. With OQGraph the solution is as simple as: 
+
+```
+start_cell.shortest_path_to(finish_cell)
+```
+
+It's good for representing tree structures, networks, routes between cities etc.
+
+## Usage
+
+Use the generators to create your skeleton node and edge classes.
+  
+```
+  rails g oqgraph
+```
+
+This will create a node and an edge model as well as a migration to
+create the edge model's table.
+
+A node model should look like this:
+
+```
+  class Foo < ActiveRecord::Base
+    include OQGraph::Node
+  end
+```
+
+An edge model should look like this:
+
+```
+  class FooEdge < ActiveRecord::Base
+    include OQGraph::Edge
+  end
+```
+
+The edge model schema should be like this:
+
+```
+    create_table :foo_edges do |t|
+        t.integer :from_id
+        t.integer :to_id
+        t.float   :weight, :limit => 25
+    end
+```
+
+The associations defined on the edge and node model are:
+
+```
+  node_model.outgoing_edges
+  node_model.incoming_edges
+  node_model.outgoing_nodes
+  node_model.incoming_nodes
+  
+  edge_model.to
+  edge_model.from
+```
+
+You should be able also to extend the edge and node models as you wish.
+The gem will automatically create the OQgraph table and the associations to it from your node model.
+
+## Examples of Use
+
+### Creating edges:
+
+```
+ foo.create_edge_to(bar)
+ foo.create_edge_to_and_from(bar)
+```
+
+Edge creation using ActiveRecord associations: 
+
+```
+ foo.outgoing_nodes << bar
+```
+
+or equivalently:
+```
+  bar.incoming_nodes << foo
+```
+
+At the moment you cannot add weights to edges with this style of notation.
+
+Create a edge with weight:
+
+```
+ bar.create_edge_to(baz, 2.0)
+```
+
+Removing a edge:
+
+```
+ foo.remove_edge_to(bar)
+ foo.remove_edge_from(bar)
+```
+
+Note that these calls remove ALL edges to bar from foo
+
+### Examining edges: 
+
+What nodes point to this one?
+Gives us an array of nodes that are connected to this one in the inward (from) direction.
+Includes the node calling the method.
+
+```
+ foo.originating
+ bar.originating?(baz)
+```
+
+What nodes can I reach from this one?
+Gives us an array of nodes that are connected to this one in the outward (to) direction.
+Includes the node calling the method.
+
+```
+ bar.reachable
+ foo.reachable?(baz)
+```
+
+### Path Finding:
+
+```
+  foo.shortest_path_to(baz) 
+  -> [foo, bar,baz]
+``` 
+
+  The shortest path to can take a :method which can either be :dijikstra (the default)
+  or :breadth_first. The breadth first method does not take weights into account.
+  It is faster in some cases.
+
+```
+  foo.shortest_path_to(baz, :method => :breadth_first)
+```
+
+All these methods return the node object with an additional weight field.
+This enables you to query the weights associated with the edges found.
+
+## Behind the Scenes
+
+The OQGraph table will also get created if it does not exist. The OQGraph table is volatile, it holds data in 
+memory only. The table structure is not volatile and gets stored in the db. 
+When your application starts up it will put all the edges into the graph table and update them as
+they are created, deleted or modified. This could slow things down at startup but caching classes in production
+means it does not happen on every request. The graph table is only rewritten now when the DB has been restarted.
+You can use this code to force the graph to be rebuilt:
+  NodeModel.rebuild_graph
+
+### How fast is it?
+I've tested with an application with 10000 nodes and 0 to 9 links from each.
+
+For a node connected to most of the network finding all reachable nodes averages at about 300ms.
+This is strongly dependent on how well connected the graph is.
+
+To find shortest paths between nodes takes about 5 to 10ms per request.
+To find all connected nodes takes about 30 to 50ms. The slow bit is the instatiation of
+the models.
+
+Here's an example request: 
+
+```
+  Processing OqgraphUsersController#show_path (for 127.0.0.1 at 2010-07-21 17:09:59) [GET]
+  Parameters: {"id"=>"223", "other_id"=>"2333"}
+    OqgraphUser Load (0.3ms)   SELECT * FROM `oqgraph_users` WHERE (`oqgraph_users`.`id` = 223) 
+    OqgraphUser Load (0.1ms)   SELECT * FROM `oqgraph_users` WHERE (`oqgraph_users`.`id` = 2333) 
+    OqgraphUser Load (2.2ms)   SELECT oqgraph_users.id,oqgraph_users.first_name,oqgraph_users.last_name, oqgraph_user_oqgraph.weight FROM oqgraph_user_oqgraph     JOIN oqgraph_users ON (linkid=id) WHERE latch = 1 AND origid = 223 AND destid = 2333
+    ORDER BY seq;     
+
+  Rendering oqgraph_users/show_path
+  Completed in 6ms (View: 2, DB: 3) | 200 OK [http://localhost/oqgraph_users/223/path_to/2333]
+```
+
+Of course YMMV.
+
+### Hairy bits, bugs and gotchas
+
+To keep the oqgraph table up to date the edge model copies all of it records in when first instantiated.
+This means that on first startup the app can be slow to respond until the whole graph has been written.
+This should not need to happen again unless the DB is restarted. You can get the MySQL server to update the graph
+by using the --init-file=<SQLfile> option in my.cnf with the appropriate SQL in it.
+
+I've encountered a bug where the oqgraph table occasionally needs to be dropped and rebuilt. It's being tracked down.
+If you are not getting any results from the oqgraph table try dropping it and restarting the app.
+
+I'm working on a way to tell if the oqgraph table is stale other than by the current count of rows. Suggestions would be welcome.
+
+Copyright (c) 2010 - 2012 Stuart Coyle, released under the MIT license

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+

data/lib/generators/oqgraph/oqgraph_generator.rb

@@ -0,0 +1,40 @@
+require 'rails/generators/active_record'
+
+module OQGraph
+  module Generators
+    class OQGraphGenerator < ActiveRecord::Generators::Base
+      include Rails::Generators::ResourceHelpers
+      
+      namespace "oqgraph"
+      source_root File.expand_path("../templates", __FILE__)
+            
+      desc "Generates a model with the given NAME with oqgraph and and edge model called <NAME>Edge" <<
+      "plus a migration file for the edge model."
+
+      def create_edge_model
+         @node_class = file_name.camelize
+         @edge_class = "#{@node_class}Edge"
+         template "graph_edge.rb", File.join('app/models', "#{file_name}_edge.rb")
+       end
+
+       def create_node_model
+         @node_class = file_name.camelize
+         template "graph_node.rb", File.join('app/models', "#{file_name}.rb")
+       end
+
+       def create_edge_table_migration
+         @edge_table_name = @edge_class.pluralize.underscore
+         migration_template "graph_edge_migration.rb", "db/migrate/create_#{@edge_table_name}"
+       end
+
+       def create_initializer
+         template "graph_initializer.rb", File.join("config/initializers/#{file_name}_oqgraph.rb")
+       end
+      
+       def create_oqgraph_migration
+         @oqgraph_table_name = "#{file_name}_oqgraph"
+         migration_template "graph_oqgraph_migration.rb", "db/migrate/create_#{@oqgraph_table_name}"
+       end
+    end
+  end
+end

data/lib/generators/oqgraph/templates/graph_edge.rb

@@ -0,0 +1,4 @@
+class <%= @edge_class %> < ActiveRecord::Base
+  include OQGraph::Edge
+  
+end

data/lib/generators/oqgraph/templates/graph_edge_migration.rb

@@ -0,0 +1,12 @@
+class Create<%= @edge_class.pluralize %> < ActiveRecord::Migration
+  # This migration creates the persistent database for the oqgraph table store.
+  # The edge class will create it's own OQGraph table called: <%= @edge_table_name %>_oqgraph
+  
+  def change
+    create_table :<%= @edge_table_name %> do |t|
+      t.integer :from_id, :null => false
+      t.integer :to_id,   :null => false
+      t.float   :weight, :default => 1.0
+    end
+  end
+end

data/lib/generators/oqgraph/templates/graph_initializer.rb

@@ -0,0 +1,3 @@
+# Sets up the OQGraph in memory table.
+# Copies all the existing nodes to the graph table if the counts seem out.
+#<%= @edge_class %>.update_graph_table

data/lib/generators/oqgraph/templates/graph_node.rb

@@ -0,0 +1,4 @@
+class <%= @node_class %> < ActiveRecord::Base
+  include OQGraph::Node
+  
+end

data/lib/generators/oqgraph/templates/graph_oqgraph_migration.rb

@@ -0,0 +1,21 @@
+class Create<%= @node_class %>Oqgraph < ActiveRecord::Migration
+  
+  def up
+    ActiveRecord::Base.connection.execute <<-EOS
+      CREATE TABLE IF NOT EXISTS <%= @oqgraph_table_name %> (
+          latch   SMALLINT  UNSIGNED NULL,
+          origid  BIGINT    UNSIGNED NULL,
+          destid  BIGINT    UNSIGNED NULL,
+          weight  DOUBLE    NULL,
+          seq     BIGINT    UNSIGNED NULL,
+          linkid  BIGINT    UNSIGNED NULL,
+          KEY (latch, origid, destid) USING HASH,
+          KEY (latch, destid, origid) USING HASH
+        ) ENGINE=OQGRAPH;
+      EOS
+  end
+  
+  def down
+    drop_table "<%= @oqgraph_table_name %>"
+  end
+end

data/lib/oqgraph/edge.rb

@@ -0,0 +1,34 @@
+require 'oqgraph/edge_instance_methods'
+require 'oqgraph/edge_class_methods'
+
+module OQGraph
+  module Edge
+    def self.included base
+      base.instance_eval do  
+        def self.node_class_name
+          self.name.gsub(/Edge$/,'')
+        end
+        
+        def self.node_class
+          node_class_name.constantize 
+        end
+        
+        self.table_name = name.underscore.pluralize
+        
+        after_create  :add_to_graph
+        after_destroy :remove_from_graph
+        after_update  :update_graph
+
+        belongs_to :from, :class_name => node_class_name, :foreign_key => :from_id
+        belongs_to :to,   :class_name => node_class_name, :foreign_key => :to_id
+        
+        attr_accessible :from_id, :to_id, :weight
+        
+        include OQGraph::EdgeInstanceMethods
+        extend OQGraph::EdgeClassMethods
+      end
+    end
+  end
+end
+
+

data/lib/oqgraph/edge_class_methods.rb

@@ -0,0 +1,52 @@
+module OQGraph
+  module EdgeClassMethods
+    
+    ##
+    # Creates the OQGraph table for the edge model.
+    # This table exists in memory only and needs to
+    # be updated on every database restart.
+    def create_graph_table
+      connection.execute <<-EOS
+      CREATE TABLE IF NOT EXISTS #{oqgraph_table_name} (
+          latch   SMALLINT  UNSIGNED NULL,
+          origid  BIGINT    UNSIGNED NULL,
+          destid  BIGINT    UNSIGNED NULL,
+          weight  DOUBLE    NULL,
+          seq     BIGINT    UNSIGNED NULL,
+          linkid  BIGINT    UNSIGNED NULL,
+          KEY (latch, origid, destid) USING HASH,
+          KEY (latch, destid, origid) USING HASH
+        ) ENGINE=OQGRAPH;
+      EOS
+  
+      # if the DB server has restarted then there will be no records in the oqgraph table.
+      update_graph_table
+    end
+    
+    def update_graph_table
+      update_oqgraph unless up_to_date?
+    end
+    
+    def node_table
+      node_class.table_name
+    end
+    
+  private
+    def oqgraph_table_name
+      "#{node_table.singularize}_oqgraph"
+    end
+    
+    def up_to_date?
+      # Really need a better way to do this.
+      self.count == connection.select_value("SELECT COUNT(*) FROM #{oqgraph_table_name}") 
+    end
+  
+    def update_oqgraph
+      connection.execute <<-EOS
+        REPLACE INTO #{oqgraph_table_name} (origid, destid, weight)
+        SELECT from_id, to_id, weight FROM #{table_name} 
+        WHERE from_id IS NOT NULL AND to_id IS NOT NULL
+      EOS
+    end
+  end
+end

data/lib/oqgraph/edge_instance_methods.rb

@@ -0,0 +1,35 @@
+module OQGraph
+  module EdgeInstanceMethods
+  private
+    def add_to_graph
+      connection.execute <<-EOS
+        REPLACE INTO #{oqgraph_table_name} (origid, destid, weight)
+        SELECT #{from_id || 0}, #{to_id || 0}, #{weight || 1.0}
+      EOS
+    end
+  
+    def remove_from_graph
+      if self.class.where(:from_id => from_id, :to_id => to_id).count == 0
+        connection.execute <<-EOS
+          DELETE IGNORE FROM #{oqgraph_table_name} 
+          WHERE origid = #{from_id}
+          AND destid = #{to_id};
+        EOS
+      end
+    end
+  
+    def update_graph
+      connection.execute <<-EOS
+        UPDATE #{oqgraph_table_name} 
+        SET origid = #{from_id}, 
+            destid = #{to_id}, 
+            weight = #{weight} 
+        WHERE origid = #{from_id_was} AND destid = #{to_id_was};
+      EOS
+    end
+    
+    def oqgraph_table_name
+      "#{self.class.node_table.singularize}_oqgraph"
+    end
+  end
+end

data/lib/oqgraph/node.rb

@@ -0,0 +1,102 @@
+module OQGraph
+  module Node
+    def self.included base
+      base.instance_eval do
+        def self.edge_class_name
+          "#{self.name}Edge"
+        end
+        
+        def self.edge_class
+          edge_class_name.constantize
+        end
+        
+        def self.rebuild_graph
+          edge_class.create_graph_table
+        end
+        
+        def oqgraph_table_name
+          "#{table_name.singularize}_oqgraph"
+        end
+        
+        has_many :outgoing_edges, {
+           :class_name => edge_class_name,
+           :foreign_key => :from_id,
+           :include => :to,
+           :dependent => :destroy
+         }
+  
+        has_many :incoming_edges, {
+           :class_name => edge_class_name,
+           :foreign_key => :to_id,
+           :include => :from,
+           :dependent => :destroy
+         }
+  
+        has_many :outgoing_nodes, :through => :outgoing_edges, :source => :to
+        has_many :incoming_nodes, :through => :incoming_edges, :source => :from
+        
+        # Joins the oqgraph edge table. The select * ensures we get the weights.
+        scope :join_oqgraph, select('*').joins("JOIN #{oqgraph_table_name} ON #{oqgraph_table_name}.linkid=id")
+        scope :order_oqgraph, order("#{oqgraph_table_name}.seq")
+        # Latch: 0 = only find direct connections, 1 = use Djikstra algorithm, 2 = use Breadth first algorithm
+        scope :originating,   lambda{|latch, destid|         join_oqgraph.where("#{oqgraph_table_name}.latch = ? AND #{oqgraph_table_name}.destid = ?", latch, destid).order_oqgraph}
+        scope :reachable,     lambda{|latch, origid|         join_oqgraph.where("#{oqgraph_table_name}.latch = ? AND #{oqgraph_table_name}.origid = ?", latch, origid).order_oqgraph}
+        scope :shortest_path, lambda{|latch, origid, destid| join_oqgraph.where("#{oqgraph_table_name}.latch = ? AND #{oqgraph_table_name}.origid = ? AND #{oqgraph_table_name}.destid = ?", latch, origid, destid).order_oqgraph}
+      end
+    end
+    
+    # Creates a one way edge from this node to another with a weight.
+    def create_edge_to(other, weight = 1.0)
+      self.class.edge_class.create!(:from_id => id, :to_id => other.id, :weight => weight)
+    end
+    
+    # +other+ graph node to edge to
+    # +weight+ positive float denoting edge weight
+    # Creates a two way edge between this node and another.
+    def create_edge_to_and_from(other, weight = 1.0)
+      self.class.edge_class.create!(:from_id => id, :to_id => other.id, :weight => weight)
+      self.class.edge_class.create!(:from_id => other.id, :to_id => id, :weight => weight)
+    end
+    
+    # +other+ The target node to find a route to
+    # +options+ A hash of options: Currently the only option is
+    #            :method => :djiskstra or :breadth_first
+    # Returns an array of nodes in order starting with this node and ending in the target
+    # This will be the shortest path from this node to the other.
+    # The :djikstra method takes edge weights into account, the :breadth_first does not.
+    def shortest_path_to(other, options = {:method => :djikstra})
+      latch = options[:method] == :breadth_first ? 2 : 1
+      self.class.shortest_path(latch, id, other.id)
+    end
+    
+    # +other+ The target node to find a route to 
+    # Gives the path weight as a float of the shortest path to the other
+    def path_weight_to(other)
+      shortest_path_to(other,:method => :djikstra).map{|edge| edge.weight.to_f}.sum
+    end
+    
+    # Returns an array of all nodes which can trace to this node
+    def originating
+      self.class.originating(2, id)
+    end
+    
+    def originating_neighbours
+      self.class.originating(0, id)
+    end
+    
+    # true if the other node can reach this node.
+    def originating? other
+      originating.include? other
+    end
+    
+    # Returns all nodes reachable from this node.
+    def reachable
+      self.class.reachable(2, id)
+    end
+    
+    # Returns all nodes reachable from this node.
+    def reachable? other
+      reachable.include? other
+    end
+  end
+end

data/lib/oqgraph_rails/version.rb

@@ -0,0 +1,3 @@
+module OqgraphRails
+  VERSION = "0.0.1"
+end

data/lib/oqgraph_rails.rb

@@ -0,0 +1,2 @@
+require 'oqgraph/edge'
+require 'oqgraph/node'

data/oqgraph_rails.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/oqgraph_rails/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Stuart Coyle"]
+  gem.email         = ["stuart.coyle@gmail.com"]
+  gem.description   = %q{Graph engine interface for active record.}
+  gem.summary       = %q{Enables the use of OpenQuery\'s OQGraph engine with active record. OQGraph is a graph database engine for MySQL.}
+  gem.homepage      = "https://github.com/stuart/oqgraph_rails"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "oqgraph_rails"
+  gem.require_paths = ["lib"]
+  gem.version       = OqgraphRails::VERSION
+  gem.add_runtime_dependency 'mysql2'
+  gem.add_runtime_dependency 'activerecord'
+  gem.add_runtime_dependency 'minitest'
+end

data/test/graph_edge_test.rb

@@ -0,0 +1,64 @@
+require 'test_helper'
+require 'oqgraph_rails'
+
+class TestModel < ActiveRecord::Base
+  include OQGraph::Node
+end
+class TestModelEdge < ActiveRecord::Base
+  include OQGraph::Edge
+end
+
+class GraphEdgeTest < ActiveSupport::TestCase
+  def setup
+    ActiveRecord::Base.establish_connection(
+        :adapter  => "mysql2",
+        :host     => "localhost",
+        :username => "root",
+        :password => "",
+        :database => "test"
+      )
+    
+    ActiveRecord::Base.connection.execute("CREATE TABLE IF NOT EXISTS test_model_edges(id INTEGER DEFAULT NULL AUTO_INCREMENT PRIMARY KEY, from_id INTEGER, to_id INTEGER, weight DOUBLE);")
+    TestModelEdge.create_graph_table
+  end
+  
+  def teardown
+    ActiveRecord::Base.connection.execute("DROP TABLE IF EXISTS test_model_edges;")
+    ActiveRecord::Base.connection.execute("DELETE FROM test_model_oqgraph;")
+  end
+  
+  test "the oqgraph table is created" do
+    assert_includes ActiveRecord::Base.connection.select_values("SHOW TABLES;"), 'test_model_oqgraph'
+  end
+  
+  test "the oqgraph is updated when there are records that need to be added" do
+    test_model_edge = TestModelEdge.create!(:from_id => 1, :to_id => 2, :weight => 1.0)
+    TestModelEdge.create_graph_table
+    assert_equal 1, ActiveRecord::Base.connection.select_value("SELECT count(*) FROM test_model_oqgraph;")
+  end
+  
+  test "adding a new edge to graph" do
+    test_model_edge = TestModelEdge.create!(:from_id => 1, :to_id => 2, :weight => 1.0)
+    assert_equal 1, ActiveRecord::Base.connection.select_value("SELECT count(*) FROM test_model_oqgraph;")
+  end
+  
+  test "removing an edge from the graph" do
+    test_model_edge = TestModelEdge.create!(:from_id => 1, :to_id => 2, :weight => 1.0)
+    test_model_edge.destroy
+    assert_equal 0, ActiveRecord::Base.connection.select_value("SELECT count(*) FROM test_model_oqgraph;")
+  end
+  
+  test "removing an edge does not remove from graph table if other edges with the same nodes exist" do
+    test_model_edge = TestModelEdge.create!(:from_id => 3, :to_id => 4, :weight => 1.0)    
+    test_model_edge_2 = TestModelEdge.create!(:from_id => 3, :to_id => 4, :weight => 1.0)  
+    test_model_edge.destroy
+    assert_equal 1, ActiveRecord::Base.connection.select_value("SELECT count(*) FROM test_model_oqgraph;")
+  end
+  
+  test "updating an edge" do
+    test_model_edge = TestModelEdge.create!(:from_id => 3, :to_id => 4, :weight => 1.0)    
+    test_model_edge = test_model_edge.update_attributes(:from_id => 4, :to_id => 1, :weight => 2.0)
+    assert_equal 1, ActiveRecord::Base.connection.select_value("SELECT count(*) FROM test_model_oqgraph WHERE origid = 4 AND destid = 1 AND weight = 2.0;")
+    assert_equal 0, ActiveRecord::Base.connection.select_value("SELECT count(*) FROM test_model_oqgraph WHERE origid = 3 AND destid = 4 AND weight = 1.0;")
+  end
+end

data/test/graph_node_test.rb

@@ -0,0 +1,215 @@
+require 'test_helper'
+require 'oqgraph_rails'
+
+class TestNode < ActiveRecord::Base
+  include OQGraph::Node
+end
+
+class TestNodeEdge < ActiveRecord::Base
+  include OQGraph::Edge
+end
+
+class GraphNodeTest < ActiveSupport::TestCase
+  def setup
+    ActiveRecord::Base.establish_connection(
+        :adapter  => "mysql2",
+        :host     => "localhost",
+        :username => "root",
+        :password => "",
+        :database => "test"
+      )
+    
+    ActiveRecord::Base.connection.execute("CREATE TABLE IF NOT EXISTS test_nodes(id INTEGER DEFAULT NULL AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255) );")
+    ActiveRecord::Base.connection.execute("CREATE TABLE IF NOT EXISTS test_node_edges(id INTEGER DEFAULT NULL AUTO_INCREMENT PRIMARY KEY, from_id INTEGER, to_id INTEGER, weight DOUBLE);")
+    TestNodeEdge.create_graph_table
+    
+    @test_1 = TestNode.create(:name => 'a')
+    @test_2 = TestNode.create(:name => 'b')
+    @test_3 = TestNode.create(:name => 'c')
+    @test_4 = TestNode.create(:name => 'd')
+    @test_5 = TestNode.create(:name => 'e')
+    @test_6 = TestNode.create(:name => 'f')
+  end
+  
+  def teardown
+    ActiveRecord::Base.connection.execute("DROP TABLE IF EXISTS test_nodes;")
+    ActiveRecord::Base.connection.execute("DROP TABLE IF EXISTS test_node_edges;")
+    ActiveRecord::Base.connection.execute("DELETE FROM test_node_oqgraph;")
+  end
+  
+  test "I can connect two nodes" do
+    @test_1.create_edge_to @test_2
+    assert_equal 1, TestNodeEdge.where(:from_id => @test_1.id, :to_id => @test_2.id, :weight => 1.0).count
+    assert_includes @test_1.outgoing_nodes, @test_2
+  end
+  
+  test "creation of edges by association" do
+    @test_1.outgoing_nodes << @test_2
+    assert_not_nil edge = TestNodeEdge.find(:first, :conditions => {:from_id => @test_1.id, :to_id => @test_2.id})
+  end
+  
+  test "creation of unidirectional edges" do
+    @test_1.create_edge_to_and_from(@test_2)
+    assert_not_nil edge = TestNodeEdge.find(:first, :conditions => {:from_id => @test_1.id, :to_id => @test_2.id, :weight => 1.0})
+    assert_not_nil edge = TestNodeEdge.find(:first, :conditions => {:from_id => @test_2.id, :to_id => @test_1.id, :weight => 1.0}) 
+    assert @test_1.outgoing_nodes.include?(@test_2)
+    assert @test_1.incoming_nodes.include?(@test_2)
+  end
+    
+  test "adding of weights to edges" do
+    @test_1.create_edge_to(@test_2, 2.0)
+    assert_not_nil edge = TestNodeEdge.find(:first, :conditions => {:from_id => @test_1.id, :to_id => @test_2.id})
+    assert edge.weight = 2.0
+  end
+  
+  test "edge model creation creates oqgraph edge" do
+    @test_1.create_edge_to(@test_2, 2.5)
+    oqedge = ActiveRecord::Base.connection.execute("SELECT * FROM test_node_oqgraph WHERE origid=#{@test_1.id} AND destid=#{@test_2.id};")
+    assert_equal [nil,1,2,2.5,nil,nil], oqedge.first                                      
+  end
+  
+  test "edge model deletion removes oqgraph edge" do
+    @test_1.outgoing_nodes << @test_2
+    edge = @test_1.outgoing_edges.find(:first, :conditions => {:to_id => @test_2.id})
+    edge.destroy
+    oqedge = ActiveRecord::Base.connection.execute("SELECT * FROM test_node_oqgraph WHERE origid=#{@test_1.id} AND destid=#{@test_2.id};")
+    assert_equal nil, oqedge.first
+  end
+  
+  test "edge model update updates oqgraph edge" do
+    edge = @test_1.create_edge_to(@test_2, 2.5) 
+    edge.update_attributes(:weight => 3.0)
+    oqedge = ActiveRecord::Base.connection.execute("SELECT * FROM test_node_oqgraph WHERE origid=#{@test_1.id} AND destid=#{@test_2.id};") 
+    assert_equal [nil,1,2,3,nil,nil], oqedge.first
+    edge.update_attributes(:to_id => 3)
+    oqedge = ActiveRecord::Base.connection.execute("SELECT * FROM test_node_oqgraph WHERE origid=#{@test_1.id} AND destid=3;") 
+    assert_equal [nil,1,3,3,nil,nil], oqedge.first
+  end
+  
+  test "getting the shortest path" do
+    #   a -> b -> c -> d
+    @test_1.create_edge_to @test_2
+    @test_2.create_edge_to @test_3
+    @test_3.create_edge_to @test_4
+    assert_equal [@test_1, @test_2, @test_3, @test_4], @test_1.shortest_path_to(@test_4)
+    assert_equal ['a','b','c','d'], @test_1.shortest_path_to(@test_4).map(&:name)
+  end
+  
+  test "complex getting the shortest path" do
+    # 
+    # a -> b -> c -> d
+    #      |      / 
+    #      e-> f 
+    @test_1.create_edge_to @test_2
+    @test_2.create_edge_to @test_3
+    @test_3.create_edge_to @test_4
+    @test_2.create_edge_to @test_5
+    @test_5.create_edge_to @test_6
+    @test_4.create_edge_to @test_6
+    assert_equal [@test_1, @test_2, @test_5, @test_6], @test_1.shortest_path_to(@test_6)
+  end
+  
+   test "shortest path returns the weight" do
+     #   a -- b -- c -- d
+     @test_1.create_edge_to @test_2, 2.0
+     @test_2.create_edge_to @test_3, 1.5
+     @test_3.create_edge_to @test_4, 1.2
+     assert_equal [nil, 2.0 ,1.5, 1.2], @test_1.shortest_path_to(@test_4).map(&:weight)
+   end
+   
+  test "getting the path weight total" do
+    #   a -- b -- c -- d
+     @test_1.create_edge_to @test_2, 2.0
+     @test_2.create_edge_to @test_3, 1.5
+     @test_3.create_edge_to @test_4, 1.2
+     assert_equal 4.7, @test_1.path_weight_to(@test_4)
+  end
+  
+  test "finding the path with breadth first" do
+    @test_1.outgoing_nodes << @test_2
+    @test_2.outgoing_nodes << @test_3
+    @test_3.outgoing_nodes << @test_4
+    assert_equal [@test_1, @test_2, @test_3, @test_4], @test_1.shortest_path_to(@test_4, :method => :breadth_first)
+  end
+  
+  # 1 -> 2 -> 3
+  test "getting originating nodes" do
+    @test_1.create_edge_to @test_2
+    @test_2.create_edge_to @test_3
+    assert_equal [@test_2, @test_1], @test_2.originating
+  end
+  
+  test "getting the reachable nodes" do
+    @test_1.create_edge_to @test_2
+    @test_2.create_edge_to @test_3
+    assert_equal [@test_2, @test_3] , @test_2.reachable
+  end
+  
+  test "testing if the node is originating" do
+    @test_1.create_edge_to @test_2
+    @test_2.create_edge_to @test_3
+    assert @test_2.originating?(@test_1)
+    refute @test_2.originating?(@test_3) 
+  end
+  
+  test "testing if the node is reachable" do
+    @test_1.create_edge_to @test_2
+    @test_2.create_edge_to @test_3
+    assert @test_2.reachable?(@test_3)
+    refute @test_2.reachable?(@test_1)
+  end
+  
+  test "get the incoming nodes" do
+    @test_1.create_edge_to @test_2
+    @test_2.create_edge_to @test_3
+    assert_equal [@test_1], @test_2.incoming_nodes
+  end
+  
+  test "get the outgoing nodes" do
+    @test_1.create_edge_to @test_2
+    @test_2.create_edge_to @test_3
+    assert_equal [@test_3], @test_2.outgoing_nodes
+  end
+   
+  test "duplicate links are ignored" do
+    @test_1.create_edge_to @test_2
+    assert_nothing_raised do
+      @test_1.create_edge_to @test_2
+    end
+  end
+   
+  test "duplicate link error" do
+    ActiveRecord::Base.connection.execute("INSERT INTO test_node_oqgraph (destid, origid, weight) VALUES (99,99,1.0);")   
+    assert_raises ActiveRecord::StatementInvalid do
+      ActiveRecord::Base.connection.execute("INSERT INTO test_node_oqgraph (destid, origid, weight) VALUES (99,99,1.0);")
+    end
+  end
+
+  test "duplicate link error fix" do
+    ActiveRecord::Base.connection.execute("REPLACE INTO test_node_oqgraph (destid, origid, weight) VALUES (99,99,1.0);")   
+    assert_nothing_raised do
+      ActiveRecord::Base.connection.execute("REPLACE INTO test_node_oqgraph (destid, origid, weight) VALUES (99,99,1.0);")
+    end
+  end
+
+  # There's an odd case here where MySQL would raise an error only when using Rails.
+  test "deletion of a nonexistent edge does no raise an error" do
+    edge = @test_1.create_edge_to @test_2
+    ActiveRecord::Base.connection.execute("DELETE FROM test_node_oqgraph WHERE destid = #{edge.to_id} AND origid = #{edge.from_id}")
+    assert_nothing_raised do
+      edge.destroy
+    end
+  end  
+  
+  test "rebuilding of edge graph" do
+    @test_1.create_edge_to @test_2
+    @test_2.create_edge_to @test_3
+    @test_3.create_edge_to @test_4
+    # Simulate the DB restart
+    ActiveRecord::Base.connection.execute("DELETE FROM test_node_oqgraph;")
+    TestNode.rebuild_graph
+   
+    assert_equal [@test_1, @test_2, @test_3, @test_4], @test_1.shortest_path_to(@test_4)
+    assert_equal ['a','b','c','d'], @test_1.shortest_path_to(@test_4).map(&:name)
+  end
+end

data/test/oqgraph_generator_test.rb

@@ -0,0 +1,55 @@
+require 'test_helper'
+require 'generators/oqgraph/oqgraph_generator'
+class OQgraphGeneratorTest < Rails::Generators::TestCase
+  tests OQGraph::Generators::OQGraphGenerator
+  
+  destination File.expand_path("../tmp", __FILE__)
+  setup :prepare_destination
+  
+  test "creates the correct migration file" do
+    run_generator %w(funky)
+    assert_migration 'db/migrate/create_funky_edges', /create_table :funky_edges do/
+  end
+  
+  test "creates the edge model class" do
+    run_generator %w(funky)
+    assert_file 'app/models/funky_edge.rb', /class FunkyEdge < ActiveRecord::Base/
+  end
+  
+  test "created edge model class is parseable ruby" do
+    run_generator %w(funky)
+    assert_nothing_raised do
+      require 'tmp/app/models/funky_edge'
+    end
+  end
+  
+  test "creates the node model class" do
+    run_generator %w(funky)
+    assert_file 'app/models/funky.rb', /class Funky < ActiveRecord::Base/
+  end
+  
+  test "created node model class is parseable ruby" do
+    run_generator %w(funky)
+    assert_nothing_raised do
+      require 'tmp/app/models/funky'
+    end
+  end
+  
+  test "creates the initializer" do
+    run_generator %w(funky)
+    assert_file 'config/initializers/funky_oqgraph.rb', /FunkyEdge.update_graph_table/
+  end
+  
+  test "the initializer is parseable ruby" do
+    run_generator %w(funky)
+    assert_nothing_raised do
+      require 'tmp/config/initializers/funky_oqgraph.rb'
+    end
+  end
+  
+  test "creates the oqgraph table migration" do
+    run_generator %w(funky)
+    assert_migration 'db/migrate/create_funky_oqgraph.rb'
+  end
+  
+end

data/test/performance_test.rb

@@ -0,0 +1,52 @@
+require 'test_helper'
+#require 'active_support/testing/performance'
+
+class TestNode < ActiveRecord::Base
+  include OQGraph::Node
+end
+
+class TestNodeEdge < ActiveRecord::Base
+  include OQGraph::Edge
+end
+
+class PerformanceTest < ActiveSupport::TestCase
+#include ActiveSupport::Testing::Performance
+  def setup
+    ActiveRecord::Base.establish_connection(
+        :adapter  => "mysql2",
+        :host     => "localhost",
+        :username => "root",
+        :password => "",
+        :database => "test"
+      )
+
+    ActiveRecord::Base.connection.execute("CREATE TABLE IF NOT EXISTS test_nodes(id INTEGER DEFAULT NULL AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255) );")
+    ActiveRecord::Base.connection.execute("CREATE TABLE IF NOT EXISTS test_node_edges(id INTEGER DEFAULT NULL AUTO_INCREMENT PRIMARY KEY, from_id INTEGER, to_id INTEGER, weight DOUBLE);")
+    TestNodeEdge.create_graph_table
+    
+    puts "Creating 10000 test nodes"
+    @test_nodes = [1..10000].map{|i| TestNode.create(:name => "node#{i}")}
+  end
+
+  def teardown
+    ActiveRecord::Base.connection.execute("DROP TABLE IF EXISTS test_nodes;")
+    ActiveRecord::Base.connection.execute("DROP TABLE IF EXISTS test_node_edges;")
+    ActiveRecord::Base.connection.execute("DELETE FROM test_node_oqgraph;")
+  end
+
+  test "joining nodes" do
+    @test_nodes.each do |node|
+      
+    end
+  end
+
+  test "finding the shortest path" do
+  end
+
+  test "finding connected nodes" do
+  end
+
+  test "removing connections" do
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,11 @@
+# Configure Rails Envinronment
+ENV["RAILS_ENV"] = "test"
+
+gem 'minitest'
+require 'rails'
+require "rails/test_help"
+
+# For generators
+require 'rails/generators/test_case'
+require 'active_record'
+

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: oqgraph_rails
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Stuart Coyle
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-06-24 00:00:00.000000000 +10:00
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: &2158956720 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2158956720
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: &2158955900 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2158955900
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &2158946220 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2158946220
+description: Graph engine interface for active record.
+email:
+- stuart.coyle@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- LICENCE
+- README.md
+- Rakefile
+- lib/generators/oqgraph/oqgraph_generator.rb
+- lib/generators/oqgraph/templates/graph_edge.rb
+- lib/generators/oqgraph/templates/graph_edge_migration.rb
+- lib/generators/oqgraph/templates/graph_initializer.rb
+- lib/generators/oqgraph/templates/graph_node.rb
+- lib/generators/oqgraph/templates/graph_oqgraph_migration.rb
+- lib/oqgraph/edge.rb
+- lib/oqgraph/edge_class_methods.rb
+- lib/oqgraph/edge_instance_methods.rb
+- lib/oqgraph/node.rb
+- lib/oqgraph_rails.rb
+- lib/oqgraph_rails/version.rb
+- oqgraph_rails.gemspec
+- test/graph_edge_test.rb
+- test/graph_node_test.rb
+- test/oqgraph_generator_test.rb
+- test/performance_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: https://github.com/stuart/oqgraph_rails
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Enables the use of OpenQuery\'s OQGraph engine with active record. OQGraph
+  is a graph database engine for MySQL.
+test_files:
+- test/graph_edge_test.rb
+- test/graph_node_test.rb
+- test/oqgraph_generator_test.rb
+- test/performance_test.rb
+- test/test_helper.rb