Forem: Thiago Rosa da Silva

Database documentation fails when it relies on human discipline

Thiago Rosa da Silva — Wed, 25 Feb 2026 01:02:11 +0000

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?

Database documentation fails when it relies on human discipline

Thiago Rosa da Silva — Tue, 24 Feb 2026 00:16:54 +0000

In theory, database documentation is simple:
design first, document everything, keep it updated.

In practice, that rarely survives real projects.

Schemas evolve fast. Requirements change. Hotfixes happen.
And the first thing to fall behind is always the diagram.

Not because teams don’t care — but because manual synchronization does not scale.

At some point, the ERD stops being a source of truth and turns into a snapshot of the past.
From there, people either stop trusting it… or stop opening it at all.

What worked better for me was changing the model entirely:

Instead of maintaining documentation, I started generating it from the actual model, versioned alongside the project, just like code.

That idea eventually became ForgeSQL — a visual modeling tool where the diagram is not an accessory, but the source that generates:

real SQL

real Docker environments

versioned artifacts in GitHub

No diagrams “to keep updated”.
No separate documentation to chase.

Just one model that stays aligned with reality.

I’m curious how other teams deal with this today:

What actually guarantees that your database diagram still reflects production?

Diagramas de banco sempre ficam desatualizados. Parei de tentar “manter” e passei a gerar.

Thiago Rosa da Silva — Sat, 21 Feb 2026 04:36:49 +0000

Diagramas de banco sempre ficam desatualizados. Parei de tentar “manter” e passei a gerar.
A maioria dos times começa com diagramas bonitos e bem pensados.
Alguns meses depois, eles viram referência histórica (quando não são ignorados por completo).

O problema não é falta de ferramenta nem falta de boa vontade.
É que diagramas mantidos manualmente não escalam com migrations, hotfixes e mudanças constantes.

Depois de passar por isso algumas vezes, mudei a abordagem:
em vez de “manter” diagramas, passei a gerá-los diretamente a partir do schema, tratando o banco como fonte única de verdade.

Isso acabou virando um projeto chamado ForgeSQL.
A ideia é simples: se o schema muda, o diagrama muda junto — de forma reproduzível, sem depender de IDE específica, screenshot ou disciplina heroica do time.

Ainda estou validando com quem vive banco no dia a dia, então queria ouvir da galera aqui:

Vocês ainda usam diagramas de banco?

Em que momento eles deixam de ser confiáveis?

O que faria um diagrama voltar a ser útil no projeto de vocês?

Se alguém quiser olhar o projeto: https://forgesql.com

Bank diagrams always become outdated. I stopped trying to "maintain" them and started generating them.

Thiago Rosa da Silva — Sat, 21 Feb 2026 04:27:01 +0000

Database diagrams always become outdated. I stopped trying to "maintain" them and started generating them.

Most teams start with beautiful and well-thought-out diagrams.

