運用されている環境は存在するけど、改めて言われるとドキュメンテーションが全然されていない、みたいな環境へのお話。
データベース定義書っぽいものを作る
最低限言い訳の出来る形式に整形して用意したいが、そんなもん作っているひまはねえ！ みたいな時に。 xsltproc を利用して作成します。
Windows 環境の人は素直に A5:SQL で出力した方が良い気もする。
テーブル定義を出力する
いわゆる SHOW CREATE TABLE ... みたいな出力を XML で取得する。
以下のようにすることで、 mysqldump 経由で定義だけ XML 出力が行える。
❯ mysqldump --no-data --xml -u ${USERNAME} -p ${DATABASE} > ~/Workspace/tmp/sample.xml
xsltproc 整形用のスタイルを用意する
これは有志が公開してくれている。 が、コメント記述されていることが前提となっていたので、自分でちょっと編集した。
オリジナルは文末の参考リンク先を。
style.xsl
<?xml version="1.0" encoding="utf8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:s="http://sqlfairy.sourceforge.net/sqlfairy.xml"> <xsl:output method="html" encoding="utf8" doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"/> <xsl:template match="database"> <html lang="ja"> <head> <meta charset="utf-8"/> <title>テーブル定義</title> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css"/> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap-theme.min.css"/> <style> table.htable { margin: 3em auto 1em auto !important; } table.htable th { border-left: 10px solid #e5e5e5 !important; } footer { border-top: 1px solid #e5e5e5; padding: 0.5em; } </style> </head> <body> <div class="container"> <h1 class="page-header">テーブル定義</h1> <xsl:apply-templates select="table_structure"/> </div> <footer class="text-center"> your company </footer> </body> </html> </xsl:template> <xsl:template match="table_structure"> <table class="table table-bordered htable"> <tbody> <tr class="active"> <th width="200px">テーブル名</th> <td><xsl:value-of select="@name"/></td> </tr> <tr class="active"> <th width="200px">コメント (補記)</th> <td><xsl:value-of select="options/@Comment"/></td> </tr> </tbody> </table> <table class="table table-condensed"> <thead> <tr> <th class="text-right">#</th> <th>カラム名</th> <th>型</th> <th>NULL</th> <th>デフォルト値</th> <th>主キー</th> <th>ユニーク</th> <th>コメント</th> </tr> </thead> <tbody> <xsl:apply-templates select="field"/> </tbody> </table> </xsl:template> <xsl:template match="field"> <tr> <td class="text-right"><xsl:value-of select="position()"/></td> <td><xsl:value-of select="@Field"/></td> <td><xsl:value-of select="@Type"/></td> <td><xsl:if test="@Null='YES'"><span class="glyphicon glyphicon-ok"></span></xsl:if></td> <td><xsl:value-of select="@Default"/></td> <td><xsl:if test="@Key='PRI'"><span class="glyphicon glyphicon-ok"></span></xsl:if></td> <td><xsl:if test="@Key='UNI'"><span class="glyphicon glyphicon-ok"></span></xsl:if></td> <td><xsl:value-of select="@Comment"/></td> </tr> </xsl:template> </xsl:stylesheet>
人間が可読化しやすいよう整形して HTML に整形する
以下のコマンドで XML を整形できる。
❯ xsltproc -o sample.html style.xsl ~/Workspace/tmp/sample.xml
備考
html だと困る場合はなにかしらの変換系ツールを噛ませるか、それこそブラウザから確認ついでに PDF 出力してしまえばいい。
A5:SQL で出力するものの劣化、という感じで、コマンドベースで出力できる以外の利点はあんまりない。 ので、これは開発とか CI で PR 単位ごとに実行する、とかそういう「いざ作れと言われたら面倒だけど、用意しておく分には初回の苦労以外はまあ」という感じのあったら嬉しい系として運用するのがよさそう。
実際 CI やってるならテスト用のデータベースあると思うので、そちらを対象に実行すればいいし、という感じ。 ほならワークフローを作れ、と言われたらそれはそうなんだけども。
