プロジェクト概要

関連ソースファイル

このページの内容は以下のソースファイルに基づいて生成されています：

• README.md
• main.go
• LICENSE
• CHANGELOG.md
• scripts/jsonschema/main.go
• go.mod
• Makefile
• Dockerfile
• scripts/jsonschema/go.mod
• testdata/md_test_README.md.golden

tbls は、データベーススキーマから自動的にドキュメントを生成し、スキーマ変更を検知・管理するための CLI ツールである。Go 言語で実装され、PostgreSQL、MySQL、SQL Server、MongoDB、BigQuery、Spanner、DynamoDB など 15 種類以上のデータベースおよびクラウドデータサービスに対応している。生成されるドキュメントには、テーブル定義、カラム情報、インデックス、制約、トリガー、ER 図（PlantUML/Mermaid 形式）が含まれ、Markdown ファイルとして出力される。

このツールの最大の特徴は、CI/CD パイプラインへの統合が容易である点である。tbls diff コマンドを使用することで、データベーススキーマと生成済みドキュメント間の差分を検出し、スキーマ変更の見落としを防ぐことができる。また、データベース間の比較もサポートしており、開発環境と本番環境のスキーマ差異を可視化することも可能である。

プロジェクトの目的と概要

tbls の主な目的は、データベースドキュメントの作成・維持を自動化し、スキーマ変更管理を効率化することである。従来、データベースドキュメントは手動で作成・更新されることが多く、実際のスキーマとの乖離が問題となっていた。tbls はこの問題を解決するため、スキーマ情報の自動取得と差分検知機能を提供している。

基本的なワークフロー

tbls の標準的な使用フローは以下の通りである。まず、.tbls.yml 設定ファイルを作成し、データベース接続情報とドキュメント出力パスを定義する。次に tbls doc コマンドを実行してドキュメントを生成し、生成されたファイルを Git リポジトリにコミットする。これにより、スキーマ変更の履歴管理とチーム共有が可能となる。

yaml
1# .tbls.yml の基本構成例
2dsn: postgres://dbuser:*****@hostname:5432/dbname
3docPath: doc/schema

ドキュメント生成後、git add および git commit でバージョン管理システムに登録し、GitHub 上でチームメンバーと共有する。このワークフローにより、スキーマ変更の可視化とレビューが容易になる（README.md:177-191）。

差分検知機能

tbls diff コマンドは、データベーススキーマと生成済みドキュメント間の差分を検出する。例えば、users テーブルに phone_number カラムが追加された場合、以下のような差分が出力される。

diff
1diff postgres://dbuser:*****@hostname:5432/dbname doc/schema/README.md
2--- postgres://dbuser:*****@hostname:5432/dbname
3+++ doc/schema/README.md
4@@ -4,7 +4,7 @@
5
6 | Name | Columns | Comment | Type |
7 | ---- | ------- | ------- | ---- |
8-| [users](users.md) | 7 | Users table | BASE TABLE |
9+| [users](users.md) | 6 | Users table | BASE TABLE |

さらに、異なるデータベース間の比較も可能であり、開発環境と本番環境のスキーマ同期チェックに活用できる（README.md:193-236）。

技術スタックとアーキテクチャ

tbls は Go 言語（Go 1.25）で実装された CLI ツールであり、Cobra フレームワークを使用してコマンドラインインターフェースを構築している。エントリーポイントは main.go に定義され、cmd.Execute() を呼び出すことで各種サブコマンド（doc、diff、lint 等）が実行される（main.go:33-36）。

対応データベースと依存ライブラリ

tbls は幅広いデータベースシステムに対応しており、各データベース専用の Go ドライバを使用して接続する。主要な依存関係は以下の通りである。

これらの依存関係は go.mod で管理されており、Go Modules によるバージョン固定が行われている（go.mod:1-49）。

アーキテクチャ概要

tbls のアーキテクチャは、大きく分けて「データソース層」「スキーマ解析層」「ドキュメント生成層」の 3 つのレイヤーで構成される。データソース層は各データベースドライバの抽象化を担当し、スキーマ解析層はメタデータの取得・正規化を行う。ドキュメント生成層は、テンプレートエンジンを使用して Markdown、PlantUML、Mermaid 形式の出力を生成する。

正在加载图表渲染器...

このアーキテクチャ図は、tbls の主要なコンポーネントとデータフローを示している。CLI レイヤーでコマンドを解析した後、データソース層からスキーマ情報を取得し、解析層で正規化・関係検出を行い、最終的にドキュメント生成層で出力を生成する。

設定管理と JSON Schema

