Super Easy Database Documentation Tool - "Prisma Markdown"

#opensource #development #database #typescript

Summary

prisma-markdown

Made a markdown documents generator for Prisma ORM

Very easy to use, but powerful documentation

Even non TypeScript/Prisma users are adapting it

Easy to develop, what about challenging with your stack?

Introduction

I've made an automatic markdown documents generator for Prisma about two months ago.

During the two months, I've introduced this library to my nearby developer friends, and some of them have recommended prisma-markdown to their companies. One thing amazing is, my near by developers are learning TypeScript and Prisma ORM, but their companies are not. Their companies are not using neither TypeScipt and Prisma ORM, but utilizing prisma-markdown only for the effective documentation.

Listening their interesting stories, and understanding the power of this documentation feature, I've decided to introduce my prisma-markdown as "The World Best (Relational) Database Documentation Tool". Here is the example document generated by prisma-markdown. If you click the below link, then you may understand how prisma-markdown is powerful.

Example markdown document generated by prisma-markdown

Setup

At first, install NPM package.

npm i -D prisma-markdown

At next, add the generator to the schema file.

generator markdown {
  provider = "prisma-markdown"
  output   = "./ERD.md"
  title    = "Shopping Mall"
}

/// Description comments...
///
/// @namespace Articles
/// @author Samchon
model bbs_articles { ... }

/// Description comments...
///
/// @namespace Articles
/// @author Samchon
model bbs_article_comments { ... }

At last, run below command, than ERD.md file would be generated.

npx prisma generate

Comment Tags

If your database has over hundreds of models, none of automatic ERD generators can express them perfect. In that case, prisma-markdown recommends you to separate hundreds of models to multiple paginated diagrams by using /// @namepsace <name> comments.

When you write /// @namepsace <name> comment on models, they would be separated to proper sections of markdown document. For reference, you can assign multiple @namepsaces to a model, and if you do not assign any @namepsace to a model, it would be assigned to default tag.

Also, if you use @erd <name> instead of @namespace <name>, target model would be expressed only at ERD. It would not be appeared to the markdown content section. Otherwise, @describe <name> tag will show the model only at markdown content section, not at ERD.

@namespace <name>: Both ERD and markdown content
@erd <name>: Only ERD
@describe <name>: Only markdown content
@hidden: Neither ERD nor markdown content
@minItems 1: Mandatory relationship when 1: N (||---|{)

/// Both description and ERD on Actors chatper.
///
/// Also, only ERD on Articles and Orders chapters.
///
/// @namespace Actors
/// @erd Articles
/// @erd Orders
model shopping_customers {}

/// Only description on Actors chapter.
///
/// @describe Actors
model shopping_customer_login_histories {}

/// Only ERD on Articles chapter.
///
/// @erd Articles
model shopping_sale_reviews {}

/// Never be shown.
///
/// @hidden
model shopping_sale_hits {}

Additionally, when defining 1: N relationship, you can specify the N position to be whether optional or mandatory. If you want to configure the N position to be mandatory, just write the @minItems 1 comment tag. Otherwise the N position is optional, you don't need to do anything.

model shopping_sale_units {
    /// @minItems 1
    stocks shopping_sale_snapshot_unit_stocks[];
    options shopping_sale_snapshot_unit_options[]; // optional
}
model shopping_sale_snapshot_unit_stocks {}
model shopping_sale_snapshot_unit_options {}

Secret of `Prisma-Markdown`

Prisma provides metadata API of schema file, and prisma-markdown is utilizing the API.

Therefore, about the ERD (Entity Relationship Diagram), prisma-markdown analyzes tables written in the prisma schema file, and explores relationships of them. After the analses and expeditions, prisma-markdown draws the diagrams through mermaid erDiagram grammer.

About the descriptions, prisma-markdown utilizes the description comments written in the prisma schema file directly. prisma-markdown just copies and pastes those description comments into the output markdown document, with special comment tags' parsing.

As you can see, developing prisma-markdown was not such hard, and the first version just be completed only in two days. As Prisma provides metadata API, I did not need to design the AST (Asymmetric Syntax Tree) API. Also, due to the mermaid erDiagram grammer, I did not need to implement the geometric programming.

I think that this approach would work for other languages and ORM libaries as well. As I'm a backend developer using TypeScript and Prisma, I have no intention of creating something like prisma-markdown based on another language or ORM. However, if you're one of them, how about challenge it with your stack? I think it would be great contribution for your stack/ecosystem.

Next Episode Preview

At next, I'll write educative articles that how to design relational database.

The first step would be shopping mall system, and will advance to the github (or google drive) imitated system and academic system as next steps. I will show you how to normalize and design DB through practical use case. Look forward to it.

For reference, about the shopping mall system, you can directly look at its document just by clicking the below link.