Super Easy Database Documentation Tool - "Prisma Markdown"
Tags: opensource, development, database, typescript
Published: 2023-11-24 12:32:48

> ## Summary
> - [`prisma-markdown`](https://github.com/samchon/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](https://www.prisma.io) 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.

  - [Github Repository](https://github.com/samchon/prisma-markdown)
  - [Generated Markdown Example](https://github.com/samchon/prisma-markdown/blob/master/ERD.md)
  - [Target Prisma Schema File](https://github.com/samchon/prisma-markdown/blob/master/schema.prisma)

[![prisma-markdown-example](https://github.com/samchon/prisma-markdown/assets/13158709/80ca9c8e-4c96-4deb-a8cb-674e9845ebf6)](https://github.com/samchon/prisma-markdown/blob/master/ERD.md)

> [Example markdown document](https://github.com/samchon/prisma-markdown/blob/master/ERD.md) generated by [`prisma-markdown`](https://github.com/samchon/prisma-markdown)




## Setup
At first, install NPM package.

```bash
npm i -D prisma-markdown
```

At next, add the generator to the schema file.

```prisma
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`](https://github.com/samchon/prisma-markdown/blob/master/ERD.md) file would be generated.

```bash
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 `@namepsace`s 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** (`||---|{`)

```prisma
/// 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 {}
```

![Mandatory Relationship](https://github.com/samchon/prisma-markdown/assets/13158709/b382cf64-5047-4a00-b77f-7c3427010090)

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.

```prisma
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-markdown-example](https://github.com/samchon/prisma-markdown/assets/13158709/80ca9c8e-4c96-4deb-a8cb-674e9845ebf6)](https://github.com/samchon/prisma-markdown/blob/master/ERD.md)

  - [Generated Markdown Example](https://github.com/samchon/prisma-markdown/blob/master/ERD.md)
  - [Target Prisma Schema File](https://github.com/samchon/prisma-markdown/blob/master/schema.prisma)

[Prisma](https://www.prisma.io) 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](https://mermaid.js.org/syntax/entityRelationshipDiagram.html).

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](#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](https://www.prisma.io) provides metadata API, I did not need to design the AST (Asymmetric Syntax Tree) API. Also, due to the [mermaid erDiagram grammer](https://mermaid.js.org/syntax/entityRelationshipDiagram.html), 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.

1. [Shopping Mall System](https://github.com/samchon/prisma-markdown/blob/master/ERD.md)
2. Github and (Google Drive) imitated System
3. Academic System