dbdocs を試す
kwnDB設計のドキュメントを運用していく良い方法を探して辿り着いた
kwnDBML
dbdocsの前にそもそもDBMLを知らなかった。DBMLファイルをGitで管理すれば、差分も見やすいしプルリクを使ってレビューできるので良さそうだと思った。
DBML (Database Markup Language) is an open-source DSL language designed to define and document database schemas and structures. It is designed to be simple, consistent and highly-readable.
kwn公式サイトにあるサンプル
kwnGetting Started
2023年12月10日時点でのGetting Startedをやってみる。環境は以下の通り。
- macOS Ventura 13.1
- node v20.9.0
- Visual Studio Code 1.84.2
Installation
1. Install dbdocs via terminal
dbdocsをインストールする。
npm install -g dbdocs
インストールされていることを確認する。
dbdocs
自分の環境での結果は以下の通り。
VERSION
dbdocs/0.8.4 darwin-x64 node-v20.9.0
USAGE
$ dbdocs [COMMAND]
COMMANDS
build build docs
help Display help for dbdocs.
login login to dbdocs
logout logout
ls list projects
password set password for your project or remove password
remove remove project
rename change your username
token generate or revoke your authentication token
validate validate docs content
2. Define your database with DBML
database.dbmlを作成する。ついでにVisual Studio Codeの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
3. Login to dbdocs
dbdocsにログインする。
dbdocs login
以下のように何でログインするか聞かれる。自分はメールアドレスで認証した。
? Choose a login method:
1) Email
2) GitHub/Google
Answer:
4. Generate dbdocs view
DBMLファイルをビルドする。これでWeb上に反映されるのでビルド＆デプロイという感じ。
dbdocs build ./database.dbml
5. Check your database documentation!
ビルドするとURLが表示されるので、アクセスするとDBMLファイルの内容をWeb上でドキュメントとして見ることができる。
Remove your project
今回使ったプロジェクトを削除する。
dbdocs remove Ecommerce
URLの構造
https://dbdocs.io/{アカウント名}/{プロジェクト名}
プロジェクト名はDBMLファイルのProject xxx { ...のxxxの部分
kwnPassword Protection
プロジェクトにパスワードを設定できるのでやってみる。ちなみに有料プランだとプライベートなプロジェクトが作れるらしい。
Set Password
パスワードを設定する。
dbdocs password --set <password> --project <project name>
アクセスするとこうなる。
Remove Password
パスワードの設定を削除する。
dbdocs password --remove --project <project name>
CI Integration
GitHub Actionsを使ってCIをやってみる。
自動でログインするためにトークンを生成する。生成したトークンは再確認することができないのでメモしておく。
dbdocs token -g
Repository secretsにトークンを追加する。
リポジトリ作って以下ワークフローを試してみたらビルドできた。ワークフローは公式ドキュメントのサンプルをベースに書いた。実際に運用することを考慮したワークフローになるように随時アップデートしていきたい。
kwn一旦試したいことは試せたのでクローズする。使ってみた感じ大きな不満もなく好印象。DB設計のドキュメント運用について他に良さそうな案も現状ないので使っていきたい。