schema2rst 0.9.0 をリリースしました。

一ヶ月ほど前から schema2rst をちょこちょことメンテナンスしています。
はじめは flake8 でコーディング規約のチェックをかけてみただけだったはずなのですが、
その流れであれこれいじっているうちに一ヶ月経ってしまいました。

まだドキュメントや実装が不足している部分があるので 0.9.0 というバージョンにしましたが、
前バージョン(0.1.0)のときから使っていたので、既に使ってもらえるレベルのものだと思います。

ということで、このエントリーでは schema2rst 0.9.0 の紹介をしたいと思います。

schema2rst ってなんなの?

schema2rst とはスキーマ情報から rst (reStructuredText) 形式のドキュメントを生成するツールです。
いわゆるリバースエンジニアリングをしてくれます。

開発者向けのドキュメントとしてデータベース定義書や ER図を作成することがありますが、
schema2rst はスキーマ定義からこれらのドキュメントを生成することができます*1
開発環境などのアクティブなデータベースからスキーマ情報を取り出すことができるため、
ドキュメントと実際のデータベースにズレがあるのを防ぐことができます。

基本的にはどのデータベースにも利用できると思いますが、開発時に検証しているのは MySQLPostgreSQL の 2種類です。
OracleSQL Server などでも動作確認したいので、協力してくれる方がいたら教えて下さい :-)

0.9.0 での変更点

かなりいじりました。

  • Python 3.2, 3.3 に対応
  • MySQL 以外の DBMS に対応 (動作は未確認)
  • PostgreSQL のテーブルコメント、カラムコメントに対応
  • ようやくテストコードが用意されました
  • schemadump コマンドを追加。スキーマ情報を YAML 形式にダンプ可能に。
    • ダンプデータを使うと、データベースに接続できないホストでもドキュメントが生成できます
  • A5 SQL スタイルのカラムコメント (タブ区切り)に対応

最近、testing.mysqld や testing.postgresql をこつこついじっているのは schema2rst のテストを書くためという側面もあります。
このツールは DBMS に完全に依存しているので、 sqlite などでごまかすことができないですからね。

試してみる

まずは pip でインストールします。一緒に MySQL 用のライブラリ、PostgreSQL 用のライブラリも入れておきます*2

$ pip install schema2rst mysql-python psycopg2

続いて、データベース接続用の設定ファイルを作ります。
たとえば MySQL に繋ぐ場合はこんな風に書きます。

type: mysql
db: sample
host: localhost
port: 3306
user: username
passwd: passw0rd

PostgreSQL に接続する場合は type を postgresql に書き換えれば ok です。

あとは schema2rst を実行するだけです。

$ schema2rst -c config.yaml -o schema.rst

実行結果

次のようなスキーマにたいして schema2rst を実行してみました。

CREATE TABLE users (
  id int primary key auto_increment comment 'ユーザ ID',
  login_id varchar(16) default '' not null comment 'ログイン ID',
  fullname varchar(255) default '' not null comment '氏名',
  sex int not null default 0 not null comment '性別     0:不明, 1:男性, 2:女性, 9:その他',
  mailaddr varchar(255) default '' not null unique comment 'メールアドレス',
  key (mailaddr)
) ENGINE='InnoDB' COMMENT 'ユーザ';

CREATE TABLE items (
  id int primary key auto_increment comment '商品 ID',
  name varchar(255) not null comment '商品名',
  type int not null default 1 comment '種別 (1:食品, 2:文具, 3:雑貨)',
  description text comment '説明文'
) ENGINE='InnoDB' COMMENT '商品';

CREATE TABLE order_history (
  id int primary key auto_increment comment '履歴 ID',
  user_id int not null comment 'ユーザ ID',
  item_id int not null comment '商品 ID',
  amount int not null comment '数量',
  order_date datetime comment '購入日',
  index (user_id, order_date),
  index (item_id, order_date),
  foreign key (user_id) references users(id),
  foreign key (item_id) references items(id)
) ENGINE='InnoDB' COMMENT '購入履歴';

そして、得られた rst ファイルを Sphinx で HTML に変換すると次のようになります。
f:id:tk0miya:20131212011957p:plain

まとめ

  • schema2rst をリリースしました
  • いくつかの環境に対応しました
  • DB に関わるドキュメントで楽しましょう

*1:ER図は現時点ではおまけレベルです

*2:複数の DBMS に対応している都合上、ドライバは別途インストールしてください。