FloorPlan: Visualize database evolution
Easier peer reviews and documentation-as-code
At SoundCloud, we are around 20 Android engineers, working in a multi-module project with more than 10 databases, with multiple tables each. And that’s only the Android app!
As software matures, more functionality is added, code gets moved, re-written or removed. In the same rhythm, team members change and with them historical knowledge might get lost. For that reason, it is important to have a well-organized project, that is inviting for new contributors while still digestible for one-off readers.
Understanding how data is structured can be very helpful as an initial step for diving into the abstract modeling of the business domain. Database schemas, then, provide that entry window, but building the mental model out of a machine-readable format can be a daunting task even for seasoned engineers, especially when the project grows large and changes rapidly.
Enter FloorPlan
FloorPlan is an open source Kotlin library to translate database schemas into DBML definitions and ER diagrams.
It is distributed as a CLI tool and as a Gradle Plugin, for manual interaction and integration with CI environments.
Check out the full documentation and sample plugin integration.
Versioning 🗒️
As you already do for the rest of your documentation, checking in human-readable representations of your application’s logic is a great way to build historical knowledge on the codebase, and what ended up in production.
By using git, developers can iterate on proposed schema changes, easily review them and also bring in non-technical peers by lowering the learning curve into database technologies.
Code review 🔎
An useful recipe is to check-in each version of the database as a DBML schema, and then later, leverage the power of standard diffing tools to quickly spot changes:
In the spirit of full automation, these can then be written as pull request comments after a CI build:
Documentation 📝
With the power of GraphViz, FloorPlan can also output other rendering formats, such as vector SVGs, rasterized PNGs and diagram DOT files, allowing for even further integration with your team’s workflow.
At SoundCloud, we host an internal documentation portal, completely based on markdown files, that now can automatically include diagrams for our client application databases as pull requests are merged:
Extensibility 🗜️
FloorPlan’s API is designed for extensibility, and its Consumer API allows for integration with different RDBMS engines and ORMs. It doesn’t matter which source database ORM schema structure you use, with the help of a Consumerimplementation, FloorPlan will be able to translate the database schema.
On the Android space, for instance, there are many popular libraries to communicate with SQLite, each providing a different feature-set, that FloorPlan can integrate with.
That doesn’t make its usage Android-specific, though, since a Consumer for MySQL, Postgres or Oracle could also be built by leveraging these RDBMS’s schema exporting tools. In fact, one can work with already existing tools to use DBML itself as an input to FloorPlan.
Try it out
Integrate FloorPlan in your project’s workflow, contribute and provide feedback so it can improve further!