tbls の設定ファイル（.tbls.yml）は YAML 形式で記述され、JSON Schema によるバリデーションがサポートされている。scripts/jsonschema/main.go では、設定構造体から JSON Schema を自動生成する機能が実装されている。これにより、IDE での入力補完や設定ファイルの検証が可能となる（scripts/jsonschema/main.go:16-36）。

開発体制とライセンス

tbls は MIT ライセンスの下で公開されているオープンソースプロジェクトである。著作権は Ken'ichiro Oyama 氏に帰属し、商用利用・改変・再配布が自由に行える（LICENSE:1-21）。

リリースサイクル

プロジェクトは活発にメンテナンスされており、頻繁なリリースが行われている。直近のリリース履歴を以下に示す。

CHANGELOG からわかるように、バグ修正と機能追加が継続的に行われており、コミュニティからのプルリクエストも積極的に受け入れている（CHANGELOG.md:1-28）。

開発テスト環境

tbls の開発・テスト環境は Makefile で自動化されており、複数のデータベースエンジンに対する統合テストが実行される。CI パイプラインでは、ci ターゲットがビルド、テスト、ドキュメント生成、差分チェックを一括で実行する（Makefile:1-41）。

テスト対象データベース

Makefile で定義されているテスト対象データベースは以下の通りである。

• PostgreSQL（バージョン 9.5 および最新版）
• MySQL（バージョン 5.6 および 8.0）
• MariaDB
• SQL Server
• MongoDB
• DynamoDB（ローカルエンドポイント使用）
• ClickHouse
• SQLite

各データベースに対して、doc コマンドでドキュメントを生成し、diff コマンドで期待値との差分チェックを行う。これにより、各データベースドライバの互換性と出力の一貫性が保証されている（Makefile:45-91）。

テスト実行フロー

正在加载图表渲染器...

このシーケンス図は、CI パイプラインでのテスト実行フローを示している。開発者が make ci を実行すると、依存関係のインストール、ビルド、データベースセットアップ、ユニットテスト、ドキュメント生成、差分チェックが順次実行される。

主要機能とカスタマイズ

tbls は多様なカスタマイズオプションを提供しており、プロジェクトの要件に合わせてドキュメント出力を調整できる。

辞書機能による多言語対応

dict: 設定を使用することで、ドキュメントの見出しやラベルを任意の言語に翻訳できる。以下は日本語向けの設定例である。

yaml
1dict:
2  Tables: テーブル一覧
3  Description: 概要
4  Columns: カラム一覧
5  Indexes: INDEX一覧
6  Constraints: 制約一覧
7  Triggers: トリガー
8  Relations: ER図
9  Name: 名前
10  Comment: コメント
11  Type: タイプ
12  Default: デフォルト値
13  Children: 子テーブル
14  Parents: 親テーブル
15  Definition: 定義
16  Table Definition: テーブル定義

この機能により、英語以外の言語でのドキュメント生成が容易になる（README.md:1029-1052）。

カスタムテンプレート

templates: 設定を使用することで、デフォルトのテンプレートを独自のものに置き換えられる。PlantUML や Graphviz の DOT 形式など、複数の出力形式に対応している（README.md:1054-1065）。

リレーション検出のカスタマイズ

外部キー制約が定義されていない場合でも、detectRelations: 設定を使用してカラム名のパターンマッチングによりリレーションを検出できる。命名戦略として singularTableName や invertedSingularTableName を選択可能である（README.md:1006-1027）。

適用シナリオ

tbls は以下のようなシナリオで特に有効である。

1. スキーマ変更のレビュー: プルリクエスト時に tbls diff を実行し、スキーマ変更の影響範囲を可視化
2. ドキュメントの自動更新: CI/CD パイプラインに組み込み、デプロイ時にドキュメントを自動生成
3. 環境間のスキーマ比較: 開発・ステージング・本番環境のスキーマ差異を検出
4. レガシーシステムの解析: 既存データベースからドキュメントを生成し、システム理解を促進
5. 多言語チーム対応: 辞書機能を使用して、チームの主要言語でドキュメントを提供

レポート構成

本技術分析レポートは、tbls の全体像を理解するために以下の構成で展開される。

正在加载图表渲染器...

このロードマップは、レポートの各章の関係性と推奨読了順序を示している。プロジェクト概要（本ページ）で全体像を把握した後、アーキテクチャ詳細、データフロー、設定管理、テスト戦略、拡張機能の順に深掘りすることで、tbls の技術的詳細を体系的に理解できる。

プロジェクトの定量化指標

tbls の規模と能力を定量的に示すと以下の通りである。

これらの指標は、tbls が単なるドキュメント生成ツールではなく、エンタープライズ環境でも活用できる堅牢なツールであることを示している。