はじめに

既存データベース(MySQL)のテーブル定義書が必要になったので自動生成する方法を調べてみると MySQL のスキーマ定義を Markdown にして Wiki に貼るという記事を見つけました。ただ、BacklogのWikiに出力したかったので、見つけた記事を参考にBacklog記法へ変換してみました。

Railsなら

annotateとrdocの組み合わせ
schemadoc
rails-erd

とかでも良いかもしれません。(最後のはER図ですが)

xsltprocって何？

xsltproc is a command line tool for applying XSLT stylesheets to XML documents.

xsltproc user manual
xsltprocは、XMLドキュメントにXSLTスタイルシートを適応するためのコマンドラインツールらしいです。
XMLに関連するXSLTというスタイルシートがあるみたいですね。

XMLはデータの論理的な構造を記述するための言語ですから、XMLによって記述されたXML文書（以下XMLデータ）には、それがどんな体裁でWebブラウザや紙などに表示されるべきかを指示するレイアウト情報（スタイル情報）は含まれていません。
(中略)
XMLデータの構造変換を指定する部分を、独立した規格として取り出したのがXSLT（Extensible Stylesheet Language Transformations）です。

XSLTスタイルシートの基礎の基礎：XSLTスタイルシート書き方講座（1） - ＠IT
読んてみたところXMLを他のフォーマットに変換するために必要みたいですね。XMLをCSVやHTMLなどにも変換が可能なようです。昔はXMLで出力してるの流行ってたな...この記事も2001年のやつか。

手順

1. 必要なコマンドのインストール

$ sudo apt-get install xsltproc

Macとかだとデフォルトで入っているみたいですね。

2. 下記のコードをコピペし、「backlog_style.xsl」を用意します。

backlog_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="text" encoding="utf8"/>
<xsl:template match="database">
# contents
<xsl:apply-templates select="table_structure"/>
</xsl:template>
<xsl:template match="table_structure">
* <xsl:value-of select="@name"/>
|TBL物理名|TBL論理名（コメント）|h
|<xsl:value-of select="@name"/>|<xsl:value-of select="options/@Comment"/>|
- カラム情報
|物理名|データ型|NULL|デフォルト|キー|論理名（コメント）|Extra|h<xsl:apply-templates select="field"/>
- インデックス情報
|インデックス名|カラム|複合キー順序|NULL|UNIQ|h<xsl:apply-templates select="key"/>
</xsl:template>

<xsl:template match="field">
|<xsl:value-of select="@Field"/>|<xsl:value-of select="@Type"/>|<xsl:value-of select="@Null"/>|<xsl:choose><xsl:when test="@Default != ''"><xsl:value-of select="@Default"/></xsl:when><xsl:otherwise>n/a</xsl:otherwise></xsl:choose>|<xsl:choose><xsl:when test="@Key != ''"><xsl:value-of select="@Key"/></xsl:when><xsl:otherwise>n/a</xsl:otherwise></xsl:choose>|<xsl:choose><xsl:when test="@Comment != ''"><xsl:value-of select="@Comment"/></xsl:when><xsl:otherwise>n/a</xsl:otherwise></xsl:choose>|<xsl:choose><xsl:when test="@Extra != ''"><xsl:value-of select="@Extra"/></xsl:when><xsl:otherwise>n/a</xsl:otherwise></xsl:choose>|<xsl:text></xsl:text>
</xsl:template>

<xsl:template match="key">
|<xsl:value-of select="@Key_name"/>|<xsl:value-of select="@Column_name"/>|<xsl:value-of select="@Seq_in_index"/>|<xsl:choose><xsl:when test="@Null != ''"><xsl:value-of select="@Null"/></xsl:when><xsl:otherwise>NO</xsl:otherwise></xsl:choose>|<xsl:choose><xsl:when test="@Non_unique = '0'">YES</xsl:when><xsl:otherwise>NO</xsl:otherwise></xsl:choose>|<xsl:text></xsl:text>
</xsl:template>

</xsl:stylesheet>

3.下記のコマンドを実行します。

# mysqldumpコマンドをつかってXML形式でスキーマ情報を出力
$ mysqldump --no-data --xml app_development -u root -p > app.xml

# xsltprocコマンドをつかってXML形式からBacklog記法のテーブルテキストへ変換。設定ファイルは上記のものを使用。
$ xsltproc -o app.md backlog_style.xsl app.xml

4.下記のようなファイルが作成されます。

app.md

# contents

* schema_migrations
|TBL物理名|TBL論理名（コメント)|h
|schema_migrations||
- カラム情報
|物理名|データ型|NULL|デフォルト|キー|論理名（コメント）|Extra|h
|version|varchar(255)|NO|n/a|PRI|n/a|n/a|
- インデックス情報
|インデックス名|カラム|複合キー順序|NULL|UNIQ|h
|unique_schema_migrations|version|1|NO|YES|

5.上記をBacklogに貼り付け

完成！