migration_comments 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.idea/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in migration_comments.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,81 @@
+= MigrationComments
+
+Comments for your migrations
+
+Tested on Ruby 1.8.6 using Rails 2.3.x.
+
+== Why?
+
+Migrations are wonderful.  They handle all your schema changes, and in a pinch they can bring
+any database up to speed.  However, database schemas can change rapidly while a project is
+maturing, and it can be difficult to know (or remember) the purpose for each table and field.
+As such, they deserve to be commented.  These comments should be available for display wherever
+those fields are found.
+
+== Solution!
+
+Using MigrationComments, you can simply add comments during your migrations.  Or if you already
+have existing data structures, just add the comments afterwards in a separate migration.  And of
+course you can always modify and delete these comments in later migrations.
+
+So where are these comments used?  Firstly, they will be included in your schema.rb dump which
+is where your IDE (e.g. RubyMine) should be learning about your model structure.  This means that
+they'll be available at any point in your project.  Additionally, if you are using the 'annotate'
+gem, these comments will be added to the annotations that are generated within your model.rb
+file.
+
+== Examples
+
+Want to add a comment to an existing structure...
+
+  self.up
+    add_table_comment :table_name, "A table comment"
+    comment_table :table_name, "A table comment"                      # does the same thing
+
+    add_column_comment :table_name, :column_name, "A column comment"
+    comment_column  :table_name, :column_name, "A column comment"     # does the same thing
+  end
+
+Or you can use the change_table macro...
+
+  self.up
+    change_table :table_name do |t|
+      t.comment "A table comment"
+      t.change_comment :column_name, "A column comment"
+    end
+  end
+
+Creating a new table?
+
+  self.up
+    create_table :table_name, :comment => "A table comment" do |t|
+      t.string :column_name, :comment => "A column comment"
+    end
+  end
+
+You can also remove comments...
+
+  self.up
+    remove_table_comment :table_name
+    remove_column_comment :table_name, :column_name
+  end
+
+Or you can combine these commands while modifying a table...
+
+  self.up
+    change_table :existing_table do |t|
+      t.comment nil                                       # remove an existing table comment
+      t.string :new_column, :comment => "a new column"    # add a new column with a comment
+      t.change_comment :existing_column, nil              # remove a comment on an existing column
+      t.integer :another_existing_column, :comment => nil # remove a comment on an existing column while modifying the column type
+      t.boolean :column_with_comment                      # modify an existing column without altering the comment
+    end
+  end
+
+
+== Requirements
+
+You must be using a DBMS that supports COMMENTing (currently only PostgreSQL and MySQL).
+
+If this isn't an option for you, check out the 'schema_comments' gem:
+  https://github.com/akm/schema_comments

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/migration_comments/active_record/connection_adapters/abstract_adapter.rb

@@ -0,0 +1,41 @@
+module MigrationComments::ActiveRecord::ConnectionAdapters
+  module AbstractAdapter
+    def add_table_comment(table_name, comment_text)
+      # SQL standard doesn't support schema commenting
+      raise "Table comments are not supported"
+    end
+    alias comment_table :add_table_comment
+
+    def add_column_comment(table_name, column_name, comment_text)
+      # SQL standard doesn't support schema commenting
+      raise "Column comments are not supported"
+    end
+    alias comment_column :add_column_comment
+
+    def comments_supported?
+      false
+    end
+
+    # Remove a comment on a table (if set)
+    def remove_table_comment(table_name)
+      add_table_comment(table_name, nil)
+    end
+
+    # Remove a comment on a column (if set)
+    def remove_column_comment(table_name, column_name)
+      add_column_comment(table_name, column_name, nil)
+    end
+
+    def retrieve_table_comment(table_name)
+      nil
+    end
+
+    def retrieve_column_comments(table_name, *column_names)
+      {}
+    end
+
+    def retrieve_column_comment(table_name, column_name)
+      retrieve_column_comments(table_name, column_name)[column_name]
+    end
+  end
+end

data/lib/migration_comments/active_record/connection_adapters/column_definition.rb

