CircleCIとSchemaSpyを使ったMySQLドキュメントの自動生成

CircleCI ユーザーコミュニティミートアップ #9 2022年4月21日 CircleCIを使った MySQL DBドキュメント自動生成

Twitter: 蟒蛇（「ウワバミ」と読みます） @uwabami_garden CI歴 2.5年、うちCircleCI歴 2年その割に去年から新入社員研修でCICDを担当している最近会社のCircleCI Serverが3.xに更新されたことで、研修資料が大幅作り直しになり嬉し泣きしている
自己紹介

開発していると、しばしばDBのスキーマを変更することがある DDLは適当に実行すると事故になるので、実行にはフローがあるスキーマ変更の運用

DDL作成チェック実行ドキュメント更新

DDL作成チェック実行ドキュメント更新 TOIL

スキーマがバージョン管理されていない DDLのチェックとスキーマ定義書の更新がTOILになっている解決したいフローの課題

スキーマがバージョン管理されていない →マイグレーションツールを導入してGit管理 DDLのチェックとスキーマ定義書の更新がTOILになっている →CircleCIで自動実行フローの課題

DDL作成自動チェック実行ドキュメント自動更新

マイグレーション

マイグレーションツールの導入 dbmate(https://github.com/amacneil/dbmate) RDBや開発言語に依存しないSQLベースのマイグレーションツール導入当初のスキーマを出発地点として、マイグレーションしていく

スキーマチェック

チェック項目は大きく分けて3つに分類される - 業務知識が必要なチェック - ex. 入れたいデータとデータ型が適合しているか - DDLだけで機械的に判別可能なチェック - ex.
インデックスコメントがあるか - 機械的に判別可能だがDDLだけでは判断できないチェック - ex. インデックスの重複スキーマチェック項目の分類

チェック項目は大きく分けて3つに分類される - 業務知識が必要なチェック（手動でやる） - ex. 入れたいデータとデータ型が適合しているか - DDLだけで機械的に判別可能なチェック（自動化） - ex.
インデックスコメントがあるか - 機械的に可能だがDDLだけでは判断できないチェック（自動化） - ex. インデックスの重複スキーマチェック項目の分類

tbls(https://github.com/k1LoW/tbls) - 「インデックスにコメントをつける」などチェックできる - 本来はDBドキュメントの生成ツール - linterとして使っているが、ER図の自動生成機能などもある DDLだけで機械的に判別可能なチェック

pt-duplicate-key-checker(https://www.percona.com/doc/percona-toolki t/LATEST/pt-duplicate-key-checker.html) - Percona Toolkitに含まれるツール - インデックスの重複を指摘してくれる - 重複インデックスがあっても戻り値は0なので、テストをfailさせたい場合は工夫が必要
インデックス重複チェック

ドキュメント生成

SchemaSpy(https://schemaspy.org/) - 自動的にテーブル一覧やER図を生成してくれる - tblsでもドキュメント生成はできるが、ArtifactsからHTMLを直接表示できたほうが都合が良かったので採用ドキュメントの作成

CircleCIでの実行フロー

Gitにpush ↓ 初期状態（dbmate導入直前）のスキーマファイルインポート ↓ dbmateでマイグレーション ↓ tbls, pt-duplicate-key-checkerでチェック ↓ SchemaSpyでドキュメント生成
実行フロー

ArtifactsにあるドキュメントをPRでチェックする mainにマージするとS3にも保存され、CloudFront経由で表示 CloudFront上にあるドキュメントを正として扱う自動で生成されるので忘れない生成されたドキュメントの保存

S3を更新するには当然AWS認証が必要せっかくなのでOIDCを活用したいが、CircleCI Serverにはまだない😢 実運用では涙を飲んでAPIキーを使っていますが、この発表用のデモリポジトリではOIDC認証になっています OIDC認証?

SchemaSpy出力: https://schemaspy.venom.blue/ コードサンプル: https://github.com/bateleurX/dbmate_migration Sakila Sample Databaseを例に実際にCIフロー実装とスキーマドキュメントを生成していますサンプルコードはGNU Affero
General Public Licenseで公開していますサンプル集

DBドキュメントの更新はCIを使うと便利 DDLレビューも機械的な項目はCIでやろう CircleCI ServerのOIDC対応待ってますまとめ

CircleCIとSchemaSpyを使ったMySQLドキュメントの自動生成

CircleCIとSchemaSpyを使ったMySQLドキュメントの自動生成

MATSUURA, yosuke

More Decks by MATSUURA, yosuke

Other Decks in Technology

Featured

Transcript

CircleCI ユーザーコミュニティミートアップ #9 2022年4月21日 CircleCIを使った MySQL DBドキュメント自動生成

開発していると、しばしばDBのスキーマを変更することがある DDLは適当に実行すると事故になるので、実行にはフローがあるスキーマ変更の運用

DDL作成チェック実行ドキュメント更新

DDL作成チェック実行ドキュメント更新 TOIL

スキーマがバージョン管理されていない DDLのチェックとスキーマ定義書の更新がTOILになっている解決したいフローの課題

スキーマがバージョン管理されていない →マイグレーションツールを導入してGit管理 DDLのチェックとスキーマ定義書の更新がTOILになっている →CircleCIで自動実行フローの課題

DDL作成自動チェック実行ドキュメント自動更新

マイグレーション

マイグレーションツールの導入 dbmate(https://github.com/amacneil/dbmate) RDBや開発言語に依存しないSQLベースのマイグレーションツール導入当初のスキーマを出発地点として、マイグレーションしていく

スキーマチェック

チェック項目は大きく分けて3つに分類される - 業務知識が必要なチェック - ex. 入れたいデータとデータ型が適合しているか - DDLだけで機械的に判別可能なチェック - ex.

チェック項目は大きく分けて3つに分類される - 業務知識が必要なチェック（手動でやる） - ex. 入れたいデータとデータ型が適合しているか - DDLだけで機械的に判別可能なチェック（自動化） - ex.

tbls(https://github.com/k1LoW/tbls) - 「インデックスにコメントをつける」などチェックできる - 本来はDBドキュメントの生成ツール - linterとして使っているが、ER図の自動生成機能などもある DDLだけで機械的に判別可能なチェック

ドキュメント生成

SchemaSpy(https://schemaspy.org/) - 自動的にテーブル一覧やER図を生成してくれる - tblsでもドキュメント生成はできるが、ArtifactsからHTMLを直接表示できたほうが都合が良かったので採用ドキュメントの作成

CircleCIでの実行フロー

Gitにpush ↓ 初期状態（dbmate導入直前）のスキーマファイルインポート ↓ dbmateでマイグレーション ↓ tbls, pt-duplicate-key-checkerでチェック ↓ SchemaSpyでドキュメント生成

ArtifactsにあるドキュメントをPRでチェックする mainにマージするとS3にも保存され、CloudFront経由で表示 CloudFront上にあるドキュメントを正として扱う自動で生成されるので忘れない生成されたドキュメントの保存

S3を更新するには当然AWS認証が必要せっかくなのでOIDCを活用したいが、CircleCI Serverにはまだない😢 実運用では涙を飲んでAPIキーを使っていますが、この発表用のデモリポジトリではOIDC認証になっています OIDC認証?

SchemaSpy出力: https://schemaspy.venom.blue/ コードサンプル: https://github.com/bateleurX/dbmate_migration Sakila Sample Databaseを例に実際にCIフロー実装とスキーマドキュメントを生成していますサンプルコードはGNU Affero

DBドキュメントの更新はCIを使うと便利 DDLレビューも機械的な項目はCIでやろう CircleCI ServerのOIDC対応待ってますまとめ