pg_comment 0.0.3

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 pg_comment.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2011 Arthur Shagall
+
+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.rdoc

@@ -0,0 +1,62 @@
+= PgComment
+
+In any PostgreSQL database where the Rails app is not the only consumer, it is very helpful to have comments on the various database entities.  PgComment adds methods to migrations to set and remove comments on columns and tables.
+
+Obviously, only the PostgreSQL adapter is supported.
+
+== Warning
+
+This is still experimental.  If it blows up your Rails app, I will gladly welcome your bug reports.
+
+This has only been tested on Ruby 1.9.2 and JRuby 1.6.4.
+
+== Installation
+
+TODO: finish up once I publish and fix any initial bugs.
+
+== Usage
+
+PgComment adds four methods to migrations:
+
+* set_table_comment(table_name, comment)
+* remove_table_comment(table_name)
+* set_column_comment(table_name, column_name, comment)
+* remove_column_comment(table_name, column_name, comment)
+
+Set a comment on the given table.
+
+    set_table_comment :phone_numbers, 'This table stores phone numbers that conform to the North American Numbering Plan.'
+
+Sets a comment on a given column of a given table.
+
+    set_column_comment :phone_numbers, :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'
+
+Removes any comment from the given table.
+
+    remove_table_comment :phone_numbers
+
+Removes any comment from the given column of a given table.
+
+    remove_column_comment :phone_numbers, :npa
+
+PgComment also adds extra methods to change_table.
+
+Set comments:
+
+    change_table :phone_numbers do |t|
+        t.set_table_comment 'This table stores phone numbers that conform to the North American Numbering Plan.'
+        t.set_column_comment :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'
+    end
+
+Remove comments:
+
+    change_table :phone_numbers do |t|
+        t.remove_table_comment
+        t.remove_column_comment :npa
+    end
+
+== License
+
+Copyright (c) 2011 Arthur Shagall
+
+Released under the MIT License.  See LICENSE for details.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*test.rb']
+  t.verbose = true
+end

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

@@ -0,0 +1,51 @@
+module PgComment
+  module ConnectionAdapters
+    module SchemaDefinitions
+      def self.included(base)
+        base::Table.class_eval do
+          include PgComment::ConnectionAdapters::Table
+        end
+      end
+    end
+
+    module Table
+      extend ActiveSupport::Concern
+
+      # Sets the comment on the table
+      #
+      # ===== Example
+      # ====== Set comment on table
+      #   t.set_table_comment 'This table stores phone numbers that conform to the North American Numbering Plan.'
+      def set_table_comment(comment)
+        @base.set_table_comment(@table_name, comment)
+      end
+
+      # Removes any comment from the table
+      #
+      # ===== Example
+      # ====== Remove table comment
+      #   t.remove_table_comment
+      def remove_table_comment
+        @base.remove_table_comment(@table_name)
+      end
+
+      # Sets the comment for a given column
+      #
+      # ===== Example
+      # ====== Set comment on the npa column
+      #   t.set_column_comment :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'
+      def set_column_comment(column_name, comment)
+        @base.set_column_comment(@table_name, column_name, comment)
+      end
+
+      # Removes any comment for a given column
+      #
+      # ===== Example
+      # ====== Remove comment from the npa column
+      #   t.remove_column_comment :npa
+      def remove_column_comment(column_name)
+        @base.remove_column_comment(@table_name, column_name)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module PgComment
+  module ConnectionAdapters
+    module SchemaStatements
+      def self.included(base)
+        base::AbstractAdapter.class_eval do
+          include PgComment::ConnectionAdapters::AbstractAdapter
+        end
+      end
+    end
+
+    module AbstractAdapter
+
+      def supports_comments?
+        false
+      end
+
+      # Sets a comment on the given table.
+      #
+      # ===== Example
+      # ====== Creating a comment on phone_numbers table
+      #  set_table_comment :phone_numbers, 'This table stores phone numbers that conform to the North American Numbering Plan.'
+      def set_table_comment(table_name, comment)
+        # Does nothing
+      end
+
+      # Sets a comment on a given column of a given table.
+      #
+      # ===== Example
+      # ====== Creating a comment on npa column of table phone_numbers
+      #  set_column_comment :phone_numbers, :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'
+      def set_column_comment(table_name, column_name, comment)
+        # Does nothing
+      end
+
+      # Removes any comment from the given table.
+      #
+      # ===== Example
+      # ====== Removing comment from phone numbers table
+      #  remove_table_comment :phone_numbers
+      def remove_table_comment(table_name)
+
+      end
+
+      # Removes any comment from the given column of a given table.
+      #
+      # ===== Example
+      # ====== Removing comment from the npa column of table phone_numbers
+      #  remove_column_comment :phone_numbers, :npa
+      def remove_column_comment(table_name, column_name)
+        
+      end
+
+    end
+  end
+end

