When developing a Rails app, have there been times when you're wondering "what properties/columns does this model have"? The easiest way to find out is by inspecting db/schema.rb, but that gets annoying quickly. If only there's a way to keep your schema closer to you. Enter the annotate gem.
This gem adds comments summarizing a specific model's schema. Such comments are added to the top or bottom of each ActiveRecord model, test or RSpec spec, FactoryBot factory, etc. Here's an example:
# == 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 ...
Installation and usage
You can use it by adding it to your Gemfile as follows:
group :development do gem 'annotate' end
Then install the gem bundle and the Rails hooks:
bundle install ./bin/rails g annotate:install
Now you are ready to go! Run this to have it add comments:
bundle exec annotate
Notes and caveats
./bin/rails g annotate:install actually creates a file
lib/tasks/auto_annotate_models.rake, which ensures that every time you run
./bin/rails db:migrate, the
annotate command is run automatically for you. This means that most of the time you don't need to run
Still, it's not perfect. So sometimes you should double-check by running
annotate manually and check whether anything has been missed.
Also, the gem is very picky about names, and there's no way to customize that behavior. The biggest issue I've run into is that my FactoryBot factory files must have the same name as the model, in underscore plural format. So going along with the
LineItem example, the factory file must be called
line_item.rb won't do.
The gem also won't pick up everything in the schema, just the things supported by default by Rails. For example things like database constraints or stored procedures won't be picked up in the comments.
Still, the gem is very useful. Happy devving!