$ pnpm install
-
Homebrewでtbldツールをインストール
$ brew install k1LoW/tap/tbls
-
パッケージインストール
$ pnpm install
-
Docker起動
$ docker-compose up -d
- Dockerでtbls docを実施することも可能だが、現在は無効にしている。
-
マイグレーションファイル作成(更新がある場合のみ)
$ pnpm db-generate
-
DBマイグレーション
$ pnpm db-migrate
-
Github Actionsのworkflow permissionsを更新 (Github ActionsからCommit & pushできるように)
-
Github Actionsでtblsドキュメントを自動更新し、PRのコメントに詳細を記載
-
PRをdevelopにmerge
-
developでPRを作り、mainにmerge
-
作業終了後) Docker終了
$ docker-compose down
-
rootフォルダに
.actrc
を新規作成し、以下設定-P mysql:8.0=mysql:8.0 -s GITHUB_TOKEN=XXXX
-
pnpm tbls-act
実施tbls-doc-local.yml
ファイルで記載されたアクションが実施され、docs/dbdoc/act-local
にtblsファイルが生成される。
- Databaseのスキーマを基に自動でDocumentationを作成するツール
- 主なtblsコマンド
tbls doc
: Databaseのスキーマ情報をベースにドキュメントを作成tbls diff
: Databaseのスキーマ情報と現在のtbls docファイルの差分を表示
- 必要なファイル
.tbls.yml
: configファイル。DSN(Database Source Name)やファイルの出力先を設定。ViewpointやCommentなどを設定できる。
- tblsでできること
- Viewpoint: データベースのスキーマに対する特定の視点やフィルタリングを設定・管理
- Comment: テーブルやカラムにコメントを記載
- Label: ラベル付
- Lint: スキーマ定義に対するLintの設定
- ある程度のカスタマイズはできるが、schemaspyほどの機能はない?(例: Anoalisで不整合テーブル検出など?)
- Github ActionsでCI/CDを実施することは可能だが、DBをCloud SQLで管理していることを考えると、Cloud Buildのプロセスにtbls docを含めた方が効率的?(Github actionsだとイベントリスナーでCloud Buildのmigration完了をListenした上で、Actions workflowを開始するする必要あり?)
- 例1)
cloudbuild.yaml
でmigrationファイルに変更があったら、Cloud SQL Auth Proxy実施=>migration実行=>データベース更新=>tbls doc更新- ただし、Build内で直接DBを更新するのはリスクがある?
- 例2)
cloudbuild.yaml
でmigrationファイルに変更があったら、Cloud SQL Auth Proxy実施=>別のDBに反映=>それを本番のDBに反映
- 例1)
- tbls公式Doc
- tbls と GitHub Actions を使ったスキーマ情報を管理する仕組みについて検証しました
- ドキュメント整備のためにtblsを導入してみた話
- DBスキーマはtblsのViewpointsで整理しよう
- 2024/04/23 tbls活用事例 〜 ビューポイントから データベースを整理してみた話 〜
- tblsとGitHub Actionsを使ってDBマイグレーションを含むPRには自動更新したER図を追加する
- v06 The future of tbls and Documentation as Code
- tblsを使って db schema document作成自動化
- tblsのViewPoint機能を用いたGithub Actions上でのDBドキュメントの自動生成(mkdocs使用)
-
(Java 8のインストール)[https://www.java.com/ja/download/]
-
(Graphvizのインストール)[https://www.graphviz.org/download/]
$ brew install graphviz
-
(JDBCドライバのダウンロード)[https://www.mysql.com/products/connector/]
JDBC Driver for MySQL (Connector/J)
>Platform Independent
を選択- ダウンロードしたjarファイルを
mysql-connector-j-9.0.0
を対象ディレクトリに格納
-
(Schemaspy Jarfileのダウンロード)[https://github.com/schemaspy/schemaspy/releases]
- 最新versionのjarファイルを対象ディレクトリに格納
java -jar ./schemaspy-6.2.4.jar \
-t mysql \
-dp ./mysql-connector-j-9.0.0.jar \
-db parking_app \
-host localhost \
-port 3306 \
-s parking_app \
-u root \
-o ./output \
-hq /opt/homebrew/bin/dot \
-imageformat svg \
-imagefontadjust true
- Graphviz rendererについて以下のようなエラーが多く発生するが、無視して良さそう。((根拠 from Github issues)[schemaspy/schemaspy#833])
.ERROR - dot ~~ Warning: cell size too small for content
-
schemaspy.properties
で設定情報を記載=>$ java -jar ./schemaspy-6.2.4.jar \ -configFile schemaspy.properties
を実行 -
以下のようなエラーが発生する。Javaランタイムが認識するクラスファイルバージョンが古いのが原因。Versionを11に変えれば解消するようだが、まだ解決できていない。
Caused by: java.lang.UnsupportedClassVersionError: org/openjdk/nashorn/api/scripting/NashornScriptEngineFactory has been compiled by a more recent version of the Java Runtime (class file version 55.0), this version of the Java Runtime only recognizes class file versions up to 52.0
- 未着手
- Databaseのスキーマを基に自動でDocumentationを作成するツール
- Javaベース
- 各テーブル、及びそのER図をサイトとして一覧できる。
- Anomaliesで不整合なテーブルを検出できる。
- Orphan Tablesで他テーブルとのRelationがないものを検出できる。
- Searchでテーブルレベル、テーブル内のカラムレベルの検索が可能。
- 各テーブル・カラムに対するコメントの記載や、テーブルをカテゴライズなどのカスタマイズがしにくい?
- index.htmlを参照するためには、github pagesなどを使用する必要がある。ただし、github pagesはpublicでないとサイトを公開できない。Private公開&内部でのみサイトを公開するためには、Github Enterpriseを使用する必要がある?
- 公式ドキュメント
- Github
- SchemaSpyを使ってER図を自動で作る
- Specifying the renderer from schemaspy's issue
- (MacでスタイリッシュなER図を作成する(Oracle))[https://qiita.com/uhooi/items/83e70e32d5bd7f12af8a#jdbc%E3%83%89%E3%83%A9%E3%82%A4%E3%83%90%E3%81%AE%E3%83%80%E3%82%A6%E3%83%B3%E3%83%AD%E3%83%BC%E3%83%89] *Create MS SQL Database documentations using SchemaSpy
- SchemaSpyでデータベースのドキュメントを生成してみた
- docker compose 上で SchemaSpy が動かないのを直す (MySQL 8, Apple M1 Mac)
- SchemaSpyを使ってER図を自動で作る
- SchemaSpyを使ってデータベースの中身をまとめたかった
-
仮想環境 (venv) を設定
$ python3 -m venv venv $ source venv/bin/activate $ pip install mkdocs-material $ mkdocs new . $ mkdocs serve //2回目以降はserveのみでOK
- 使用終了時に、
$ deactivate
して仮想環境も終了する。
- 使用終了時に、
-
mkdocs.yml
(1で自動生成)でカスタマイズ- 多言語設定可能
$ pip install mkdocs-static-i18n
インストール- i18nプラグイン設定必要
- docs傘下の特定のフォルダをbuildの除外に設定
- a)
$ pip install mkdocs-exclude
- b)
mkdocs.yml
のpluginで設定
- a)
- Version管理
- a)
$ pip install mike
- b)
mkdocs.yml
のpluginで設定 - c)
$ mike deploy --push --update-aliases [version] latest
で指定のversionをデプロイ - d)
$ mike serve
=>http://localhost:8000/version/
にアクセス => versionタブで各versionに移動可能 - e) Github Actions用のymlファイル作成 + Github Pagesの設定を変更
- a)
- 多言語設定可能
-
mkdocs serve
でローカル環境でサイトアクセス可能 -
mkdocs build
でサイトビルド -
Github actionsでGithub pagesにデプロイ (
.github/workflows/mkdocs-generate.yml
)
- Pythonベースで実装されるドキュメントサイトを生成するための静的サイトジェネレーター
- Markdown形式のファイルを読み込み、ドキュメントを生成
- テーマや多言語設定、Nav・サイドバーなどカスタマイズが可能
- docs直下フォルダが一つのセクションとみなされ、タブになる。1フォルダ = 1セクションでシンプル。
- 多分、Version管理もできる。こちら
- Markdown言語しだけでなく、HTMLファイルも認識する。(Path指定してリンクからアクセス可能/ ビルド後にスタイルが消える問題が発生中)
- MKDocs
- MkDocs + plugin : mkdocs-static-i18n で多言語対応サイトを構築する
- my-mkdocs-mike in github
- mkdocs-static-i18n in github
- MkDocsによるドキュメント作成
- Material for MkDocs
- mkdocsをMacにインストールする。
- MkDocs Installation
- MkDocsによるドキュメント作成
- rails-schemaspy-example in github
- mkdocs-material-youtube-tutorial in github
- How To Create STUNNING Code Documentation With MkDocs Material Theme in Youtube
- MkDocs で .git や node_modules など指定ディレクトリを exclude(除外) したい
- MkDocs+Read the Docsで面倒なWordのドキュメント管理から抜け出す
- Setting up versioning (公式Doc)
- Docs versioning: Docusaurus and MkDocs
- mike in github
- How does Material for MkDocs fetch the latest git tag (to display it in the navbar)? in github discussion
- Using Git Information
- Github Pagesの公開ページの版管理(MkDocs plugin mike利用)
- 限定公開可能?