@@ -0,0 +1,5 @@
+module MigrationComments::ActiveRecord::ConnectionAdapters
+  module ColumnDefinition
+    attr_accessor :comment
+  end
+end

data/lib/migration_comments/active_record/connection_adapters/comment_definition.rb

@@ -0,0 +1,22 @@
+module MigrationComments::ActiveRecord::ConnectionAdapters
+  class CommentDefinition < Struct.new(:adapter, :table, :column_name, :comment_text)
+    def to_dump
+      table_comment? ?
+          "add_table_comment :#{table_name}, %{#{comment_text}}" :
+          "add_column_comment :#{table_name}, :#{column_name}, %{#{comment_text}}"
+    end
+
+    def to_sql
+      adapter.comment_sql(self)
+    end
+    alias to_s :to_sql
+
+    def table_comment?
+      column_name.blank?
+    end
+
+    def table_name
+      table.respond_to?(:name) ? table.name : table
+    end
+  end
+end

data/lib/migration_comments/active_record/connection_adapters/mysql2_adapter.rb

@@ -0,0 +1,9 @@
+module MigrationComments::ActiveRecord::ConnectionAdapters
+  module Mysql2Adapter
+    def self.included(base)
+      base.class_eval do
+        include MigrationComments::ActiveRecord::ConnectionAdapters::MysqlAdapter
+      end
+    end
+  end
+end

data/lib/migration_comments/active_record/connection_adapters/mysql_adapter.rb

@@ -0,0 +1,97 @@
+module MigrationComments::ActiveRecord::ConnectionAdapters
+  module MysqlAdapter
+    def self.included(base)
+      base.class_eval do
+        attr_accessor :database_name
+        alias_method_chain :create_table, :migration_comments
+        alias_method_chain :change_column, :migration_comments
+      end
+    end
+
+    def add_table_comment(table_name, comment)
+      execute "ALTER TABLE #{table_name} COMMENT #{escaped_comment(comment)}"
+    end
+
+    def add_column_comment(table_name, column_name, comment)
+      column = column_for(table_name, column_name)
+      change_column table_name, column_name, column.sql_type, :comment => comment
+    end
+
+    def retrieve_table_comment(table_name)
+      result = select_rows(table_comment_sql(table_name))
+      result[0].nil? || result[0][0].blank? ? nil : result[0][0]
+    end
+
+    def retrieve_column_comments(table_name, *column_names)
+      result = select_rows(column_comment_sql(table_name, *column_names))
+      return {} if result.nil?
+      return result.inject({}){|m, row| m[row[0].to_sym] = (row[1].blank? ? nil : row[1]); m}
+    end
+
+    def create_table_with_migration_comments(table_name, options={}, &block)
+      local_table_definition = nil
+      create_table_without_migration_comments(table_name, options) do |td|
+        local_table_definition = td
+        local_table_definition.comment options[:comment] if options.has_key?(:comment)
+        block.call(td)
+      end
+      comments = local_table_definition.collect_comments(table_name)
+      comments.each do |comment_definition|
+        execute_comment comment_definition
+      end
+    end
+
+    def change_column_with_migration_comments(table_name, column_name, type, options={})
+      unless options.keys.include?(:comment)
+        options.merge!(:comment => retrieve_column_comment(table_name, column_name))
+      end
+      change_column_without_migration_comments(table_name, column_name, type, options)
+    end
+
+    def add_column_options!(sql, options)
+      super(sql, options)
+      if options.keys.include?(:comment)
+        sql << " COMMENT #{escaped_comment(options[:comment])}"
+      end
+    end
+
+    def execute_comment(comment_definition)
+      if comment_definition.table_comment?
+        add_table_comment comment_definition.table_name, comment_definition.comment_text
+      else
+        add_column_comment comment_definition.table_name, comment_definition.column_name, comment_definition.comment_text
+      end
+    end
+
+    private
+    def escaped_comment(comment)
+      comment.nil? ? "''" : "'#{comment.gsub("'", "''").gsub("\\", "\\\\\\\\")}'"
+    end
+
+    def table_comment_sql(table_name)
+      ensure_database_name
+      <<SQL
+SELECT table_comment FROM INFORMATION_SCHEMA.TABLES
+  WHERE table_schema = '#{database_name}'
+  AND table_name = '#{table_name}'
+SQL
+    end
+
+    def column_comment_sql(table_name, *column_names)
+      ensure_database_name
+      col_matcher_sql = column_names.empty? ? "" : " AND column_name IN (#{column_names.map{|c_name| "'#{c_name}'"}.join(',')})"
+      <<SQL
+SELECT column_name, column_comment FROM INFORMATION_SCHEMA.COLUMNS
+  WHERE table_schema = '#{database_name}'
+  AND table_name = '#{table_name}' #{col_matcher_sql}
+SQL
+    end
+
+    def ensure_database_name
+      return if database_name
+      info = YAML::load(IO.read('config/database.yml'))
+      @database_name = info[ENV['DB'] || RAILS_ENV]["database"]
+    end
+
+  end
+end

