[Awesome Ruby Gem] Use migration_comments gem to comment your Rails Migration

Posted on Edited on In , , Views: Word count in article: 2.2k Reading time ≈ 2 mins.

migration_comments

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, VS Code) 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.

Installation

You can install it as a gem:

1
$ gem install migration_comments

or add it into a Gemfile (Bundler):

1
2
3
4
5
6
7
8
# Gemfile

# Put gems used only for development or testing in the appropriate group in the Gemfile
group :development do
  # pinnymz/migration_comments: Comments for your migrations
  # https://github.com/pinnymz/migration_comments 
  gem 'migration_comments', '0.4.1'
end

Then, run bundle install.

1
$ bundle install

Usage

To add a comment to an existing structure…

1
2
3
4
def self.up
  set_table_comment :table_name, "A table comment"
  set_column_comment :table_name, :column_name, "A column comment"
end

Or you can use the change_table macro…

1
2
3
4
5
6
def 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?

1
2
3
4
5
def self.up
  create_table :table_name, :comment => "A table comment" do |t|
    t.string :column_name, :comment => "A column comment"
  end
end

Annotate (aka AnnotateModels)

The Annotate (aka AnnotateModels) gem annotating Rails classes with schema and routes info by adding a comment summarizing the current schema to the top or bottom of each of your codes.

The schema comment looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# == Schema Info
#
# Table name: line_items
#
#  id                  :integer(11)    not null, primary key
#  quantity            :integer(11)    not null
#  product_id          :integer(11)    not null
#  unit_price          :float
#  order_id            :integer(11)
#

class LineItem < ActiveRecord::Base
  belongs_to :product
  . . .

References

[1] pinnymz/migration_comments: Comments for your migrations - https://github.com/pinnymz/migration_comments

[2] ctran/annotate_models: Annotate Rails classes with schema and routes info - https://github.com/ctran/annotate_models