Add support for specifying comments for tables, columns, and indexes.

Comments are specified in migrations, stored in database itself (in its schema),
and dumped into db/schema.rb file.

This allows to generate good documentation and explain columns and tables' purpose
to everyone from new developers to database administrators.

For PostgreSQL and MySQL only. SQLite does not support comments at the moment.

See docs for PostgreSQL: http://www.postgresql.org/docs/current/static/sql-comment.html
See docs for MySQL: http://dev.mysql.com/doc/refman/5.7/en/create-table.html

1 files changed, 30 insertions, 6 deletions

diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
index 020d9bbdca..3bbd5a9515 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -18,6 +18,11 @@ module ActiveRecord
         nil
       end
 
+      # Returns comment associated with given table in database
+      def table_comment(table_name)
+        nil
+      end
+
       # Truncates a table alias according to the limits of the current adapter.
       def table_alias_for(table_name)
         table_name[0...table_alias_length].tr('.', '_')
@@ -255,7 +260,7 @@ module ActiveRecord
       #
       # See also TableDefinition#column for details on how to create columns.
       def create_table(table_name, options = {})
-        td = create_table_definition table_name, options[:temporary], options[:options], options[:as]
+        td = create_table_definition table_name, options[:temporary], options[:options], options[:as], options[:comment]
 
         if options[:id] != false && !options[:as]
           pk = options.fetch(:primary_key) do
@@ -265,7 +270,7 @@ module ActiveRecord
           if pk.is_a?(Array)
             td.primary_keys pk
           else
-            td.primary_key pk, options.fetch(:id, :primary_key), options
+            td.primary_key pk, options.fetch(:id, :primary_key), options.except(:comment)
           end
         end
 
@@ -283,6 +288,13 @@ module ActiveRecord
           end
         end
 
+        if supports_comments? && !supports_comments_in_create?
+          change_table_comment(table_name, options[:comment]) if options[:comment]
+          td.columns.each do |column|
+            change_column_comment(table_name, column.name, column.comment) if column.comment
+          end
+        end
+
         result
       end
 
@@ -1078,7 +1090,7 @@ module ActiveRecord
       def add_index_options(table_name, column_name, options = {}) #:nodoc:
         column_names = Array(column_name)
 
-        options.assert_valid_keys(:unique, :order, :name, :where, :length, :internal, :using, :algorithm, :type)
+        options.assert_valid_keys(:unique, :order, :name, :where, :length, :internal, :using, :algorithm, :type, :comment)
 
         index_type = options[:type].to_s if options.key?(:type)
         index_type ||= options[:unique] ? "UNIQUE" : ""
@@ -1106,13 +1118,25 @@ module ActiveRecord
         end
         index_columns = quoted_columns_for_index(column_names, options).join(", ")
 
-        [index_name, index_type, index_columns, index_options, algorithm, using]
+        comment = options[:comment] if options.key?(:comment)
+
+        [index_name, index_type, index_columns, index_options, algorithm, using, comment]
       end
 
       def options_include_default?(options)
         options.include?(:default) && !(options[:null] == false && options[:default].nil?)
       end
 
+      # Adds comment for given table or drops it if +nil+ given
+      def change_table_comment(table_name, comment)
+        raise NotImplementedError, "change_table_comment is not implemented"
+      end
+
+      # Adds comment for given table column or drops it if +nil+ given
+      def change_column_comment(table_name, column_name, comment) #:nodoc:
+        raise NotImplementedError, "change_column_comment is not implemented"
+      end
+
       protected
         def add_index_sort_order(option_strings, column_names, options = {})
           if options.is_a?(Hash) && order = options[:order]
@@ -1194,8 +1218,8 @@ module ActiveRecord
         end
 
       private
-      def create_table_definition(name, temporary = false, options = nil, as = nil)
-        TableDefinition.new(name, temporary, options, as)
+      def create_table_definition(name, temporary = false, options = nil, as = nil, comment = nil)
+        TableDefinition.new(name, temporary, options, as, comment)
       end
 
       def create_alter_table(name)