Zenn
🚚

テーブル定義書をtbls × Git管理に移行したら良いことばっかり

に公開
DB
ドキュメント
Google Sheets
tbls
テーブル定義書
tech

こんにちは、mayaです！

先日、チームで管理していたテーブル定義書をGoogleスプレッドシートからtblsというツールを使ったGit管理に移行しました。
結論から言うと、これが想像以上に運用改善につながったので、その体験をシェアしたいと思います！

この記事で分かること

  • なぜテーブル定義書のGit管理が必要だったのか
  • tblsの導入手順と実際の設定内容
  • 自動更新の仕組みづくりと運用のポイント
  • 実際に感じたメリット・デメリット
  • 導入時に詰まったポイントと解決方法

筆者のステータス

  • Web開発経験3年程度のエンジニア
  • MySQL、Prismaを使った開発経験あり
  • チームでのDB管理運用改善を担当

現状の問題：GoogleスプレッドシートでのDB管理の限界

まず、なぜ移行が必要だったのかお話しします。

これまで私たちのチームでは、テーブル定義書をGoogleスプレッドシートで管理していました。
最初は手軽で良かったのですが、プロジェクトが大きくなるにつれ、以下のような問題が顕著になってきました。

実際に起こっていた問題

1. 定義書の更新忘れ・記述ミス

  • スキーマを変更したけど、スプレッドシートの更新を忘れる
  • 手動入力による誤字脱字や記述ミス
  • 気づかないうちに間違った情報で開発が進む😭

2. 変更履歴が追いづらい

  • 誰がいつ何を変更したのかが分からない
  • 間違った変更をしても、元に戻すのが困難
  • バージョン管理ができない

3. メンバーの知らないうちに更新される

  • レビューフローがない
  • 重要な変更に気づかずスルーしてしまう
  • チーム全体での情報共有が不十分

4. 誤操作のリスク

  • うっかり重要なセルを削除してしまう
  • フォーマットが崩れる
  • 複数人が同時編集してコンフリクト

これらの問題により、「テーブル定義書が信頼できない」状況になってしまいました。
開発メンバーも「結局、実際のDBを確認するしかない」という状態で、定義書の意味がなくなっていたんです。

tbls（テーブルズ）とは？選定理由

tblsの基本機能

tblsは、データベースからテーブル定義書を自動生成してくれるツールです。

主な特徴：

  • データベース直結：実際のDBスキーマから正確な情報を取得
  • マークダウン形式：Git管理しやすく、可読性も高い
  • 多種DB対応：MySQL、PostgreSQL、SQLiteなど幅広く対応
  • コメント管理：独自のコメントを設定ファイルで管理
  • ER図生成：テーブル間のリレーションも可視化

なぜtblsを選んだのか

他のツールとも比較検討しましたが、最終的にtblsを選んだ決め手は以下でした：

項目 tbls 他ツール
DB直結の正確性 ◎ △（手動更新が必要なものが多い）
Git管理との親和性 ◎ ◯
日本語ドキュメント ◎ △
学習コスト ◯ △
チーム導入のしやすさ ◎ △

特に「DB直結で常に正確な情報が取得できる」という点が決定的でした。
これなら、スキーマとドキュメントの乖離が起こりようがないですからね！

実際の導入手順

それでは、実際にどのように導入したかを詳しく説明します。

1. tblsのインストール

まずはtblsをインストールします。Macの場合はHomebrewが便利です。

brew install k1LoW/tap/tbls

2. 設定ファイル（tbls.yml）の作成

プロジェクトルートにtbls.ymlを作成し、データベース接続情報と出力設定を記載します。

tbls.yml
# DSN (Database Source Name) to connect database
dsn: mysql://username:password@localhost:3306/ec_shop

# Path to generate document
# Default is `dbdoc`
docPath: docs/db/schema

# Comments設定 - ドキュメント再生成時に保持される独自のコメント
comments:
  -
    table: users
    tableComment: |
      会員登録したユーザーの基本情報を管理するテーブル。
      ECサイトでの購入履歴や配送先情報と紐付けされる。

      新規会員登録時にレコードが作成される。
      退会時は論理削除される。
    columnComments:
      display_name: |
        サイト上で表示される名前
        商品レビュー等で公開される
      email: ログイン時に使用するメールアドレス
      remember_token: |
        自動ログイン機能で使用
        セッション管理用トークン
  -
    table: products
    tableComment: |
      ECサイトで販売する商品情報を管理するテーブル。
      在庫管理や注文管理と連携する。
    columnComments:
      product_code: |
        商品管理用の一意コード
        JAN コードとは別管理
      status: |
        0: 非公開
        1: 公開中
        2: 売り切れ
      price: 税抜き価格（円）

3. 初回のドキュメント生成

設定が完了したら、実際にドキュメントを生成してみます。

tbls doc --force

--forceオプションをつけることで、既存のドキュメントがあっても強制的に上書きします。

実行すると、docs/db/schemaディレクトリ配下に以下のようなファイルが生成されます：

docs/db/schema/
├── README.md          # 全体のER図とテーブル一覧
├── users.md          # usersテーブルの詳細
├── products.md       # productsテーブルの詳細
├── orders.md         # ordersテーブルの詳細
└── ...

生成されたマークダウンファイルは、テーブル構造が見やすく整理されていて、そのまま仕様書として使えるクオリティでした！

自動更新の仕組み作り

手動でのドキュメント生成だと、結局更新し忘れが起こりそうだったので、自動更新の仕組みを作りました。

lint-stagedとの連携

