RailsConf Recap Part 4: How to auto-document database schemas

RailsConf Recap Part 4: How to auto-document database schemas

I’m wrapping up my RailsConf 2021 presentation recap today. Check out Part 1, Part 2 and Part 3 in case you missed them! This final post recaps the demo I gave on how to auto-document database schemas with a gem called rails-erd.

An entity relationship diagram (ERD) shows the tables, columns and relations in a relational database schema. To auto-generate an ERD for a specific version of your code directly from the database, you can use the rails-erd gem. It does this by:

  • Gathering database meta data through active record (it uses ActiveRecord so it’s database independent)
  • Analyzing the schema and then generating a DOT file, which can be processed into a PDF
  • Bundling all of this up into a rake task, which you can use to update the ERD when you modify the schema

In the ERD PDF file, you can see a detailed diagram of your database schema. This is useful for analyzing the data model of an app and identifying features such as nullable and not nullable columns, column types, primary keys, foreign keys and the different types of relationships.

You can also get other insights from looking at the schema, such as security information. In my demo, for instance, I was able to see that the password remember and reset token were all stored as a one-way digest. So, if an attacker was able to obtain access to this database, I know they wouldn’t be able to obtain these secrets.

You can watch this portion of my RailsConf talk in the video clip below. If you want to follow along in the code or look it up later, I’ve created a branch called erd within the Land of Apps fork of the Rails Sample App sixth edition. Check it out here.

I’d love to hear your comments, suggestions and questions in Slack! And feel free to explore the other two types of code design docs that I demoed how to auto-generate, including:

AppMap logo Get AppMap