Minimal Modeling case study: Mokum
Last post in this substack was sent five months ago. On February 24th, 2022 Russian military forces invaded the territory of Ukraine. I have many close friends in Ukraine. Speaking and writing has been hard since then, and it still is, five months later.
I’ve missed the weekly cadence of this substack. Many, many things happened in the past five months around database modeling here.
One thing that I did is the case study of a project that I’ve been closely involved with: Mokum.place, the social network. It’s a mid-size Rails application, it has ~60 tables with ~350 columns. How can we document it? How can we explain what data is stored there?
Minimal Modeling is an approach to making sense of the database and the data it contains. Today I just want to show you a deliverable of a real-world project. This is a work in progress: 25% of columns have been processed and represented in a structured form.
Read it here, as the Notion document: Minimal Modeling case study: Mokum. (I got a taste for Notion).
URL: https://mokumplace.notion.site/Case-study-Mokum-f2001712e8424acc9ed9b3d97e482a53.
On the main page you see the following sections:
1/ SQL schema: raw schema dump as a sequence of CREATE TABLE operators. We want to make sense of it.
2/ The Catalog, comprised of:
2a/ Anchors: also known by many names, including nouns and entities (e.g.: “User”);
2b/ Attributes: this is where the data is stored (e.g.: “What is the User’s date of birth?”);
2c/ Links: relationships between anchors, (e.g.: “User likes a Post”).
3/ Secondary data. The Catalog is a source of truth, but some database columns contain a different kind of data: derived, special or duplicated data values. We document them here.
4/ Graphical schema. This is a work in progress.
5/ Narratives. In the Catalog we’ve described each anchor, attribute and link independently from each other. But we also need a place for longer texts, where we can talk in more depth about this or that area of the database. This is this place. Narratives may refer to anchors, attributes, links; or explain physical implementation in terms of tables, columns, indexes, etc.
The first four sample narratives about Mokum are: “Basics”, “Realms”, “User and group names”, and “feed_calendars table”. They are representative of various kinds of texts that you can write to clarify the business and engineering decisions behind your database.
See how it all fits together: Minimal Modeling case study: Mokum.
This here is a hierarchical Notion document, and it’s great for demonstration purposes. Google Sheets and Google Docs would also work, and those may even be better suited to quickly make sense of a specific part of the database.