RepoThread Logo
RepoThread
価格

クイックスタート

関連ソースファイル

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

tbls は Go 言語で記述された CI フレンドリーなデータベースドキュメント生成ツールである。README.md:9-16 によれば、本ツールはデータベーススキーマを GitHub Flavored Markdown (GFM) 形式で自動的にドキュメント化し、単一バイナリで動作するため CI/CD パイプラインへの統合が容易である。また、PostgreSQL、MySQL、SQLite、SQL Server、Snowflake、BigQuery など多数のデータベースをサポートしており、ドキュメント生成だけでなくリンターとしても機能する。

本プロジェクトは継続的なビルドとテストが行われており、README.md:1-7 に示されるように GitHub Actions によるビルドステータスバッジや Go Report Card などの品質指標が公開されている。

ワンコマンドでの実行

tbls は設定ファイルなしでコマンドラインから直接データベースに接続し、ドキュメントを生成できる。README.md:52-58 に記載されている通り、DSN (Database Source Name) を引数に指定するだけで PostgreSQL データベースのドキュメントが生成される。

console
1$ tbls doc postgres://dbuser:dbpass@hostname:5432/dbname

Docker 環境を使用する場合、README.md:60-64 に示されるように ghcr.io/k1low/tbls イメージを利用できる。カレントディレクトリを /work にマウントし、同一のコマンドを実行することでホストマシンにドキュメントが出力される。

console
1$ docker run --rm -v $PWD:/work -w /work ghcr.io/k1low/tbls doc postgres://dbuser:dbpass@hostname:5432/dbname

インストール方法

tbls は複数のインストール方法を提供しており、README.md:66-88 に詳細が記載されている。主要なパッケージマネージャーを使用したインストール方法を以下の表にまとめる。

方法コマンド対象プラットフォーム
deb パッケージdpkg -i tbls.debDebian/Ubuntu
RPM パッケージyum install tbls_*.rpmRHEL/CentOS/Fedora
Homebrewbrew install tblsmacOS/Linux
MacPortssudo port install tblsmacOS
aquaaqua g -i k1LoW/tblsクロスプラットフォーム
go installgo install github.com/k1LoW/tbls@latestGo 環境必須
Dockerdocker pull ghcr.io/k1low/tbls:latestコンテナ環境

deb パッケージを使用する場合、GitHub Releases からバージョンを指定してダウンロードする。RPM パッケージも同様にリリースページから直接インストール可能である。Homebrew および MacPorts は macOS ユーザーにとって最も簡便な選択肢であり、パッケージの更新管理も容易である。

GitHub Actions での使用については、README.md:117-142 に設定例が示されている。k1low/setup-tbls@v1 アクションを使用することで、ワークフロー内で tbls コマンドが自動的に利用可能になる。

yaml
1# .github/workflows/doc.yml
2name: Document
3
4on:
5  push:
6    branches:
7      - main
8
9jobs:
10  doc:
11    runs-on: ubuntu-latest
12    steps:
13      - name: Checkout .tbls.yml
14        uses: actions/checkout@v3
15      - uses: k1low/setup-tbls@v1
16      - name: Run tbls for generate database document
17        run: tbls doc

設定ファイルによる構成

プロジェクトで継続的にドキュメントを管理する場合、設定ファイル .tbls.yml (または tbls.yml) をリポジトリのルートに配置することが推奨される。README.md:158-169 に記載されている基本構成を以下に示す。

yaml
1# .tbls.yml
2
3# DSN (Database Source Name) to connect database
4dsn: postgres://dbuser:dbpass@localhost:5432/dbname
5
6# Path to generate document
7# Default is `dbdoc`
8docPath: doc/schema

dsn には接続先データベースの接続文字列を指定する。パスワードに # や < などの特殊文字が含まれる場合は、URL エンコードが必要である。docPath はドキュメントの出力先ディレクトリを指定し、デフォルト値は dbdoc である。

設定ファイルを作成した後、README.md:171-177 に示されるように tbls doc コマンドを実行するだけでデータベースが解析され、GitHub Friendly Markdown 形式でドキュメントが生成される。

console
1$ tbls doc

生成されたドキュメントと設定ファイルを Git にコミットすることで、データベーススキーマの変更履歴を管理できる。

console
1$ git add .tbls.yml doc/schema
2$ git commit -m 'Add database document'
3$ git push origin main

