2016.07.07 2022.10.28

RailsでDB定義書を自動生成

mmmuser

とあるプロジェクトでデータベースのテーブル定義書を作成する必要があったのですが、変更がある度に手動でドキュメントを修正するのは大変面倒なため、自動生成することにしました。
Rails の migration を使って管理しているテーブル群(MySQL)の定義書を PDF で出力するまでのフローを紹介します。
この記事の通りに作成すると以下の様式の定義書になりますが、お好きなようにデザインを変更することもできます。詳細は後述。

Contents

全体の流れ
まとめ

全体の流れ

rake db:migrate でテーブルを作成/変更する
DBのスキーマ構造を XML 形式で出力する
XML を HTML に変換する
HTML を PDF に変換する

の大きく4つの手順で定義書を出力します。

1. rake db:migrate でテーブルを作成/変更する

この部分は普段の通りに migration ファイルを記述するだけなのですが、上部サンプルの定義書にあるようにカラムの論理名が必要な場合には、 migration_comments という gem を使います。
以下のように migration ファイルを書くと論理名も記述することができます。

class CreateUser < ActiveRecord::Migration
  def change
    create_table :users do |t|
      t.string :name,     null: false, default: 'No Name', comment: 'ユーザ名'
      t.string :email,    null: false,                     comment: 'メールアドレス'
      t.string :password, null: false,                     comment: 'パスワード'
      t.integer :age,                                      comment: '年齢'

      t.timestamps null: false
    end
    add_index :users, :email, unique: true
    set_table_comment :users, "ユーザ"
    set_column_comment :users, :id, "ユーザID"
  end
end

レコードIDとテーブル名は set_table_comment や set_column_comment を使って別途定義をしています。

2. DBのスキーマ構造を XML 形式で出力する

MySQL の場合には mysqldump コマンドの --no-data --xml オプションでスキーマ情報だけを XML 形式で出力できるため、これを使用します。

3. XML を HTML に変換する

xsltproc というツールを使うと

$ xsltproc -o schema.html style.xsl schema.xml

で XML を HTML に変換することができます。XSL は聞いたことがなかったのですが、Extensible Stylesheet Language の頭文字で、XML の変換を行うためのスタイルシート技術のようです。
長くなるのでここには記載しませんが、サンプル定義書で使用した XSL は Gist showwin/db_schema_style.xsl に上げたので必要な方はこちらもご覧ください。

4. HTML を PDF に変換する

wkhtmltopdf というツールを使うと

$ wkhtmltopdf schema.html schema.pdf

で HTML から PDF に変換できるのですが、Ubuntu の場合だと wkhtmltopdf: cannot connect to X server とエラーが出てしまうので

$ xvfb-run -a -s "-screen 0 1024x768x24" wkhtmltopdf schema.html schema.pdf

とすると良いです。ついでに fonts-ipafont を入れておくとフォントが綺麗になって幸せになれます。

手順まとめ

Rails + MySQL + Ubuntu な環境での手順まとめです。
違う環境のかたは適宜対応してください。

必要なツールをインストールします。

$ apt-get install xsltproc xvfb wkhtmltopdf fonts-ipafont

Gemfile に追加します。

gem 'migration_comments'

migration ファイルを記述します。

Rakefile に rake db:migration コマンドにフックして2,3,4の処理が実行されるように記述します。中間生成物は home_path/* に出力して、最終成果物のDB定義書は doc/schema.pdf に出力する例です。style.xsl を事前においておくことを忘れないようにしましょう。

task :create_schema_doc do
  home_path = 'path/to/somewhere'
  # schema の構造を XML 形式で出力
  `mysqldump -u $RAILS_DATABASE_USERNAME -p$RAILS_DATABASE_PASSWORD -h $RAILS_DATABASE_HOST --no-data --xml $RAILS_DATABASE_NAME > #{home_path}/schema.xml`
  # XML を HTML に変換
  `xsltproc -o #{home_path}/schema.html #{home_path}/style.xsl #{home_path}/schema.xml`
  # HTML を PDF に変換
  `xvfb-run -a -s "-screen 0 1024x768x24" wkhtmltopdf #{home_path}/schema.html doc/schema.pdf`
end

Rake::Task['db:migrate'].enhance do
  Rake::Task[:create_schema_doc].invoke
end

そして、、

$ rake db:migrate

でPDFなDB定義書の完成です！

まとめ

Rails でアプリケーションを書いていて、DB定義書が必要になるケースはあまりないかもしれませんが、特に意識することなく rake db:migrate の度に自動でDB定義書が更新されるのが思いのほか気持ちよかったので記事にしてみました。
XML から HTML への変換時の自由度が高く、好みのデザイン/スタイルで出力できるのも魅力的ですね。

#Ruby on Rails

AUTHOR