AnnotateRb keeps Rails schema comments honest after every migration

A fork of annotate_models, with a migration guide attached

AnnotateRb describes itself as a Ruby Gem that adds annotations to your Rails models and route files, and it states plainly that it is forked from the Annotate aka AnnotateModels gem. That origin matters more than it might appear, because forking means the two projects have diverged and the differences are real rather than cosmetic. The repository ships a MIGRATION_GUIDE.md specifically for people coming from the annotate gem, which is the clearest signal that behaviour changed rather than merely being renamed. What the gem does is add comments summarising the model schema or the routes into a set of files: ActiveRecord models, fixture files, tests and specs, FactoryBot factories, and the routes.rb file for Rails projects. The schema comment takes the familiar shape of a Schema Information block placed above the class, listing the table name and each column with its type and constraints. It is a comment generator for people who would rather not open a database console to answer what a column's nullability is.

The install generator wires a rake task into db:migrate

The installation story is small and the interesting part is the hook. The gem installs globally with a single command.

$ gem install annotaterb

Or it goes into the project Gemfile inside the development group, so it never loads in production.

group :development do
  ...

  gem "annotaterb"

  ...

Then a generator copies a rake task into your project's lib/tasks directory, where it hooks into the Rails rake tasks and runs AnnotateRb automatically after database migration tasks.

$ bin/rails g annotate_rb:install

After that, a migration annotates the models it touched.

$ bin/rails db:migrate
# ...
# Annotating models
# Annotated (1): app/models/user.rb

That output line is the whole point of the tool. The comment in app/models/user.rb is regenerated from the live schema rather than edited by hand, so it cannot drift. There is also an escape hatch for the case where the automatic run is not what you want.

$ ANNOTATERB_SKIP_ON_DB_TASKS=1 bin/rails db:migrate

Four generators, and one that repairs config drift

Four Rails generator commands get added by the gem, visible under the AnnotateRb heading when you run the generator help.

$ bin/rails generate --help

...

AnnotateRb:
  annotate_rb:config
  annotate_rb:hook
  annotate_rb:install
  annotate_rb:update_config
...

The config generator writes a new .annotaterb.yml using the gem's defaults. The hook generator installs the Rake file that annotates models after a database task, which is the same behaviour the install generator gives you. The install generator simply runs the config and hook generators in sequence, so it is the one to reach for unless you want only half the setup. The fourth one is the interesting one. The update_config generator appends to .annotaterb.yml any configuration key-value pairs that are used by the gem, and the documentation gives the reason plainly: it is useful when there is drift between the config file values and the gem defaults, which happens when new features are added in a later version. In other words, an existing .annotaterb.yml written against an older gem will be missing keys that the current gem understands, and this generator backfills them. If you are upgrading the gem across versions, that is the command that saves you from silently running with half your settings ignored.

The model options are where the real configuration lives

The CLI is a single binary with two subcommands, models and routes, and the model options list is long enough that you should read it before choosing defaults. The command listing shows the shape of it.

# To show the CLI options
$ bundle exec annotaterb

Usage: annotaterb [command] [options]

Commands:
    models [options]
    routes [options]
    help
    version

The flags control what goes into the comment. Foreign keys can be listed, with a companion option to complete the foreign key names. Indexes can be listed, with a simple-indexes mode that concatenates the column's related indexes onto the column line instead of listing them separately. Check constraints can be listed. Column types can be filtered out of the display, with separate options to hide the limit for given types and to hide the default for given types, both taking comma-separated values such as integer,boolean,text or json,jsonb,hstore. Columns can be skipped entirely with a regular expression option, and the documentation even shows the pattern it is modelled on, ignoring id, updated_at and created_at. Enum-backed columns have their own format option with label, raw and both values. Database comments, column comments and table comments each have include and exclude flags, and there is a separate option for where the column comment sits in the block. The pattern here is that anything you can imagine putting in a schema comment, you can turn on or off.

Routes annotation and the wrapper options

The routes side is smaller. You can ignore routes matching a regular expression, the documentation offering a pattern that skips mobile, resque and pghero routes, which are the usual suspects when your route list becomes unreadable. A timestamp can be included in the routes annotation, which is a deliberate choice about churn rather than a feature. The wrapper options control the text that frames the comment: a single wrapper flag uses the same text for the opening and closing, while separate wrapper-open and wrapper-close flags let the two ends differ. That is the sort of detail that matters if your project convention is a specific fence or a marker your tooling looks for. The routes annotation is also the one place where a timestamp option is offered, and that choice cuts both ways: it proves the annotation is current, and it puts a diff on every route change.

Deletion, custom paths and the model directory override

Several options exist for shaping where the gem looks and what it leaves behind. There is a delete option that removes annotations from all model files or from the routes.rb file, which is the inverse of what you just ran and belongs in a rake task of your own if you ever need to reset. The model directory can be overridden so the gem annotates files stored somewhere other than app/models, with multiple directories separated by commas, and the same comma-separated override exists for a root directory for projects whose files live under a different tree. Subdirectories of the models directory can be ignored. And there is an additional-file-patterns option that takes comma-separated paths or globs to annotate, with an example that includes a %MODEL_NAME% placeholder, which is how you annotate per-model files such as factory definitions that live outside the usual directories. There is also an option to place annotations directly above nested classes or modules rather than at the top of the file, which is a small thing that matters the moment your file has more than one class in it.

Maintenance, licensing and what the repository contains

The last push to the repository was on 2026-10-22, and the repository is not archived, though it publishes no GitHub releases, so version tracking happens through the gem rather than through tags on this repository. The licence is listed as a custom licence that GitHub cannot classify, and the LICENSE.txt file in the repository root holds the actual terms, so read that file rather than relying on the badge. The repository layout is a conventional Ruby gem layout with a gemspec, a VERSION file, a Gemfile, a Rakefile, lib and exe directories, a spec directory and a Guardfile for file watching during development. There is a.standard.yml and a.standard_todo.yml, so the code follows the Standard Ruby style, a.rspec file for RSpec configuration and a.yardopts file for documentation generation. The presence of DEVELOPMENT.md, CONTRIBUTING.md and a potato.md suggests a maintained project with contributor guidance, and a MIGRATION_GUIDE.md at the root for the annotate gem transition.

Editorial conclusion

Adopt AnnotateRb if your team reads model files to understand the database and wants that comment block to be regenerated rather than maintained by hand, especially if you have inherited a project where the annotations drift out of date. Do not adopt it if your models are thin wrappers and your team reads the schema in a database tool instead, since the annotation then duplicates information nobody reads. Verify two things before you wire it into a migration workflow: that the generator you install produces the annotation format your team expects rather than the annotate gem's format, because the migration guide exists precisely because the two differ, and that the rake hook does not fire in an environment where the schema is not the source of truth, such as a production console task. The practical first step is gem install annotaterb, then run bin/rails g annotate_rb:config and diff the generated .annotaterb.yml against the options your project actually needs.

Frequently asked questions

Official sources

1. drwl/annotaterb on GitHub
2. Issues
3. README