data/lib/pg_comment/connection_adapters/postgresql_adapter.rb

@@ -0,0 +1,59 @@
+module PgComment
+  module ConnectionAdapters
+    module PostgreSQLAdapter
+      def supports_comments?
+        true
+      end
+
+      def set_table_comment(table_name, comment)
+        sql = "COMMENT ON TABLE #{quote_table_name(table_name)} IS $$#{comment}$$;"
+        execute sql
+      end
+
+      def set_column_comment(table_name, column_name, comment)
+        sql = "COMMENT ON COLUMN #{quote_table_name(table_name)}.#{quote_column_name(column_name)} IS $$#{comment}$$;"
+        execute sql
+      end
+
+      def remove_table_comment(table_name)
+        sql = "COMMENT ON TABLE #{quote_table_name(table_name)} IS NULL;"
+        execute sql
+      end
+
+      def remove_column_comment(table_name, column_name)
+        sql = "COMMENT ON COLUMN #{quote_table_name(table_name)}.#{quote_column_name(column_name)} IS NULL;"
+        execute sql
+      end
+=begin
+--Fetch all comments
+SELECT c.relname as table_name, a.attname as column_name, d.description as comment
+FROM pg_description d
+JOIN pg_class c ON c.oid = d.objoid
+LEFT OUTER JOIN pg_attribute a ON c.oid = a.attrelid AND a.attnum = d.objsubid
+WHERE c.relkind = 'r'
+ORDER BY c.relname
+=end
+      def comments(table_name)
+        com = select_all %{
+SELECT a.attname AS column_name, d.description AS comment
+FROM pg_description d
+JOIN pg_class c on c.oid = d.objoid
+LEFT OUTER JOIN pg_attribute a ON c.oid = a.attrelid AND a.attnum = d.objsubid
+WHERE c.relkind = 'r' AND c.relname = '#{table_name}'
+                         }
+        com.map do |row|
+          [ row['column_name'], row['comment'] ]
+        end
+      end
+    end
+  end
+end
+
+[:PostgreSQLAdapter, :JdbcAdapter].each do |adapter|
+  begin
+    ActiveRecord::ConnectionAdapters.const_get(adapter).class_eval do
+      include PgComment::ConnectionAdapters::PostgreSQLAdapter
+    end
+  rescue
+  end
+end

data/lib/pg_comment/migration/command_recorder.rb

@@ -0,0 +1,32 @@
+module PgComment
+  module Migration
+    module CommandRecorder
+      def set_table_comment(*args)
+        record(:set_table_comment, args)
+      end
+
+      def remove_table_comment(*args)
+        record(:remove_table_comments, args)
+      end
+
+      def set_column_comment(*args)
+        record(:set_column_comment, args)
+      end
+
+      def remove_column_comment(*args)
+        record(:remove_column_comment, args)
+      end
+
+      def invert_set_table_comment(args)
+        table_name = args.first
+        [:remove_table_comment, [table_name]]
+      end
+
+      def invert_set_column_comment(args)
+        table_name = args[0]
+        column_name = args[1]
+        [:remove_column_comment, [table_name, column_name]]
+      end
+    end
+  end
+end

data/lib/pg_comment/railtie.rb

