Minimal Modeling
Making sense of your database

Subscribe to the newsletter:,
or continue reading this page
Your database has grown organically. Like many companies nowadays, you use different database systems: relational, NoSQL, big data in the cloud, whatever.

There are hundreds of tables and thousands of columns in your system. There are multiple data migrations going on simultaneously.

The documentation is scarce.

Take a new engineer, or a new data scientist: how much time does their onboarding take? There must be a way to help them begin contributing faster than it happens now.

Even for the people who already work for the company: how long does it take them to understand a different project that they were assigned to?

I know, let's write some documentation!
At some point everyone tries documenting the database. Corporate wikis. Database schema visualization tools. ORM-based documentation. Google Docs. Custom-built web tools.

Typically, there are multiple attempts over the years.

For some reason, many such initiatives quickly lose traction. People just don't contribute, the documentation slowly becomes obsolete, the coverage is in single digits, the chosen tool is eventually abandoned.
Minimal Modeling approach
We use a simple logical modeling approach inspired by Anchor Modeling. We document the database by dissecting it into anchors, attributes and links, and also derived data and some textual narratives.

The resulting deliverable is conceptually a handful of spreadsheets and a number of documents. It could be maintained in any collaboration system that you use: Google Sheets and Google Docs, Notion, Confluence, Roam, Airtable, Markdown, you name it.

We accept the reality of your existing databases: we do not require any changes in your data storage system: no refactoring, no data migration, we're focused on describing and documenting it as it is.

Our approach is completely aligned with and compatible with all common approaches to database management: relational, NoSQL, schema-free, data warehousing, OLAP solutions, whatever.
Case study
“A modeling of a thousand columns begins with a single anchor.”
— Old Minimal Modeling proverb.
See how 400 database columns in 60 tables could be documented in 4 spreadsheets and as many narratives as you need. Spreadsheets and narratives are carefully designed for compounding incremental improvements.

Click here to see how a real-world database is documented in Minimal Modeling (in Notion).

Learning Minimal Modeling
Subscribe to the Minimal Modeling newsletter on Substack for updates.

We plan to do another run of Minimal Modeling course some time later in 2022. It's going to be eight two-hour Zoom sessions.

We’ll talk about stakeholders and their concerns. Then we’ll introduce a simple logical representation of data, and will use it as a foundation. Then we’ll discuss how logical representation turns into physical tables, and what drives the design of physical tables. Then we’ll introduce the idea of a data catalog, and we'll use it to discuss documenting; in particular, the difference between narrative and catalog. Finally, we’ll talk about extracting logical representation from the physical schema.

There will be two homework assignments. You will get a course cheatsheet at the end, to help you summarize what you’ve learned.

Subscribe to the Minimal Modeling newsletter on Substack for updates.
Implementing Minimal Modeling
We have a number of successful implementations of Minimal Modeling, with the following observed results:

First, you get an actually usable documentation of your databases.

Second, your people get a common vocabulary that lets different stakeholders to speak the same language.

Third, your database does not require any changes to introduce a Minimal Modeling. However, it may help you highlight some issues with the meaning of your data, and it will help you with the refactoring.

To get updates on Minimal Modeling, subscribe to our Substack newsletter:

Alexey Makhotkin is an independent researcher in the field of database modeling. He's been working with databases since 1996 in a number of roles.

Subscribe to the weekly Substack newsletter:

Follow on Twitter: @alexeymakhotkin
Made on