私たちのプロジェクトではPrismaを使っているので、schema.prismaファイルに変更があった場合に自動でtblsを実行するようにしました。

package.json
{
  "lint-staged": {
    "src/lib/db/prisma/schema.prisma": [
      "tbls doc --force",
      "git add docs/db/schema"
    ]
  }
}

動作フロー

この設定により、以下のような流れで自動更新されます：

  1. 開発者がPrismaスキーマファイル（schema.prisma）を変更
  2. git commitを実行
  3. lint-stagedがschema.prismaの変更を検知
  4. 自動的にtbls doc --forceが実行される
  5. テーブル定義書が更新される
  6. 更新されたドキュメントもコミットに含まれる

これで、スキーマを変更したら必ずドキュメントも更新される仕組みができました！

運用方針の策定とチーム展開

技術的な導入が完了したら、チームメンバーへの展開を行いました。

ドキュメント作成

まず、運用方針をまとめたドキュメントを作成しました：

主なポイント：

  • docs/db/schemaディレクトリ配下のファイルは直接編集禁止
  • コメント追加はtbls.ymlのcommentsセクションで行う
  • データベース接続が必要なので、ローカル環境での実行が前提
  • トラブル時の対処法

チームへの説明会

実際に運用を開始する前に、チームメンバーに向けて説明会を実施しました。

説明内容：

  1. 今回の移行の背景と目的
  2. tblsの基本的な使い方
  3. 自動更新の仕組み
  4. 注意事項とトラブルシューティング

メンバーからは「これで定義書の更新忘れがなくなりそう！」「Git管理になるのは安心」といった前向きな反応がもらえました。

実際に使ってみた感想

良かった点

1. 更新忘れがゼロになる
これが一番大きな改善点です。スキーマを変更すると自動的にドキュメントも更新されるので、定義書とDBの乖離が起こりません。

2. レビューフローが確立された
Git管理になったことで、テーブル定義の変更もPRレビューの対象になりました。重要な変更を見逃すリスクが大幅に減りました。

3. 変更履歴が追えるようになった
「いつ、誰が、何を変更したか」が明確になり、問題が起きた時の調査が楽になりました。

4. ドキュメントの品質向上
自動生成なので、フォーマットが統一され、見やすくなりました。ER図も自動で生成されるのが便利です。
実際のDBスキーマから生成するので内容も正確です。

課題・改善点

1. 初回セットアップの学習コスト
tblsの設定やlint-stagedとの連携など、初回セットアップに少し時間がかかりました。

2. ローカル環境への依存
データベースに接続する必要があるため、ローカル環境でDBが起動していないと実行できません。

3. コメント管理の複雑さ
独自のコメントを追加するにはtbls.ymlを編集する必要があり、直感的ではありませんでした。

チームメンバーの反応

  • 「定義書が常に最新になっているので安心」
  • 「マークダウン形式で見やすい」
  • 「PRレビューで構造変更に気づけるようになった」

全体的に、かなり好評でした！

導入時に詰まったポイントと解決方法

実際の導入では、いくつかのトラブルに遭遇しました。同じ問題で困る方もいるかもしれないので、シェアします。

1. データベース接続エラー

症状：tbls doc --force実行時に以下のエラーが発生

Error: failed to connect to database: dial tcp [::1]:3307: connect: connection refused

原因：ローカルのMySQLコンテナが起動していなかった

解決方法：

  • DockerでMySQLコンテナを起動
  • DSNの接続情報（ホスト、ポート、ユーザー名、パスワード）を再確認
  • mysqlコマンドで手動接続テストを実施

2. ドキュメントが更新されない

症状：コマンドは成功するが、ドキュメントに変更が反映されない

原因：--forceオプションを付けていなかった

解決方法：

# これだと既存ファイルを上書きしない
tbls doc

# --forceで強制上書き
tbls doc --force

3. 自動更新が動作しない

症状：コミット時にlint-stagedが実行されない

原因：Huskyの設定が不十分だった

解決方法：

# Huskyの再インストール
npm install husky --save-dev
npx husky install

# pre-commitフックの確認
ls .husky/
cat .husky/pre-commit

4. 日本語コメントの文字化け

症状：tbls.ymlの日本語コメントが文字化けする

原因：ファイルの文字エンコーディングが適切でなかった

解決方法：

  • ファイルをUTF-8で保存し直す
  • エディタの設定を確認

今後の改善予定

現在の運用で概ね満足していますが、さらなる改善も検討しています：

1. CI/CDでの自動実行

現在はローカル環境での実行のみですが、GitHub ActionsなどのCIでも実行できるようにしたいと思っています。

2. ER図の見やすさ改善

自動生成されたER図が少し見づらいので、レイアウトの調整や不要なリレーションの非表示などを検討中です。

3. 他のプロジェクトへの横展開

tblsはめちゃ便利ですし社内の反響が思いの想像以上に良いので、他のプロジェクトでも同様の導入が進めば良いなぁと思ったりしてます。
必要になったらいつでも情報共有できるようにこの記事を書いてます。

tblsを導入してテーブル定義書をGit管理にしたことで、チーム全体のDB管理運用が格段に改善されました！
特に自動更新の仕組みは、更新忘れを防ぐ上でとても効果的だったと思います。

GoogleスプレッドシートでのDB管理に限界を感じているチームには、ぜひtblsの導入をおすすめします。
初回セットアップは少し手間ですが、それを上回るメリットがありますよ🙋‍♂️

最後まで読んでいただき、ありがとうございました！
同じような課題をお持ちのチームの参考になれば嬉しいです。

Discussion