A few months later, they become historical references (when they aren't completely ignored).

The problem isn't a lack of tools or a lack of goodwill.

It's that manually maintained diagrams don't scale with migrations, hotfixes, and constant changes.

After going through this a few times, I changed my approach:

Instead of "maintaining" diagrams, I started generating them directly from the schema, treating the database as the single source of truth.

This ended up becoming a project called ForgeSQL.

The idea is simple: if the schema changes, the diagram changes along with it—in a reproducible way, without depending on a specific IDE, screenshots, or heroic team discipline.

I'm still validating with those who work with databases daily, so I wanted to hear from you guys here:

Do you still use database diagrams?

At what point do they cease to be reliable?

What would make a diagram useful again in your project?

If anyone wants to look at the project: https://forgesql.com

ForgeSQL: one diagram, real SQL, real Docker

Thiago Rosa da Silva — Fri, 20 Feb 2026 16:41:44 +0000

Most database diagrams don’t survive the first sprint.
SQL changes, Docker drifts, and the diagram becomes a lie.
That’s why I built ForgeSQL.
ForgeSQL lets you:
Design your database visually
Generate real SQL (Postgres, MySQL, SQL Server, Oracle)
Generate Docker Compose from the same model
Keep diagram, schema, and environment in sync
The diagram is the source of truth. Everything else is generated.
No PDFs. No outdated docs. No guessing.
If you’ve dealt with schema drift in real projects, this might help:
https://forgesql.com

Keeping Database Schema in Sync With Production

Thiago Rosa da Silva — Fri, 13 Feb 2026 19:36:40 +0000

One recurring problem in backend and data engineering workflows is this:

We design databases visually.
But we deploy them as SQL.

Somewhere between diagrams, migrations, CI/CD and Docker environments, things drift.

Over time:

The ER diagram no longer reflects production.
The production schema evolves through manual migrations.
Docker setups are maintained separately.
Version control contains SQL files, not the original intent of the model.

This disconnect is subtle at first. But in real systems, it becomes a source of confusion, onboarding friction, and architectural entropy.

Let’s unpack why this happens — and what alternative approaches might look like.

The Drift Problem

Most teams follow something like this workflow:

Initial schema modeled in a diagram tool.
SQL exported (or manually written).
Migrations handled via Flyway, Liquibase, Alembic, etc.
CI/CD pipelines apply migrations.
Docker environments configured separately.

After a few months:

The diagram is outdated.
Migrations reflect history, not structure.
Reconstructing the full schema requires replaying migration history.
Visual representation becomes documentation-only.

The visual model is no longer the source of truth.

The migration history is.

What Is the Real Source of Truth?

There are typically three candidates:

1. The Live Database

Reverse engineer from production.

Pros:

Always accurate (for that environment).

Cons:

Doesn’t represent intent.
Environment-specific.
Hard to reason about evolution.

2. Migration Files

Treat migrations as canonical.

Pros:

Fully versioned.
CI/CD friendly.
Production-aligned.

Cons:

Represents change history, not final structure.
Hard to visualize architecture from them.
Cross-dialect support becomes complex.

3. Declarative Schema Definition

Define structure once and generate artifacts.

Pros:

Structure-first.
Easier visualization.
Potentially dialect-agnostic.

Cons:

Requires strong validation.
Needs deterministic SQL generation.
Must integrate with migration workflows.

This third approach is less common in traditional relational tooling, but widely adopted in infrastructure-as-code philosophy.

Migration-First vs Structure-First

Most relational workflows are migration-first:

Change is primary. Structure is derived.

But what if we invert that?

Structure-first approach:

Define schema declaratively (or visually).
Generate deterministic SQL.
Generate migration diffs.
Generate container environment.
Version the schema definition itself.

Now the model becomes the artifact.

Migrations become derivative, not primary.

Multi-Dialect Reality

In modern environments, teams may:

Develop locally in PostgreSQL.
Use MySQL in staging.
Maintain compatibility layers.
Spin up ephemeral Docker environments per branch.

This creates a problem:

SQL dialect differences introduce fragmentation.

If the schema is defined abstractly, dialect-specific SQL can be generated consistently.

This reduces duplication and potential inconsistencies.

Docker as a Derived Artifact

Another common disconnect:

The database schema and Docker setup live in separate places.

But from a reproducibility standpoint:

Schema definition → should produce → runnable environment.

If the model knows:

Engine
Version
Extensions
Ports
Initialization SQL

Then generating Docker Compose becomes mechanical.

That reduces setup friction and onboarding time.

Treating Schema as a Versioned Artifact

What happens if we treat the schema definition file as:

The source of truth
Versioned in Git
Used to generate SQL
Used to generate Docker config
Used to derive migrations

Now we have:

Deterministic builds
Reproducible environments
Visual clarity
Single canonical representation

This aligns more closely with infrastructure-as-code principles.

But What About Migrations?

This does not replace migrations.

Instead:

Schema definition changes.
Diff is computed.
Migration SQL is generated.
Migration is reviewed.
CI/CD applies it.

The difference is:

Migrations are output of structural change — not the primary design interface.

An Experiment

I’ve been experimenting with this structure-first approach in a side project.

The idea is simple:

Model tables and relationships visually.
Generate SQL for PostgreSQL, MySQL, SQL Server or Oracle.
Structure the project ready for Git versioning.
Export Docker Compose to spin up the database instantly.

The goal isn’t to replace mature tools like Flyway or Alembic.

It’s to explore whether making the schema definition the central artifact reduces drift between design and production.

Open Questions

I’m genuinely curious how others handle this in real systems:

What do you consider the true source of truth?
How do you prevent diagram drift?
Do you rely entirely on migrations?
Would you trust deterministic SQL generation?
How do you handle multi-dialect environments?

If you’ve dealt with this in production, I’d love to understand your workflow.

The discussion itself is more valuable than any specific tool.

If you'd like to see the experiment I'm working on, it's called forgesql.com.
But more importantly, I’m interested in how teams solve this at scale.