🚀

dbdocs に入門してみた✨

2024/07/03に公開

PostgreSQL

dbdocs

tech

📕Overview

https://dbdocs.io/docs

dbdocs.ioは、あなたのデータベースのためのウェブベースのドキュメントを作成するための無料のシンプルなツールです。このガイドでは、5分もかからずにdbdocsをセットアップして使い始めることができます。

Databaseの設計書を作成してくれる便利なサービスです。Google, Githubでアカウントを作成すれば使えます。

🧷summary

1. Installation

前提条件インストールの前に、NodeJSとNPMがコンピュータにインストールされていることを確認してください。

ターミナル経由でdbdocsをインストールする

npm install -g dbdocs

dbdocsコマンドを実行して、すでにインストールされていることを確認し、いくつかのコマンドをプレビューする。

dbdocs

2. DBMLでデータベースを定義する

dbdocsを使うには、シンプルでオープンソースのDSL言語であるDBMLを使ってデータベーススキーマを定義します。DBML言語サポートパッケージがVisual Studio Codeに付属しているので、Visual Studio Codeを使うことをお勧めしますが、他のエディターでも同じように使えます。

VS Codeに拡張機能を追加

以下のようにdatabase.dbmlというファイルを作成するとします。

database.dbml

Project Ecommerce {
  database_type: 'PostgreSQL'
  Note: '''
    # Ecommerce Database
    **markdown content here**
  '''
}
Table users as U {
  id int [pk, increment]
  full_name varchar
  created_at timestamp
  country_code int
  note: "table 'users' contains user information"
}
Table merchants {
  id int [pk]
  merchant_name varchar
  country_code int [note: "country of merchant"]
  admin_id int [ref: > U.id]
  created_at datetime [default: `now()`, note: "created time"]
  note: "table 'merchants' contains merchant information"
}
Table countries {
  code int [pk]
  name varchar
  continent_name varchar
}
Table order_items {
  order_id int [ref: > orders.id]
  product_id int    
  quantity int [default: 1]
  note: 'items in an order'
}
Table orders {
  id int [pk]
  user_id int [not null, unique]
  status varchar
  created_at varchar [note: 'When order created']
}
Enum products_status {
  out_of_stock
  in_stock
  running_low [note: 'less than 20']
}
Table products {
  id int [pk]
  name varchar
  merchant_id int [not null]
  price int
  status products_status
  created_at datetime [default: `now()`]
  
  Indexes {
    (merchant_id, status) [name:'product_status']
    id [unique]
  }
}
Ref: U.country_code > countries.code  
Ref: merchants.country_code > countries.code
Ref: order_items.product_id > products.id
Ref: products.merchant_id > merchants.id

簡単なヒント：数行のコマンドで.sqlファイルを.dbmlに変換できます。

プロジェクト情報のノートはマークダウン構文をサポートしています。以下のような感じです：

Project first_project {
  database_type: 'PostgreSQL'
  Note: '''
    # Ecommerce Database
    **markdown content here**
  '''
}

ドキュメントはプロジェクト名と同じ名前になります。この例では、ドキュメント名はfirst_projectとなります。そうでない場合は、ステップ5でプロジェクト名を尋ねられます。

dbdocsビューを生成する前に、以下のコマンドを実行してログインする必要があります。

dbdocs login

Google or Github　で作成したアカウントでログインする。

Tokenが発行されているので、コピーしてターミナルに貼り付けて実行する。

4. Generate dbdocs view

ターミナルでdbmlファイルのあるフォルダを開き、以下のコマンドでdbdocsビューを生成する。

dbdocs build database.dbml

5. Check your database documentation!

プロジェクトを削除するには、remove コマンドを使用します。

dbdocs remove

🧑‍🎓thoughts

使ってみた感想。Databaseの設計書をコードベースで作成することができるのと、スキーマーの構造を可視化できるのが良かった。テーブル同士のリレーションも確認でき、画面をスクロールできるので、これは便利だなと思いました。最近仕事で、PostgreSQLを使う機会があるので、DB設計できるツールが使えると便利です。

参考になった記事