Zenn
🐙

tblsのSalesforce CLIメタデータ用外部ドライバーを作った

に公開
Go
Markdown
ER 図
Salesforce
tbls
tech

はじめに

tblsとは様々なRDBMSやその他データベース、DWH等からテーブル定義やER図のドキュメントを生成するコマンドラインツールです。

主要なデータソースはシングルバイナリに組み込まれたドライバーでサポートされていますので、通常は困ることがありません。しかし残念ながらSalesforceのドライバーは持っていないのです。
幸いなことに、tblsには「外部データベースドライバー」という仕組みで非対応のデータソースを入力とすることができます。

それでは、ということでSalesforce CLIの「ソース形式」メタデータ用ドライバーを作ってみました。
logo
https://github.com/shellyln/tbls-driver-sf-cli-meta
お試しいただきご意見やissueを頂戴できれば幸いです。

外部データベースドライバーのプロトコル

外部データベースドライバー(以下ドライバー)のプロトコルは非常にシンプルです。
ドライバーはtblsからプロセスとして起動されます。実行形式であれば何でも構いません。
tblsは設定やコマンドライン等から受け取ったデータソース名(DSN)がtbls-driver-*:で始まる場合、*の部分の名前で一致するPATHに含まれる実行形式をドライバーとして起動し、DSN全体を環境変数TBLS_DSNでドライバーのプロセスに渡します。
ドライバーは、標準出力にJSON形式でDBのスキーマ情報を出力し、プロセスを正常終了させます。

出力するスキーマ

出力すべきスキーマはJSON Schema形式でこちらに定義されています。

開発言語の選択

プロトコルの章を見れば何でも良いことがわかると思いますが、個人的な好みでGoで開発することにしました。事前にGoをインストールする必要があるもののgo installコマンド一発でユーザーがセットアップ可能にできるのは便利ですね。

Salesforceのスキーマを読み込む

Salesforceのスキーマを簡単に取得する、また、CIやLLMで活用することを考えると、Salesfoce CLIやVSCodeプラグインで取得している手許の「ソース形式」メタデータを用いるのが良いと考えました。Salesforceのメタデータ形式はこのようにドキュメント化されています。本ドライバーは、flows・globalValueSets・restrictionRules・triggers・objects(fields・validationRules)を読み込んでいます。
tblsは一般的なデータベース向けにスキーマを作っていますので、若干Salesforceのオブジェクトや項目の持つ属性が上手く嵌らないところがありました。やむを得ず、def(定義のCREATE文等を入れるフィールド)やcommentを活用することとなりました。
Apexトリガーは本格的なパーサーを構築するのはさすがに大袈裟なので、正規表現で拾えるものを拾っています。

標準オブジェクト・標準項目の詳細情報が無い

あのぉ、Salesforceさん、標準オブジェクト・標準項目のメタデータ、情報がほとんど空なんですけど……。(諦めました)

  • ※2025-04-18 V0.0.4: 標準オブジェクトのリレーションシップを復元するようにしました。

使い方

セットアップ

Goがインストールされている前提で以下のコマンドを実行します。

go install github.com/k1LoW/tbls@latest
go install github.com/shellyln/tbls-driver-sf-cli-meta@latest

プロジェクトのリポジトリでの設定

Salesforceプロジェクトのルートに以下の内容で.tbls.ymlを作成します。
カスタマイズ方法はこちらをご参照ください。

dsn: sf-cli-meta:.

docPath: doc/schema

format:
  # Adjust the column width of Markdown format table
  # Default is false
  adjust: false
  # Sort the order of table list and columns
  # Default is false
  sort: true
  # Display sequential numbers in table rows
  # Default is false
  number: false
  # The comments for each table in the Tables section of the index page will display the text up to the first double newline (first paragraph).
  # Default is false
  showOnlyFirstParagraph: false
  # Hide table columns without values
  # Default is false
  hideColumnsWithoutValues: false
  # It can be boolean or array
  # hideColumnsWithoutValues: ["Parents", "Children"]

er:
  # Skip generation of ER diagram
  # Default is false
  skip: false
  # ER diagram image format (`png`, `jpg`, `svg`, `mermaid`)
  # Default is `svg`
  format: mermaid
  # Add table/column comment to ER diagram
  # Default is false
  comment: false
  # Hide relation definition from ER diagram
  # Default is false
  hideDef: false
  # Show column settings in ER diagram. If this section is not set, all columns will be displayed (default).
  showColumnTypes:
    # Show related columns
    related: true
    # Show primary key columns
    primary: true
  # Distance between tables that display relations in the ER
  # Default is 1
  distance: 1
  # ER diagram (png/jpg) font (font name, font file, font path or keyword)
  # Default is "" (system default)
  font:

include:
  - '*__c'
  - '*__mdt'
  - Account
  - Activity
  - Contact
  - Event
  - Lead
  - Opportunity
  - Task
  - User

ドキュメントの生成

メタデータは標準のforce-app/main/default/に配置されている前提です(2025-04-17時点では変更できません)。
以下のコマンドを実行します。yamlに記載されているdoc/schemaに出力されます。

tbls doc

このようなドキュメントが生成されます。
1
2
3
実物はこちらをご覧ください。

Excel形式での出力

検討段階で追加するカスタム項目をExcelに記載してレビュー、その後サンドボックスに適用したいこともあると思います。
以下のコマンドでExcel形式にエクスポートできます。

tbls out -t xlsx -o schema.xlsx

ドライバー実装の注意点

  • Relationを作る際、テーブル名のtableが存在しないとtblsはエラーとなる。
    • 本ドライバーの場合、メタデータを一部のみ取得している場合に該当。
  • MermaidでERを描画する場合、typeがブランクのcolumnがあると正しく描画されない。
  • MermaidでERを描画する場合、Mermaidが特殊扱いする一部の記号が貫通して出力された。
    • 本ドライバーの場合、標準オブジェクトのブランクになっている項目の型に-を割り当てたところ貫通した。

まとめ

Salesforce開発でテキストベースへのドキュメントの変更をお考えの方は、是非お試しいただければと思います。
ご意見やissueを賜れますと、また、新たなドライバーを作成される方の一助となれますと幸いです。

Discussion