sparkfly-foreigner 0.5.4

data/.gitignore

@@ -0,0 +1,3 @@
+*.swp
+*gemspec
+pkg/*

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2010 David Wilkie
+
+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.textile

@@ -0,0 +1,105 @@
+h1. Sparkfly Foreigner
+
+sparkfly-foreigner is a fork of "Matt Higgins Foreigner":http://github.com/matthuhiggins/foreigner/ and the "dwilkie-foreigner":http://github.com/dwilkie/foreigner
+
+Sparkfly requires an enterprise-ready Rails environment, which means we need solid PostgreSQL support and referential integrity.
+Further, all of our plugins must be thoroughly tested. To make sure that PostgreSQL support is where we want it to be, the work
+done by Matt Higgins and D. Wilkie were forked and all the tests were converted to use rspec. Dependency on plugin_test_helper
+was taken out. 
+
+h2. Test Coverage
+
+These tests were created and tested against our target platform, Rails 2.3.5. Support for Rails 3 will come in the future
+when we actually move our platform to Rails 3. The PostgreSQL 8.3 has the best coverage.
+
+PostgreSQL (tested against 8.3.9)
+ - "Schema" tests: do the table migrations actually add referential integrity?
+ - "Schema Extractor" tests: does the foreign_key() method extract out the foreign key from information_schema? 
+ - "Semantics" tests: do the add/drop constraints emit proper SQL?
+
+MySQL (tested against 5.0.90 / Gentoo mysql-5.0.90-r2 hardened x86_64)
+ - "Schema" tests: do the table migrations actually add referential integrity?
+ - "Schema Extractor" tests: does the foreign_key() method extract out the foreign key from information_schema? 
+ - "Semantics" tests: do the add/drop constraints emit proper SQL?
+
+SQLite3 (tested against 3.6.22 in-memory only)
+ - "Semantics" tests: do the add/drop constraints emit proper SQL?
+
+Schema Dumper
+ - Are we emitting the correct schema.rb syntax for adding foreign key constraints?
+
+TODO:
+ - CHECK Constraints (PostgreSQL-only)
+ - CHECK Constraints implemented as triggers for MySQL. This is unlikely to be supported since we don't plan to deploy to MySQL
+
+h2. Usage 
+
+To specify a different column name you can do the following:
+<pre>
+  create_table :comments do |t|
+    t.integer :article_id, :null => false
+    t.foreign_key :post, :column => :article_id
+  end
+</pre>
+
+To specify dependencies (nullify or delete) you can do the following:
+<pre>
+  create_table :comments do |t|
+    t.references :post, :foreign_key => {:dependent => :delete}, :null => false
+  end
+</pre>
+
+Here's another example using a different column name and the dependent option
+<pre>
+  create_table :comments do |t|
+    t.integer :article_id, :null => false
+    t.foreign_key :post, :column => :article_id, :dependent => :nullify
+  end
+</pre>
+
+To specify a reference with a foreign key constraint using Rails convention:
+<pre>
+  create_table :comments do |t|
+    t.references :post, :foreign_key => true, :null => false
+  end
+</pre>
+
+Read the specs for more example usage.
+
+h2. schema.rb
+
+All of the constrants are updated in schema.rb when you either:
+<pre>
+  rake db:migrate
+  rake db:schema:dump
+</pre>
+This allows you to see the state of your migratons and
+take advantage of using <pre>rake db:schema:load</pre>
+
+h2. Installation
+
+h3. Rails 3
+
+- Have not tested any of these changes against Rails 3.
+- See the matthuhiggins-foreigner or dwilkie-foreigner if you want a Foreigner that plays nice with Rails 3. 
+
+h3. Rails 2.3.5
+
+Add the following to environment.rb:
+<pre>config.gem "sparkfly-foreigner", :lib => "foreigner"</pre>
+Then run:
+<pre>sudo rake gems:install</pre>
+
+h2. Testing
+
+You will need rspec and possibly rspec-rails. Run "rake spec" to run all the spec. Make sure
+that all of the PostgreSQL and MySQL databases defined in spec/spec_helper.rb are created
+before you run those tests.
+
+h2. Copyrights
+
+Copyright (c) 2010 Ho-Sheng Hsiao, released under the MIT license
+
+Modified from code written by David Wilkie and Matt Higgins. See http://github.com/sparkfly/foreigner for details on
+what got changed from what.
+

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc 'Run the specs'
+Spec::Rake::SpecTask.new(:spec) do |t|
+    t.spec_opts = ['--colour --format progress --loadby mtime --reverse']
+      t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+desc 'Generate documentation for the foreigner plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Foreigner'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "sparkfly-foreigner"
+    gemspec.summary = "Foreign keys for Rails migrations for PostgreSQL, MySQL and Sqlite3. Based on dwilkie-foreigner"
+    gemspec.description = "Allows you to add foreign keys to your migrations and enforce them"
+    gemspec.email = "hosh@sparkfly.com"
+    gemspec.homepage = "http://github.com/hosh/foreigner"
+    gemspec.authors = ["Ho-Sheng Hsiao"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.5.4

data/lib/foreigner.rb

@@ -0,0 +1,58 @@
+require 'foreigner/connection_adapters/abstract/schema_statements'
+require 'foreigner/connection_adapters/abstract/schema_definitions'
+require 'foreigner/semantics/sql_2003'
+require 'foreigner/schema_dumper'
+
+module Foreigner
+  mattr_accessor :adapters
+  self.adapters = {}
+
+  class << self
+    def register(adapter_name, file_name)
+      adapters[adapter_name] = file_name
+    end
+  
+    def load_adapter!
+      if adapters.key?(configured_adapter)
+        require adapters[configured_adapter]
+      end
+    end
+    
+    def configured_adapter
+      ActiveRecord::Base.connection.adapter_name.downcase
+    end
+    
+    def on_load(&block)
+      if defined?(Rails) && Rails.version >= '3.0'
+        ActiveSupport.on_load :active_record do
+          unless ActiveRecord::Base.connected?
+            ActiveRecord::Base.configurations = Rails.application.config.database_configuration
+            ActiveRecord::Base.establish_connection
+          end
+          block.call
+        end
+      else
+        yield
+      end
+    end
+  end
+end
+
+Foreigner.register 'mysql', 'foreigner/connection_adapters/mysql_adapter'
+Foreigner.register 'sqlite3', 'foreigner/connection_adapters/sqlite3_adapter'
+Foreigner.register 'postgresql', 'foreigner/connection_adapters/postgresql_adapter'
+
+Foreigner.on_load do
+  module ActiveRecord
+    module ConnectionAdapters
+      include Foreigner::ConnectionAdapters::SchemaStatements
+      include Foreigner::ConnectionAdapters::SchemaDefinitions
+    end
+
+    SchemaDumper.class_eval do
+      include Foreigner::SchemaDumper
+    end
+  end
+  
+  Foreigner.load_adapter! if defined?(Rails) # Audo-load if within Rails
+end

data/lib/foreigner/connection_adapters/abstract/schema_definitions.rb

@@ -0,0 +1,154 @@
+module Foreigner
+  module ConnectionAdapters
+    class ForeignKeyDefinition < Struct.new(:from_table, :to_table, :options) #:nodoc:
+    end
+
+    module SchemaDefinitions
+      def self.included(base)
+        base::TableDefinition.class_eval do
+          include Foreigner::ConnectionAdapters::TableDefinition
+        end
+
+        base::Table.class_eval do
+          include Foreigner::ConnectionAdapters::Table
+        end
+      end
+    end
+
+    module TableDefinition
+      class ForeignKey < Struct.new(:base, :to_table, :options)
+
+        def to_sql
+          base.foreign_key_definition(to_table, options)
+        end
+        alias to_s :to_sql
+      end
+
+      def self.included(base)
+        base.class_eval do
+          include InstanceMethods
+          alias_method_chain :references, :foreign_keys
+          alias_method_chain :to_sql, :foreign_keys
+        end
+      end
+
+      module InstanceMethods
+        # Adds a :foreign_key option to TableDefinition.references.
+        # If :foreign_key is true, a foreign key constraint is added to the table.
+        # You can also specify a hash, which is passed as foreign key options.
+        #
+        # ===== Examples
+        # ====== Add goat_id column and a foreign key to the goats table.
+        #  t.references(:goat, :foreign_key => true)
+        # ====== Add goat_id column and a cascading foreign key to the goats table.
+        #  t.references(:goat, :foreign_key => {:dependent => :delete})
+        #
+        # Note: No foreign key is created if :polymorphic => true is used.
+        def references_with_foreign_keys(*args)
+          options = args.extract_options!
+          fk_options = options.delete(:foreign_key)
+
+          if fk_options && !options[:polymorphic]
+            fk_options = {} if fk_options == true
+            args.each { |to_table| foreign_key(to_table, fk_options) }
+          end
+
+          references_without_foreign_keys(*(args << options))
+        end
+
+        # Defines a foreign key for the table. +to_table+ can be a single Symbol, or
+        # an Array of Symbols.
+        #
+        # ===== Examples
+        # ====== Creating a simple foreign key
+        #  t.foreign_key(:person)
+        # ====== Defining the column
+        #  t.foreign_key(:person, :column => :sender_id)
+        # ====== Specify cascading foreign key
+        #  t.foreign_key(:person, :dependent => :delete)
+        def foreign_key(to_table, options = {})
+          if @base.supports_foreign_keys?
+            to_table = to_table.to_s.pluralize if ActiveRecord::Base.pluralize_table_names
+            foreign_keys << ForeignKey.new(@base, to_table, options)
+          end
+        end
+
+        def to_sql_with_foreign_keys
+          sql = to_sql_without_foreign_keys
+          sql << ', ' << (foreign_keys * ', ') if foreign_keys.present?
+          sql
+        end
+
+        private
+          def foreign_keys
+            @foreign_keys ||= []
+          end
+      end
+    end
+
+    module Table
+      def self.included(base)
+        base.class_eval do
+          include InstanceMethods
+          alias_method_chain :references, :foreign_keys
+        end
+      end
+
+      module InstanceMethods
+        # Adds a new foreign key to the table. +to_table+ can be a single Symbol, or
+        # an Array of Symbols. See SchemaStatements#add_foreign_key
+        #
+        # ===== Examples
+        # ====== Creating a simple foreign key
+        #  t.foreign_key(:person)
+        # ====== Defining the column
+        #  t.foreign_key(:person, :column => :sender_id)
+        # ====== Creating a named foreign key
+        #  t.foreign_key(:person, :column => :sender_id, :name => 'sender_foreign_key')
+        # ====== Defining the column of the +to_table+.
+        #  t.foreign_key(:person, :column => :sender_id, :primary_key => :person_id)
+        def foreign_key(to_table, options = {})
+          @base.add_foreign_key(@table_name, to_table, options)
+        end
+
+        # Remove the given foreign key from the table.
+        #
+        # ===== Examples
+        # ====== Remove the suppliers_company_id_fk in the suppliers table.
+        #   t.remove_foreign_key :companies
+        # ====== Remove the foreign key named accounts_branch_id_fk in the accounts table.
+        #   remove_foreign_key :column => :branch_id
+        # ====== Remove the foreign key named party_foreign_key in the accounts table.
+        #   remove_index :name => :party_foreign_key
+        def remove_foreign_key(options = {})
+          @base.remove_foreign_key(@table_name, options)
+        end
+
+        # Adds a :foreign_key option to TableDefinition.references.
+        # If :foreign_key is true, a foreign key constraint is added to the table.
+        # You can also specify a hash, which is passed as foreign key options.
+        #
+        # ===== Examples
+        # ====== Add goat_id column and a foreign key to the goats table.
+        #  t.references(:goat, :foreign_key => true)
+        # ====== Add goat_id column and a cascading foreign key to the goats table.
+        #  t.references(:goat, :foreign_key => {:dependent => :delete})
+        #
+        # Note: No foreign key is created if :polymorphic => true is used.
+        def references_with_foreign_keys(*args)
+          options = args.extract_options!
+          polymorphic = options[:polymorphic]
+          fk_options = options.delete(:foreign_key)
+
+          references_without_foreign_keys(*(args.dup << options))
+
+          if fk_options && !polymorphic
+            fk_options = {} if fk_options == true
+            args.each { |to_table| foreign_key(to_table, fk_options) }
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/foreigner/connection_adapters/abstract/schema_statements.rb

@@ -0,0 +1,75 @@
+module Foreigner
+  module ConnectionAdapters
+    module SchemaStatements
+      def self.included(base)
+        base::AbstractAdapter.class_eval do
+          include Foreigner::ConnectionAdapters::AbstractAdapter
+        end
+      end
+    end
+    
+    module AbstractAdapter
+      def supports_foreign_keys?
+        false
+      end
+
+      # Adds a new foreign key to the +from_table+, referencing the primary key of +to_table+
+      #
+      # The foreign key will be named after the from and to tables unless you pass
+      # <tt>:name</tt> as an option.
+      #
+      # ===== Examples
+      # ====== Creating a foreign key
+      #  add_foreign_key(:comments, :posts)
+      # generates
+      #  ALTER TABLE `comments` ADD CONSTRAINT
+      #     `comments_post_id_fk` FOREIGN KEY (`post_id`) REFERENCES `posts` (`id`)
+      # 
+      # ====== Creating a named foreign key
+      #  add_foreign_key(:comments, :posts, :name => 'comments_belongs_to_posts')
+      # generates
+      #  ALTER TABLE `comments` ADD CONSTRAINT
+      #     `comments_belongs_to_posts` FOREIGN KEY (`post_id`) REFERENCES `posts` (`id`)
+      # 
+      # ====== Creating a cascading foreign_key on a custom column
+      #  add_foreign_key(:people, :people, :column => 'best_friend_id', :dependent => :nullify)
+      # generates
+      #  ALTER TABLE `people` ADD CONSTRAINT
+      #     `people_best_friend_id_fk` FOREIGN KEY (`best_friend_id`) REFERENCES `people` (`id`)
+      #     ON DELETE SET NULL
+      # 
+      # === Supported options
+      # [:column]
+      #   Specify the column name on the from_table that references the to_table. By default this is guessed
+      #   to be the singular name of the to_table with "_id" suffixed. So a to_table of :posts will use "post_id"
+      #   as the default <tt>:column</tt>.
+      # [:primary_key]
+      #   Specify the column name on the to_table that is referenced by this foreign key. By default this is
+      #   assumed to be "id".
+      # [:name]
+      #   Specify the name of the foreign key constraint. This defaults to use from_table and foreign key column.
+      # [:dependent]
+      #   If set to <tt>:delete</tt>, the associated records in from_table are deleted when records in to_table table are deleted.
+      #   If set to <tt>:nullify</tt>, the foreign key column is set to +NULL+.
+      def add_foreign_key(from_table, to_table, options = {})
+      end
+
+      # Remove the given foreign key from the table.
+      #
+      # ===== Examples
+      # ====== Remove the suppliers_company_id_fk in the suppliers table.
+      #   remove_foreign_key :suppliers, :companies
+      # ====== Remove the foreign key named accounts_branch_id_fk in the accounts table.
+      #   remove_foreign_key :accounts, :column => :branch_id
+      # ====== Remove the foreign key named party_foreign_key in the accounts table.
+      #   remove_foreign_key :accounts, :name => :party_foreign_key
+      def remove_foreign_key(from_table, options)
+      end
+
+      # Return the foreign keys for the schema_dumper
+      def foreign_keys(table_name)
+        []
+      end
+    end
+  end
+end