Database documentation usually fails for one simple reason:
it depends on manual discipline.
Diagrams are created during the design phase, but real projects evolve fast:
requirements change, hotfixes happen, migrations pile up.
The code moves forward.
The database schema changes.
The diagram stays behind.
At some point, the ERD no longer represents production, and teams stop trusting it.
What worked better for me was changing the model entirely.
Instead of trying to maintain diagrams and documentation manually, I started treating the schema model as the source of truth, and generating everything else from it:
- SQL schemas
- Docker environments
- documentation and diagrams
- versioned artifacts in GitHub
The key idea is simple:
if the diagram drives the implementation, it cannot become outdated.
To make this concrete, I created a small public repository demonstrating this workflow, with:
- a single source model
- generated SQL
- a runnable Docker setup
- and documentation derived from the same model
Repository:
https://github.com/ThiagoRosa21/schema-versioning-demo
The examples in the repo were generated using ForgeSQL:
https://forgesql.com
The goal is not to promote a tool, but to show a workflow where:
documentation does not depend on memory, discipline, or goodwill.
I’m curious how other teams deal with this today.
What actually guarantees that your database diagrams still reflect production?
Top comments (0)