Use rails-erd Instead of annotate_models
Before we jump into
how to integrate it into your workflow let’s talk about something adjacent to
Often when dropping into a new Rails app I’ll notice that models, specs, and
factories will be the lucky bearers of the related database table schema thanks
annotate_models gem is a great tool for providing visibility into the
underlying structure of your database tables.
To that, I say “👍” !
However, there are some downsides. They’re not necessarily malevolent or problematic, but more speedbumps along the road of your development process.
It’s noisy at the top of important pieces of your code. Opening a file, being met with a wall of comments, and spending time to get to the meat of a class - it’s a speedbump. I ask you to ask yourself - how often do you really need to reference the columns and structure of your table? I’d guess “not so often”. It’s not that big a deal, but over time when your models grow in size it’s not unfathomable that your editor buffer, on first open, could be nothing but the contents from
If you use vim and tpope’s vim-rails package you can get to your model’s schema you can get to this information quickly already.
:Eschema table_namewill take you right there. Example:
:Eschema posts, etc.
If you use Atom there are plugins that will assist with this -
A migration should result in 2 files staged in Git. The new migration, and an updated
structure.sql. Instead, with
annotate_modelsyou end up with those two, plus: modified model, factory, and spec – for each model you update. To me that’s an unnecesary halo effect.
Last but not least — and, arguably, most annoyingly — if you or a teammate neglects to check those updates into git, the next time someone runs a recently checked in migration, your local files change modifying files that have nothing to do with the work you’re going to check in.
I will stop there with my humble request that you reconsider using
annotate_models and get into the meat of what I feel is a helpful tool for
your project(s). Enter
Rails ERD (Entity Relationship Diagram)
What is an “Entity Relationship Diagram”? According to techopedia:
An entity-relationship diagram (ERD) is a data modeling technique that graphically illustrates an information system’s entities and the relationships between those entities.
rails-erd is a utility gem that will generate a PDF with a diagram of your
models, their columns, and the relationship between the models. It looks a
little something like:
Per the directions on the project’s repo:
Make sure graphviz is installed:
brew install graphviz🍎
sudo apt install graphviz🐧
gem "rails-erd", require: false, group: :developmentto your application’s Gemfile
bundle exec erd
You should have a PDF in your app root waiting to be opened now!
For extra credit you can set up your app to generate a new erd after you’ve run new migrations.
bundle exec rails generate erd:install
Your information now resides in that one pdf, unlike
polution of all your files. One file that can be
gitignored if so desired!
In the grand scheme of things, the gripes I present above are miniscule. I’d
absolutely concede that. It’s really not that big a deal. However, if you’re
on a project using
annotate_models and you’re in the middle of a rebase
having to reconcile the merge conflicts from that gem across several files? I
hope you’ll remember this blog post.