Salesforce開発でのtbls利用tips

はじめに

前回、tblsのSalesforce用外部データベースドライバーを作成したことをきっかけに以下の記事を書きました。

tblsを使う意義、導入の方法はお伝え出来たかと思いますが、今回はより良く使うためのtipsをお届けできればと思います。

前回のおさらい

tblsはDBのスキーマ、テーブル定義とER図を複数のフォーマットで生成することができるコマンドラインツールです。Markdown+Mermaidを選ぶことで、全てテキストベースで管理できます。

tbls driver for Salesforce CLI's metadata (tbls-driver-sf-cli-meta) はtblsが標準ドライバーで対応していないSalesforceのスキーマを扱うための外部データベースドライバー(以下、本ドライバー)です。

CLIツールでDB定義書を作ることで、CLI・LLMフレンドリーな設計書とすることができます。

(tips 1) テンプレートをカスタマイズする

生成されるmarkdownはオブジェクトに対して1ファイル作られるので、頻繁にオブジェクト一覧ページに戻りたいのですが、オブジェクトのページには一覧ページに戻る導線がありません。独自のナビゲーションがあるGitHubやGitLabで見るには良いのですが、VS Codeで見ていると不便に感じます。

また、項目定義の表について数式などを出力しているので、表の横幅が長くなりすぎることがあります。<style>タグを埋め込んで幅を制限したくなります。(※但し、<style>タグはGitHub/GitLabのレンダリングでは無効化されてしまいます)

tblsはテンプレートをカスタマイズすることで、出力のデザインを変えることができます。
オリジナルのテンプレートはこちらにありますので、これを改変してプロジェクト内に配置して、.tbls.ymlで指定します。

.tbls.yml

(省略)
templates:
  md:
    index: 'templates/index.md.tmpl'
    table: 'templates/table.md.tmpl'
    viewpoint: 'templates/viewpoint.md.tmpl'
(省略)

templates/table.md.tmpl

> [Home](README.md) / {{ .Table.Name }}

# {{ .Table.Name }}
(省略)
---

> Generated by [tbls](https://github.com/k1LoW/tbls)

<style>

table:nth-of-type(1) {
  max-width: 1100px;
}
table:nth-of-type(1) td {
  word-break: break-all;
  overflow-wrap: break-word;
}
table:nth-of-type(1) td:nth-child(1) {
  max-width: 200px;
  inline-size: 200px;
}
table:nth-of-type(1) td:nth-child(2) {
  max-width: 200px;
  inline-size: 200px;
}
table:nth-of-type(1) td:nth-child(3) {
  max-width: 150px;
  inline-size: 150px;
}
table:nth-of-type(1) td:nth-child(5) {
  max-width: 150px;
  inline-size: 150px;
}
table:nth-of-type(1) td:nth-child(8) {
  max-width: 300px;
  inline-size: 300px;
}
</style>

※1行目と最後の<style>タグを追加しています。
スタイルの列幅は好みで調整してください。

注意: Extra Definitionに入る情報(数式、リレーション、選択リスト値、等)が無いオブジェクトでは列が省略されます。

templates/viewpoint.md.tmpl

> [Home](README.md) / {{ .Name }}

# {{ .Name }}
(省略)

※1行目を追加しています。

(tips 2) Markdownの特殊文字をエスケープする

tblsはMarkdownの特殊文字を全てエスケープはしていません。したがって、出力内容によっては表示が乱れることがあります。
本ドライバーではtblsに渡す前に任意の文字をエスケープする設定を設けています。
(設定ファイル、設定のエントリーはオプションで無くても動作します。)
設定ファイルはコマンド実行時のカレントディレクトリから読まれます。

./.tbls-sf-cli-meta.toml

(省略)

# Escapes markdown special characters with a backslash. e.g. `*` -> '\*'
# `def` is an object or array of objects such as `tables` or `columns` in the schema.
# `prop` is a property of an object such as `name` or `type`.
# 1. both `def` and `prop` match 
# 2. `prop` matches and `def` is an empty string 
# 3. `def` matches and `prop` is an empty string 
# 4. both `def` and `prop` are empty strings

[[escape]]
def = ''
prop = ''
char = '$'

[[escape]]
def = ''
prop = 'extra_def'
char = '$[~'

[[escape]]
def = 'tables'
prop = ''
char = '$['

[[escape]]
def = 'tables'
prop = 'comment'
char = '$[*'

(省略)

オブジェクト、フィールド、その他のテキストを評価する際、設定ファイル内の[[escape]]エントリーのうち、以下の優先順で最もマッチするルールでエスケープします。
defはテーブル、カラムといった、ページやセクションとなる纏まりで、propはその属性を表示する表の列となる情報です。

1. def と prop の両方が一致
2. prop が一致し def がブランク
3. def が一致し prop がブランク
4. def と prop の両方がブランク

(tips 3) tblsに出力するオブジェクトを予め絞り込む

tblsには2025/4/24現在、Markdownに出力するテーブルをフィルターするinclude/exclude設定を有効にすると、ER図に出力するカラムを制限する設定(er.showColumnTypes)が無視される不具合と思われる挙動があります。
回避のため本ドライバーの設定で概ね同様に予め絞り込むことができます。

./.tbls-sf-cli-meta.toml

(省略)

# Filter tables.
# If the `include` key is present, it restricts the table to only those specified.
# Then, if the `exclude` key is present, it excludes the specified tables.
# The `include` and `exclude` keys are applied in that order.
# The wildcard `*` can be used to match multiple characters.

include = [
  '*__c',
  '*__mdt',
  'Account',
  'Contact*',
]
exclude = [
  'Baz__*',
]

(省略)

includeがあると、ホワイトリストとしてパターンに一致するオブジェクトだけに絞り込まれます。
次に、excludeがあると、パターンに一致するオブジェクトが除外されます。
include、excludeの順に評価されます。

(tips4) オブジェクトの項目一覧で、Comment列に表示ラベル名のみを出す

本ドライバーのデフォルトの挙動では、項目一覧のComment列には「表示ラベル名」と「説明」を; で結合して出力しています。
本ドライバーの設定で表示ラベル名のみとすることができます。

./.tbls-sf-cli-meta.toml

(省略)
# If you want only the label name to appear in the comment column of a table column, set to true.
suppressFieldDescription = true
(省略)

(tips5) 出力を日本語にする

社内での利用を促進するにあたって、出力が日本語でないというのは、ところによってはマイナスになるかもしれません。tblsは標準で出力のタイトルやカラム名を辞書登録で変換する機能を持っています。

.tbls.yml

(省略)
dict:
  Tables: オブジェクト一覧
  Description: 概要
  Columns: 項目一覧
  Indexes: INDEX一覧
  Constraints: 制約一覧
  Triggers: Apexトリガー / レコードトリガーフロー
  Relations: ER図
  Name: 名前
  Comment: コメント
  Type: タイプ
  Default: デフォルト値
  Children: 子オブジェクト
  Parents: 親オブジェクト
  Definition: 定義
  Table Definition: オブジェクト定義
  Nullable: Null許可
  Extra Definition: 定義
  Viewpoints: ビューポイント
  Enums: グローバル選択リスト値セット
  Values: 値
(省略)

設定ファイルのサンプル

今回設定した設定ファイルの全体は以下でご覧ください。

さいごに

これらの設定をすることで、出力されるドキュメントは格段に使いやすくなると思います。
ご活用いただければ幸いです。