data/lib/migration_comments/active_record/connection_adapters/postgresql_adapter.rb

@@ -0,0 +1,111 @@
+module MigrationComments::ActiveRecord::ConnectionAdapters
+  module PostgreSQLAdapter
+    def self.included(base)
+      base.class_eval do
+        alias_method_chain :create_table, :migration_comments
+        alias_method_chain :add_column, :migration_comments
+        alias_method_chain :change_column, :migration_comments
+      end
+    end
+
+    def comments_supported?
+      true
+    end
+
+    # Set a comment on a table
+    def add_table_comment(table_name, comment_text)
+      execute CommentDefinition.new(self, table_name, nil, comment_text).to_sql
+    end
+
+    # Set a comment on a column
+    def add_column_comment(table_name, column_name, comment_text)
+      execute CommentDefinition.new(self, table_name, column_name, comment_text).to_sql
+    end
+
+    def retrieve_table_comment(table_name)
+      result = execute(table_comment_sql(table_name)).result
+      result[0].nil? ? nil : result[0][0]
+    end
+
+    def retrieve_column_comments(table_name, *column_names)
+      result = execute(column_comment_sql(table_name, *column_names)).result
+      return {} if result.nil?
+      return result.inject({}){|m, row| m[row[0].to_sym] = row[1]; m}
+    end
+
+    def create_table_with_migration_comments(table_name, options = {}, &block)
+      local_table_definition = nil
+      create_table_without_migration_comments(table_name, options) do |td|
+        local_table_definition = td
+        local_table_definition.comment options[:comment] if options.has_key?(:comment)
+        block.call(td)
+      end
+      comments = local_table_definition.collect_comments(table_name)
+      comments.each do |comment_definition|
+        execute comment_definition.to_sql
+      end
+    end
+
+    def add_column_with_migration_comments(table_name, column_name, type, options = {})
+      add_column_without_migration_comments(table_name, column_name, type, options)
+      if options[:comment]
+        add_column_comment(table_name, column_name, options[:comment])
+      end
+    end
+
+    def change_column_with_migration_comments(table_name, column_name, type, options = {})
+      change_column_without_migration_comments(table_name, column_name, type, options)
+      if options.keys.include?(:comment)
+        add_column_comment(table_name, column_name, options[:comment])
+      end
+    end
+
+    def comment_sql(comment_definition)
+      "COMMENT ON #{comment_target(comment_definition)} IS #{escaped_comment(comment_definition.comment_text)}"
+    end
+
+    private
+
+    private
+    def comment_target(comment_definition)
+      comment_definition.table_comment? ?
+          "TABLE #{quote_table_name(comment_definition.table_name)}" :
+          "COLUMN #{quote_table_name(comment_definition.table_name)}.#{quote_column_name(comment_definition.column_name)}"
+    end
+
+    def escaped_comment(comment)
+      comment.nil? ? 'NULL' : "'#{comment.gsub("'", "''")}'"
+    end
+
+    def table_comment_sql(table_name)
+      <<SQL
+SELECT d.description FROM (
+#{table_oids(table_name)}) tt
+JOIN pg_catalog.pg_description d
+  ON tt.oid = d.objoid AND tt.tableoid = d.classoid AND d.objsubid = 0;
+SQL
+    end
+
+    def column_comment_sql(table_name, *column_names)
+      col_matcher_sql = column_names.empty? ? "" : " a.attname IN (#{column_names.map{|c_name| "'#{c_name}'"}.join(',')}) AND "
+      <<SQL
+SELECT a.attname, pg_catalog.col_description(a.attrelid, a.attnum)
+FROM pg_catalog.pg_attribute a
+JOIN (
+#{table_oids(table_name)}) tt
+  ON tt.oid = a.attrelid
+WHERE #{col_matcher_sql} a.attnum > 0 AND NOT a.attisdropped;
+SQL
+    end
+
+    def table_oids(table_name)
+      <<SQL
+SELECT c.oid, c.tableoid
+FROM pg_catalog.pg_class c
+WHERE c.relname = '#{table_name}'
+  AND c.relkind = 'r'
+  AND pg_catalog.pg_table_is_visible(c.oid)
+SQL
+    end
+  end
+end

data/lib/migration_comments/active_record/connection_adapters/table.rb

@@ -0,0 +1,12 @@
+module MigrationComments::ActiveRecord::ConnectionAdapters
+  module Table
+    def change_comment(column_name, comment_text)
+      @base.add_column_comment(@table_name, column_name, comment_text)
+    end
+
+    def change_table_comment(comment_text)
+      @base.add_table_comment(@table_name, comment_text)
+    end
+    alias comment :change_table_comment
+  end
+end

data/lib/migration_comments/active_record/connection_adapters/table_definition.rb

@@ -0,0 +1,30 @@
+module MigrationComments::ActiveRecord::ConnectionAdapters
+  module TableDefinition
+
+    attr_accessor :table_comment
+    def self.included(base)
+      base.class_eval do
+        alias_method_chain :column, :migration_comments
+      end
+    end
+
+    def comment(text)
+      @table_comment = CommentDefinition.new(@base, nil, nil, text)
+      self
+    end
+
+    def column_with_migration_comments(name, type, options = {})
+      column_without_migration_comments(name, type, options)
+      col = self[name]
+      col.comment = CommentDefinition.new(@base, nil, name, options[:comment])
+      self
+    end
+
+    def collect_comments(table_name)
+      comments = []
+      comments << @table_comment << @columns.map(&:comment)
+      comments.flatten!.compact!
+      comments.each{|comment| comment.table = table_name}
+    end
+  end
+end

data/lib/migration_comments/active_record/schema_dumper.rb

@@ -0,0 +1,54 @@
+module MigrationComments::ActiveRecord
+  module SchemaDumper
+    def self.included(base)
+      base.class_eval do
+        alias_method_chain :table, :migration_comments
+      end
+    end
+
+    def table_with_migration_comments(table, stream)
+      tbl_stream = StringIO.new
+      table_without_migration_comments(table, tbl_stream)
+      tbl_stream.rewind
+      commented_stream = append_comments(table, tbl_stream)
+      tbl_stream.close
+      stream.print commented_stream.read
+    end
+
+    def append_comments(table, stream)
+      table_name = table.inspect.gsub('"', '')
+      table_comment = @connection.retrieve_table_comment(table_name)
+      column_comments = @connection.retrieve_column_comments(table_name)
+      comment_stream = StringIO.new
+      lines = []
+      table_line = 0
+      col_names = {}
+      while (line = stream.gets)
+        content = line.chomp
+        if content =~ /create_table\s/
+          table_line = lines.size
+        elsif content =~ /t\.\w+\s+"(\w+)"/
+          col_names[lines.size] = $1.to_sym
+        end
+        lines << content
+      end
+      len = col_names.keys.map{|index| lines[index]}.map(&:length).max + 2
+      lines.each_with_index do |line, index|
+        if table_line == index && table_comment.present?
+          block_init = " do |t|"
+          line.chomp!(block_init) << ", " << render_comment(table_comment) << block_init
+        elsif col_names[index]
+          comment = column_comments[col_names[index]]
+          line << ',' << ' ' * (len - line.length) << render_comment(comment) unless comment.blank?
+        end
+        comment_stream.puts line
+      end
+      comment_stream.rewind
+      comment_stream
+    end
+
+    def render_comment(comment)
+      ":comment => \"#{comment}\""
+    end
+  end
+end

data/lib/migration_comments/annotate_models.rb

@@ -0,0 +1,40 @@
+module MigrationComments
+  module AnnotateModels
+    def self.included(base)
+      base.class_eval do
+        class << self
+          include ClassMethods
+          alias_method_chain :get_schema_info, :migration_comments
+        end
+      end
+    end
+
+    module ClassMethods
+      def get_schema_info_with_migration_comments(*args)
+        info = get_schema_info_without_migration_comments(*args)
+        klass = args[0]
+        commented_info(klass, info)
+      end
+
+      def commented_info(klass, info)
+        table_name = klass.table_name
+        adapter = klass.connection
+        table_comment = adapter.retrieve_table_comment(table_name)
+        column_comments = adapter.retrieve_column_comments(table_name)
+        lines = []
+        info.each_line{|l| lines << l.chomp}
+        column_regex = /^#\s+(\w+)\s+:\w+/
+        len = lines.select{|l| l =~ column_regex}.map{|l| l.length}.max
+        lines.each do |line|
+          if line =~ /# Table name: |# table \+\w+\+ /
+            line << " # #{table_comment}" if table_comment
+          elsif line =~ column_regex
+            comment = column_comments[$1.to_sym]
+            line << " " * (len - line.length) << " # #{comment}" if comment
+          end
+        end
+        lines.join($/) + $/
+      end
+    end
+  end
+end

data/lib/migration_comments/version.rb

@@ -0,0 +1,3 @@
+module MigrationComments
+  VERSION = "0.1.0"
+end

data/lib/migration_comments.rb

@@ -0,0 +1,58 @@
+require "migration_comments/version"
+
+require 'migration_comments/active_record/schema_dumper'
+require 'migration_comments/active_record/connection_adapters/comment_definition'
+require 'migration_comments/active_record/connection_adapters/column_definition'
+require 'migration_comments/active_record/connection_adapters/table'
+require 'migration_comments/active_record/connection_adapters/table_definition'
+require 'migration_comments/active_record/connection_adapters/abstract_adapter'
+require 'migration_comments/active_record/connection_adapters/mysql_adapter'
+require 'migration_comments/active_record/connection_adapters/mysql2_adapter'
+require 'migration_comments/active_record/connection_adapters/postgresql_adapter'
+
+module MigrationComments
+  def self.setup
+    base_names = %w(SchemaDumper) +
+      %w(ColumnDefinition Table TableDefinition AbstractAdapter).map{|name| "ConnectionAdapters::#{name}"}
+
+    base_names.each do |base_name|
+      ar_class = "ActiveRecord::#{base_name}".constantize
+      mc_class = "MigrationComments::ActiveRecord::#{base_name}".constantize
+      unless ar_class.ancestors.include?(mc_class)
+        ar_class.__send__(:include, mc_class)
+      end
+    end
+
+    %w(PostgreSQL Mysql Mysql2).each do |adapter|
+      begin
+        require("active_record/connection_adapters/#{adapter.downcase}_adapter")
+        adapter_class = ('ActiveRecord::ConnectionAdapters::' << "#{adapter}Adapter").constantize
+        mc_class = ('MigrationComments::ActiveRecord::ConnectionAdapters::' << "#{adapter}Adapter").constantize
+        adapter_class.module_eval do
+          adapter_class.__send__(:include, mc_class)
+        end
+      rescue Exception => ex
+      end
+    end
+
+    # annotations are not required for this gem, but if they exist they should be updated
+    begin
+      begin # first try to load from the 'annotate' gem
+        require 'annotate/annotate_models'
+      rescue Exception => ex
+        # continue as it may be already accessible through a plugin
+      end
+      gem_class = AnnotateModels
+      # don't require this until after the original AnnotateModels loads to avoid namespace confusion
+      require 'migration_comments/annotate_models'
+      mc_class = MigrationComments::AnnotateModels
+      unless gem_class.ancestors.include?(mc_class)
+        gem_class.__send__(:include, mc_class)
+      end
+    rescue Exception => ex
+      # if we got here, don't bother installing comments into annotations
+    end
+  end
+end
+
+MigrationComments.setup

data/migration_comments.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "migration_comments/version"
+
+Gem::Specification.new do |s|
+  s.name        = "migration_comments"
+  s.version     = MigrationComments::VERSION
+  s.authors     = ["Pinny"]
+  s.email       = ["pinny@medwiztech.com"]
+  s.homepage    = "https://github.com/pinnymz/migration_comments"
+  s.summary     = %q{Comments for your migrations}
+  s.description = %q{Add schema comments in your migrations, see them in model annotations and db/schema.rb dump}
+
+  s.rubyforge_project = "migration_comments"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency 'rails', '~> 2.3', '>= 2.3.2'
+
+  # for development, we are testing against the 'annotate' gem
+  # however, the comments should work with the original 'annotate_models' plugin as well at:
+  #  http://repo.pragprog.com/svn/Public/plugins/annotate_models
+  # provided the environment is not loaded until _after_ the AnnotateModels module is declared
+  s.add_development_dependency 'annotate'
+
+  s.add_development_dependency 'postgres-pr' # replace with other adapter as needed
+  # s.add_development_dependency 'mysql'
+  # s.add_development_dependency 'mysql2'
+end

data/test/add_comments_test.rb

@@ -0,0 +1,135 @@
+require 'test_helper'
+
+class AddCommentsTest < Test::Unit::TestCase
+  include TestHelper
+
+  def test_adding_a_table_comment
+    comment_text = "a comment on the sample table"
+    result = nil
+    ActiveRecord::Schema.define do
+      add_table_comment :sample, comment_text
+      result = retrieve_table_comment :sample
+    end
+    assert_equal comment_text, result
+  end
+
+  def test_adding_a_column_comment
+    comment_text = "a comment on the sample table in the column field"
+    result_field1 = nil
+    result_field2 = nil
+    ActiveRecord::Schema.define do
+      add_column_comment :sample, :field1, comment_text
+      result_field1 = retrieve_column_comment :sample, :field1
+      result_field2 = retrieve_column_comment :sample, :field2
+    end
+    assert_equal comment_text, result_field1
+    assert_nil result_field2
+  end
+
+  def test_creating_a_table_with_table_and_column_comments
+    table_comment = "a table comment"
+    column_comment = "a column comment"
+    result_table_comment = nil
+    result_column_comments = nil
+    ActiveRecord::Schema.define do
+      begin
+        create_table :sample2, :comment => table_comment do |t|
+          t.integer :field1, :comment => column_comment
+          t.string :field2
+        end
+        result_table_comment = retrieve_table_comment :sample2
+        result_column_comments = retrieve_column_comments :sample2
+      ensure
+        drop_table :sample2
+      end
+    end
+    assert_equal table_comment, result_table_comment
+    assert_equal column_comment, result_column_comments[:field1]
+    assert_nil result_column_comments[:field2]
+  end
+
+  def test_changing_a_table_with_new_comments
+    table_comment = "a table comment"
+    column_comment1 = "a column comment"
+    column_comment2 = "another column comment"
+    result_table_comment = nil
+    result_column_comments = nil
+    ActiveRecord::Schema.define do
+      change_table :sample do |t|
+        t.comment table_comment
+        t.change :field1, :string, :comment => column_comment1
+        t.change :field2, :integer
+        t.boolean :field3, :comment => column_comment2
+      end
+      result_table_comment = retrieve_table_comment :sample
+      result_column_comments = retrieve_column_comments :sample
+    end
+    assert_equal table_comment, result_table_comment
+    assert_equal column_comment1, result_column_comments[:field1]
+    assert_equal column_comment2, result_column_comments[:field3]
+    assert_nil result_column_comments[:field2]
+  end
+
+  def test_partially_modifying_comments_from_a_table
+    table_comment = "a table comment"
+    column_comment1 = "a column comment"
+    column_comment2 = "another column comment"
+    column_comment3 = "yet a third column comment"
+    modified_comment = "modified comment"
+    result_table_comment = nil
+    result_column_comments = nil
+    ActiveRecord::Schema.define do
+      change_table :sample do |t|
+        t.comment table_comment
+        t.change :field1, :string, :comment => column_comment1
+        t.change :field2, :integer, :comment => column_comment2
+        t.boolean :field3, :comment => column_comment3
+      end
+      change_table :sample do |t|
+        t.comment nil
+        t.change :field1, :string
+        t.change :field2, :integer, :comment => modified_comment
+        t.change :field3, :boolean, :comment => nil
+      end
+      result_table_comment = retrieve_table_comment :sample
+      result_column_comments = retrieve_column_comments :sample
+    end
+    assert_nil result_table_comment
+    assert_equal column_comment1, result_column_comments[:field1]
+    assert_equal modified_comment, result_column_comments[:field2]
+    assert_nil result_column_comments[:field3]
+  end
+
+  def test_removing_comments_from_a_table
+    comment_text = "a comment on the sample table"
+    result = nil
+    ActiveRecord::Schema.define do
+      add_table_comment :sample, comment_text
+      remove_table_comment :sample
+      result = retrieve_table_comment :sample
+    end
+    assert_nil result
+  end
+
+  def test_removing_comments_from_a_column
+    comment_text = "a comment on field1 of sample table"
+    result = nil
+    ActiveRecord::Schema.define do
+      add_column_comment :sample, :field1, comment_text
+      remove_column_comment :sample, :field1
+      result = retrieve_column_comment :sample, :field1
+    end
+    assert_nil result
+  end
+
+  def test_comment_text_is_escaped_properly
+    comment_text = "a \"comment\" \\ that ' needs; escaping''"
+    result = nil
+    ActiveRecord::Schema.define do
+      add_table_comment :sample, comment_text
+      result = retrieve_table_comment :sample
+    end
+    assert_equal comment_text, result
+  end
+
+end

data/test/annotate_models_test.rb

@@ -0,0 +1,53 @@
+require 'test_helper'
+gem 'annotate'
+require 'annotate/annotate_models'
+
+class Sample < ActiveRecord::Base
+  self.table_name = 'sample'
+end
+
+class AnnotateModelsTest < Test::Unit::TestCase
+  include TestHelper
+
+  TEST_PREFIX = "== Schema Information"
+
+  def test_annotate_includes_comments
+    db_type = :default
+    ActiveRecord::Schema.define do
+      db_type = :postgres if connection.is_a?(ActiveRecord::ConnectionAdapters::PostgreSQLAdapter) rescue false
+
+      add_table_comment :sample, "a table comment"
+      add_column_comment :sample, :field1, "a \"comment\" \\ that ' needs; escaping''"
+      add_column :sample, :field3, :string, :null => false, :comment => "third column comment"
+    end
+
+    result = AnnotateModels.get_schema_info(Sample, TEST_PREFIX)
+    postgres_expected = <<EOS
+# #{TEST_PREFIX}
+#
+# Table name: sample # a table comment
+#
+#  id     :integer         not null, primary key
+#  field1 :string(255)                           # a "comment" \\ that ' needs; escaping''
+#  field2 :integer
+#  field3 :string(255)     not null              # third column comment
+#
+
+EOS
+    default_expected = <<EOS
+# #{TEST_PREFIX}
+#
+# Table name: sample # a table comment
+#
+#  id     :integer(4)      not null, primary key
+#  field1 :string(255)                           # a "comment" \\ that ' needs; escaping''
+#  field2 :integer(4)
+#  field3 :string(255)     not null              # third column comment
+#
+
+EOS
+    expected = instance_eval "#{db_type}_expected"
+    assert_equal expected, result
+  end
+end
+

data/test/config/database.yml

@@ -0,0 +1,12 @@
+postgres:
+  adapter: postgresql
+  database: migration_comments_test
+  host: 127.0.0.1
+  username: postgres
+  password: postgres
+
+mysql:
+  adapter: mysql # mysql2
+  database: migration_comments_test
+  user: root
+  password: password

data/test/schema_dumper_test.rb

@@ -0,0 +1,40 @@
+require 'test_helper'
+
+class SchemaDumperTest < Test::Unit::TestCase
+  include TestHelper
+
+  def test_dump
+    ActiveRecord::Schema.define do
+      add_table_comment :sample, "a table comment"
+      add_column_comment :sample, :field1, "a \"comment\" \\ that ' needs; escaping''"
+      add_column :sample, :field3, :string, :null => false, :comment => "third column comment"
+    end
+    dest = StringIO.new
+    ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection, dest)
+    dest.rewind
+    result = dest.read
+    expected = <<EOS
+# This file is auto-generated from the current state of the database. Instead of editing this file, 
+# please use the migrations feature of Active Record to incrementally modify your database, and
+# then regenerate this schema definition.
+#
+# Note that this schema.rb definition is the authoritative source for your database schema. If you need
+# to create the application database on another system, you should be using db:schema:load, not running
+# all the migrations from scratch. The latter is a flawed and unsustainable approach (the more migrations
+# you'll amass, the slower it'll run and the greater likelihood for issues).
+#
+# It's strongly recommended to check this file into your version control system.
+
+ActiveRecord::Schema.define(:version => 1) do
+
+  create_table "sample", :force => true, :comment => "a table comment" do |t|
+    t.string  "field1",                 :comment => "a \"comment\" \\ that ' needs; escaping''"
+    t.integer "field2"
+    t.string  "field3", :null => false, :comment => "third column comment"
+  end
+
+end
+EOS
+    assert_equal expected, result
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,30 @@
+require 'test/unit'
+
+require 'rubygems'
+gem 'rails', '>= 2.3.2'
+require 'active_record'
+require 'yaml'
+
+CONFIGURATIONS = YAML::load(IO.read('config/database.yml'))
+
+ActiveRecord::Base.establish_connection(CONFIGURATIONS[ENV['DB'] || 'postgres'])
+
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'migration_comments'
+
+module TestHelper
+  def setup
+    ActiveRecord::Schema.define(:version => 1) do
+      create_table :sample do |t|
+        t.string :field1
+        t.integer :field2
+      end
+    end
+  end
+
+  def teardown
+    ActiveRecord::Schema.define do
+      drop_table :sample
+    end
+  end
+end

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification 
+name: migration_comments
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Pinny
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-02-10 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 2
+        - 3
+        version: "2.3"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 2
+        - 3
+        - 2
+        version: 2.3.2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: annotate
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: postgres-pr
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: Add schema comments in your migrations, see them in model annotations and db/schema.rb dump
+email: 
+- pinny@medwiztech.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.rdoc
+- Rakefile
+- lib/migration_comments.rb
+- lib/migration_comments/active_record/connection_adapters/abstract_adapter.rb
+- lib/migration_comments/active_record/connection_adapters/column_definition.rb
+- lib/migration_comments/active_record/connection_adapters/comment_definition.rb
+- lib/migration_comments/active_record/connection_adapters/mysql2_adapter.rb
+- lib/migration_comments/active_record/connection_adapters/mysql_adapter.rb
+- lib/migration_comments/active_record/connection_adapters/postgresql_adapter.rb
+- lib/migration_comments/active_record/connection_adapters/table.rb
+- lib/migration_comments/active_record/connection_adapters/table_definition.rb
+- lib/migration_comments/active_record/schema_dumper.rb
+- lib/migration_comments/annotate_models.rb
+- lib/migration_comments/version.rb
+- migration_comments.gemspec
+- test/add_comments_test.rb
+- test/annotate_models_test.rb
+- test/config/database.yml
+- test/schema_dumper_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: https://github.com/pinnymz/migration_comments
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: migration_comments
+rubygems_version: 1.4.2
+signing_key: 
+specification_version: 3
+summary: Comments for your migrations
+test_files: []
+