Can I add comments to a table or column using ActiveRecord Migrations?

Question

In MySQL (and other SQL databases), it can be helpful to add comments to a table or column whose purpose may be unclear. (Search MySQL's create table syntax for "comment" for examples.)

Is there a way to do this in an ActiveRecord Migration? I have tried this with no results.

create_table :stuff do |t|
  t.integer :obscure_column, :comment => "Explanatory comment"
end

I'm using Rails 3.1.

I wrote a gem not long ago `migration_comments` that will do what you need. Hasn't been battle tested for long, but I'd welcome any input... — PinnyM, Apr 12 '12 at 21:28
@PinnyM - Finally tried it out. Awesome! Thanks for releasing it. — Nathan Long, Mar 01 '13 at 20:09

score 18 · Accepted Answer · answered Mar 01 '13 at 19:27

18

The migration_comments gem mentioned in a comment to the original question appears to be the best cross-database solution for this need. In addition to providing migrations support for adding table and column comments, the gem also annotates the schema.rb file to include all of the comments. Perfect for my company's needs (large legacy rails app where the database model is ambiguous and also shared with a team of analysts writing native SQL reports).

answered Mar 01 '13 at 19:27

QuarkleMotion

814
8
10

2

It's worth noting that comments are baked in in Rails 5, no need for a gem. C.f. "comment" modifier http://edgeguides.rubyonrails.org/active_record_migrations.html#column-modifiers – Jerome Dalbert Jul 27 '16 at 23:19
1

In the latest rails, one can use `change_column_comment`, as explained in my answer https://stackoverflow.com/a/60584476/3090068 – Yuki Inoue Mar 08 '20 at 04:31

score 8 · Answer 2 · answered Mar 05 '19 at 15:30

8

In Rails 5 you can use the change_column:

class AddCommentsToReferences < ActiveRecord::Migration[5.2]
  def up
    change_column :references, :achievement_id, :integer, comment: 'Achievement'
    change_column :references, :object_id, :integer, comment: 'Achievement object id'
  end
end

don't forget write correct column_type as third parameter.

answered Mar 05 '19 at 15:30

Sergio Belevskij

2,478
25
24

4

In the latest rails, one can use `change_column_comment`, as explained in my answer https://stackoverflow.com/a/60584476/3090068 – Yuki Inoue Mar 08 '20 at 04:31

score 5 · Answer 3 · answered Mar 08 '20 at 04:29

5

I don't know when this method is introduced, but in the latest rails (6.0) you can use change_column_comment method.

def change
  change_column_comment(:posts, :state, from: "old_comment", to: "new_comment")
end

refer: https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-change_column_comment

answered Mar 08 '20 at 04:29

Yuki Inoue

3,569
5
34
53

1

Was [introduced in Rails 5 as of January 3rd, 2016 per this PR](https://github.com/rails/rails/commit/c690b9ce39c893077b48fa5b27af87e995f97e9b), however was not made [public API until October 4th, 2017](https://github.com/rails/rails/commit/85ca01bcb319d5ce66c0fa9ce6aede533492f0e9). – chemturion Jun 22 '20 at 18:48

score 5 · Answer 4 · answered Nov 08 '11 at 19:45

There is a gem called pg_comment that will add this functionality if you are using postgresql.

The gem adds extra commands to add the comments. Note that the syntax in postgresql is different than in mysql, and I guess that is why there is no general ActiveRecord implementation.

For example:

create_table :stuff do |t|
  t.integer :some_value
end
set_table_comment :stuff, 'This table stores stuff.'
set_column_comment :stuff, :some_value, 'Stores some value'

This could get pretty verbose, but I know there are some nice tools that make use of this.

Secondly, Rails indeed allows you to manage your schema from within rails (and that is awesome), it may seem sufficient to document your migrations, but after a while nobody looks at the migrations anymore. And you are stuck with an undocumented schema.

In the oracle-enhanced adapter this feature is available from the start, and has just the same syntax as you proposed.

Unfortunately I have not found a similar gem or solution for MySQL.

This one is for MySQL, but it hasn't been updated in 4 years: https://github.com/openrain/activerecord-comments — Nathan Long, Oct 26 '12 at 19:58

score 0 · Answer 5 · answered May 23 '23 at 22:54

In addition to change_column_comment (already mentioned in another answer) there is change_table_comment:

change_table_comment(:posts, from: "old table comment", to: "new table comment")

The from: key allows you to create a reversible migration for the comment. This will probably usually mean changing it from nil to some string. You can of course remove a comment by changing it to: nil.

Can I add comments to a table or column using ActiveRecord Migrations?

5 Answers5