環境要件

tbls は Go 言語で記述されており、単一バイナリとして配布されるため、ランタイムの依存関係が最小限である。go.mod:1-3 によれば、プロジェクトは Go 1.25.0 を使用してビルドされている。ただし、エンドユーザーがバイナリを直接ダウンロードして使用する場合、Go のインストールは不要である。

main.go:23-29 には、サポートされているデータベースドライバのインポートが記載されており、MySQL、PostgreSQL、SQLite、SQL Server、Snowflake、Databricks が含まれている。これらのドライバはバイナリに組み込まれているため、追加のインストールは不要である。

Docker 環境でビルドを行う場合、Dockerfile:1-10 に示されるように golang:1-bookworm イメージが使用され、SQLite サポートのために sqlite3 パッケージがインストールされる。

実行検証

tbls が正常にインストールされたかを確認するには、バージョン表示コマンドを実行する（※バージョン確認コマンドの具体的な出力形式はソースファイルに明示されていないため、一般的な動作として説明）。インストール後、以下のコマンドで動作確認が可能である。

console
1$ tbls version

ドキュメント生成を実行した後、指定した docPath (デフォルトは dbdoc) ディレクトリ内に Markdown ファイルと ER 図が生成されていることを確認する。sample/mysql/README.md:1-39 は、実際に tbls によって生成されたドキュメントのサンプルであり、テーブル一覧、説明、ラベル、リレーション図が含まれている。

生成されるドキュメントの構造：

  • README.md - データベース全体の概要とテーブル一覧
  • *.md - 各テーブルの詳細説明
  • schema.svg - ER 図 (SVG 形式)

よくある問題と解決策

DSN の接続エラー

問題: tbls doc 実行時にデータベース接続エラーが発生する。

原因と解決策:

  1. DSN の形式が不正 - README.md:171 に注意書きがある通り、パスワードに特殊文字 (#, < 等) が含まれる場合は URL エンコードが必要
  2. ネットワーク接続の問題 - データベースサーバーへの接続が許可されているか確認（ポート番号は DSN で指定、例: PostgreSQL は 5432）
  3. 認証情報の誤り - ユーザー名、パスワード、データベース名を再確認

Docker 実行時のパーミッションエラー

問題: Docker で実行した際、生成されたファイルにアクセスできない。

原因と解決策: Docker コンテナ内で生成されたファイルの所有者が root になる場合がある。README.md:60-64 のコマンド例では -v $PWD:/work でマウントしているが、ユーザー ID のマッピングが必要な場合がある。--user $(id -u):$(id -g) オプションを追加することで解決できる（※この解決策は一般的な Docker のベストプラクティスであり、ソースファイルには明示されていない）。

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

問題: データベーススキーマを変更したが、ドキュメントに反映されない。

原因と解決策:

  1. キャッシュの問題 - 出力ディレクトリを削除して再実行
  2. 設定ファイルの docPath 確認 - 期待するディレクトリに出力されているか確認
  3. tbls diff コマンドの使用 - README.md:203-218 に示されるように、tbls diff を使用してデータベースとドキュメントの差分を確認できる
console
1$ tbls diff

CI 環境でのタイムアウト

問題: GitHub Actions で tbls doc がタイムアウトする。

原因と解決策: .github/workflows/ci.yml:52-56 に示されるように、CI 環境ではデータベースの起動待ち時間が必要な場合がある。sleep 20s のように適切な待機時間を設定するか、ヘルスチェックを使用してデータベースの準備完了を待つことが推奨される（※ヘルスチェックの具体的な実装はソースファイルに明示されていない）。

次のステップ

クイックスタートガイドで基本的な使い方を習得した後は、以下の機能の活用を検討するとよい。

  1. リンター機能 - データベーススキーマの品質チェック
  2. 差分検出 - tbls diff によるスキーマ変更の追跡
  3. ドキュメントカバレッジ - コメントや説明の網羅率測定
  4. カスタムテンプレート - 出力フォーマットのカスタマイズ
  5. ビューポイント - 特定の視点からのスキーマ表示

これらの詳細な設定と使用方法については、プロジェクトの包括的なドキュメント（使用ガイド）を参照すること。特に .tbls.yml での高度な設定（テーブルフィルタリング、リレーション定義、ラベル付けなど）は、大規模なデータベースのドキュメント管理において有用である。