@@ -0,0 +1,27 @@
+module PgComment
+  class Railtie < Rails::Railtie
+    initializer 'pg_comment.load_adapter' do
+      ActiveSupport.on_load :active_record do
+        ActiveRecord::ConnectionAdapters.module_eval do
+          include PgComment::ConnectionAdapters::SchemaStatements
+          include PgComment::ConnectionAdapters::SchemaDefinitions
+        end
+
+        ActiveRecord::SchemaDumper.class_eval do
+          include PgComment::SchemaDumper
+        end
+
+        if defined?(ActiveRecord::Migration::CommandRecorder)
+          ActiveRecord::Migration::CommandRecorder.class_eval do
+            include PgComment::Migration::CommandRecorder
+          end
+        end
+
+        conf_name = ActiveRecord::Base.connection_pool.spec.config[:adapter]
+        if conf_name == 'postgresql' then
+          require 'pg_comment/connection_adapters/postgresql_adapter'
+        end
+      end
+    end
+  end
+end

data/lib/pg_comment/schema_dumper.rb

@@ -0,0 +1,36 @@
+module PgComment
+  module SchemaDumper
+    extend ActiveSupport::Concern
+
+    included do
+      alias_method_chain :tables, :comments
+    end
+
+    def tables_with_comments(stream)
+      tables_without_comments(stream)
+      @connection.tables.sort.each do |table_name|
+        dump_comments(table_name, stream)
+      end
+    end
+
+    def dump_comments(table_name, stream)
+      unless (comments = @connection.comments(table_name)).empty?
+        comment_statements = comments.map do |row|
+          column_name = row[0]
+          comment = row[1]
+          
+          if column_name
+            "  set_column_comment '#{table_name}', '#{column_name}', '#{comment.gsub(/'/, "\\\\'")}'"
+          else
+            "  set_table_comment '#{table_name}', '#{comment}'"
+          end
+
+        end
+
+        stream.puts comment_statements.join("\n")
+        stream.puts
+      end
+    end
+    private :dump_comments
+  end
+end

data/lib/pg_comment/version.rb

@@ -0,0 +1,3 @@
+module PgComment
+  VERSION = "0.0.3"
+end

data/lib/pg_comment.rb

@@ -0,0 +1,23 @@
+require "pg_comment/version"
+require 'active_support/all'
+
+module PgComment
+  extend ActiveSupport::Autoload
+  autoload :Adapter
+  autoload :SchemaDumper
+
+  module ConnectionAdapters
+    extend ActiveSupport::Autoload
+
+    autoload_under 'abstract' do
+      autoload :SchemaDefinitions
+      autoload :SchemaStatements
+    end
+  end
+
+  module Migration
+    autoload :CommandRecorder, 'pg_comment/migration/command_recorder'
+  end
+end
+
+require 'pg_comment/railtie' if defined?(Rails)

data/pg_comment.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "pg_comment/version"
+
+Gem::Specification.new do |s|
+  s.name        = "pg_comment"
+  s.version     = PgComment::VERSION
+  s.authors     = ["Arthur Shagall"]
+  s.email       = ["arthur.shagall@gmail.com"]
+  s.homepage    = "https://github.com/albertosaurus/pg_comment"
+  s.summary     = 'Postgres Comments for Rails'
+  s.description = 'Adds helper methods to migrations and pulls out comments into schema.rb'
+
+  s.rubyforge_project = "pg_comment"
+
+  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_dependency('activerecord', '>= 3.0.0')
+  s.add_development_dependency("test-unit")
+end

data/test/fake_connection.rb

@@ -0,0 +1,9 @@
+class FakeConnection
+  def initialize(args = {})
+    @comments = args[:comments]
+  end
+
+  def comments(table_name)
+    @comments
+  end
+end

data/test/postgre_sql_adapter_test.rb

