DEV Community

Play Button Pause Button
Kevin Gilpin for AppMap

Posted on

How to auto-document the database schema of your Rails app

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 above. 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. Check it out here:

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

  1. AppMap covering end-to-end data flows
  2. Swagger covering web services and APIs

Top comments (1)

sherrydays profile image
Sherry Day

Great talk. Thanks for sharing!