@@ -0,0 +1,64 @@
+require 'rubygems'
+gem 'test-unit'
+require 'test/unit'
+require 'pg_comment/connection_adapters/postgresql_adapter'
+
+class PostgreSQLAdapterTest < Test::Unit::TestCase
+  class Adapter
+    attr_reader :buffer
+    def select_results=(val)
+      @select_results = val
+    end
+
+    def select_all(*args)
+      @select_results
+    end
+
+    def quote_table_name(table_name)
+      table_name
+    end
+
+    def quote_column_name(column_name)
+      column_name
+    end
+
+    def execute(sql)
+      @buffer ||= []
+      @buffer << sql
+    end
+
+    include PgComment::ConnectionAdapters::PostgreSQLAdapter
+  end
+
+  def test_sql_generation
+    expected = [ "COMMENT ON TABLE my_table IS $$table comment$$;",
+                 "COMMENT ON COLUMN my_table.my_column IS $$column comment$$;",
+                 "COMMENT ON TABLE my_table IS NULL;",
+                 "COMMENT ON COLUMN my_table.my_column IS NULL;" ]
+
+    a = Adapter.new
+    a.set_table_comment :my_table, 'table comment'
+    a.set_column_comment :my_table, :my_column, 'column comment'
+    a.remove_table_comment :my_table
+    a.remove_column_comment :my_table, :my_column
+    assert_equal expected, a.buffer
+  end
+
+  def test_comments
+    a = Adapter.new
+    expected = [ { 'column_name' => nil, 'comment' => 'table comment' },
+                 { 'column_name' => 'column1', 'comment' => 'column comment 1' },
+                 { 'column_name' => 'column2', 'comment' => 'column comment 2' } ]
+    a.select_results = expected
+    results = a.comments( nil )
+    assert_not_nil results
+    assert_equal 3, results.size, "Should have three comment rows."
+    results.each_with_index do |comment_row, index|
+      column_name = comment_row[0]
+      comment = comment_row[1]
+      assert_equal expected[index]['column_name'], column_name
+      assert_equal expected[index]['comment'], comment
+    end
+  end
+
+end

data/test/schema_dumper_test.rb

@@ -0,0 +1,47 @@
+require 'fake_connection'
+require 'rubygems'
+gem 'test-unit'
+require 'test/unit'
+require 'active_record'
+require 'pg_comment/schema_dumper'
+
+class SchemaDumperTest < Test::Unit::TestCase
+  class SchemaDumpContainer
+    def initialize
+      @connection = FakeConnection.new( :comments => [[nil, 'table comment'],
+                                                      ['c1', 'column1 comment'],
+                                                      ['c2', 'column2 comment']] )
+    end
+
+    def self.alias_method_chain(*args)
+      #Does nothing
+    end
+
+    include PgComment::SchemaDumper
+
+    public :dump_comments
+  end
+
+  class Stream
+    attr_reader :stream_results
+
+    def puts(str = nil)
+      @stream_results ||= []
+      @stream_results << str unless str.nil?
+    end
+  end
+
+  def setup
+    @fake_table = 'my_table'
+    @expected = ["  set_table_comment '#{@fake_table}', 'table comment'",
+                 "  set_column_comment '#{@fake_table}', 'c1', 'column1 comment'",
+                 "  set_column_comment '#{@fake_table}', 'c2', 'column2 comment'"].join("\n")
+  end
+
+  def test_dump_comments
+    sd = SchemaDumpContainer.new
+    stream = Stream.new
+    sd.dump_comments @fake_table, stream
+    assert_equal @expected, stream.stream_results[0]
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: pg_comment
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+  prerelease: 
+platform: ruby
+authors:
+- Arthur Shagall
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-09-10 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: &15971340 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *15971340
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: &15970820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *15970820
+description: Adds helper methods to migrations and pulls out comments into schema.rb
+email:
+- arthur.shagall@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/pg_comment.rb
+- lib/pg_comment/connection_adapters/abstract/schema_definitions.rb
+- lib/pg_comment/connection_adapters/abstract/schema_statements.rb
+- lib/pg_comment/connection_adapters/postgresql_adapter.rb
+- lib/pg_comment/migration/command_recorder.rb
+- lib/pg_comment/railtie.rb
+- lib/pg_comment/schema_dumper.rb
+- lib/pg_comment/version.rb
+- pg_comment.gemspec
+- test/fake_connection.rb
+- test/postgre_sql_adapter_test.rb
+- test/schema_dumper_test.rb
+homepage: https://github.com/albertosaurus/pg_comment
+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: pg_comment
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Postgres Comments for Rails
+test_files: []