cli 読解ガイド

1事前知識：このツールの入力と出力

このツールは「DBのカタログ → 文書」の一方向の変換器です。文書に載せる内容の入力が2つ（DBのカタログとサイドカーYAML）、実行のしかたを決める入力が3つあり、出力は3つの形式とコンソールです。

出力先の構成

出力はすべてoutput.path（未指定なら./output）の下に、DBごとのディレクトリに分けて置かれます。同じ出力先へ複数のDBを出力しても混ざりません。

{output.path}/
├─ {DB名}/                              Markdown（人が読む）
│   ├─ README.md                         一覧へのリンク集と、出力対象の集計
│   ├─ tableList_{DB名}.md               テーブル一覧（常に出力）
│   ├─ erDiagramList_{DB名}.md           スキーマ別ER図の索引
│   ├─ erDiagram_{DB名}_{スキーマ}.md     スキーマ別ER図（大きいと _group{n} に分割）
│   ├─ viewpointList_{DB名}.md・viewpoint_{DB名}_{id}.md   観点
│   ├─ triggerList / functionList / sequenceList / typeList_{DB名}.md
│   └─ {スキーマ}/
│       ├─ table | view | materialized_view/{テーブル}.md  テーブル定義書
│       └─ function | sequence | type/{名前}.md            個別定義（関数は--previewで「利用しているテーブル」の節が付く）
├─ snapshot/{DB名}/                     JSON Lines（機械が読む。--checkの比較対象）
│   ├─ database.json
│   └─ {スキーマ}/tables.jsonl・functions.jsonl・sequences.jsonl・types.jsonl
└─ insights/{DB名}/                     参考情報（--checkの対象外）
    ├─ viewpoints.json                   観点（宣言した場合だけ）
    └─ {スキーマ}/functionTableUsages.json   関数・プロシージャの利用しているテーブル（--previewを付けた場合だけ）

一覧は、テーブル一覧以外は対象が1件以上あるときだけ出力します。どのファイルをどのクラスが書くかは10章にまとめています。

サイドカーYAML：DBに無い情報を足す

Markdownを手で編集しても、次の生成で上書きされます。DBのコメントに書けない情報は、設定ファイルのannotationsで指定するYAMLに書きます。コード上はこれをサイドカーと呼び（パスはsidecarPath）、性質の違う3種類の情報を持ちます。

# docs/sample/postgres/annotations.sample.yml から抜粋
tables:
  sample.department:                 # スキーマ名.物理テーブル名
    remarks: 組織改編時はdepartment_codeを変更せず、department_nameのみ更新すること
    columns:
      department_code: 部署コード。他システム連携時のキーとして使用
relations:
  - table: sample.audit_log          # 参照元（子）
    columns: [record_id]
    parentTable: sample.employee     # 参照先（親）
    parentColumns: [employee_id]
    cardinality: 0..1対多
viewpoints:
  - id: personnel                    # 観点ページのファイル名に使う
    name: 人事管理
    tables:                          # table= と同じ記法
      - sample.employee*
      - "!sample.employee_directory_view"
      - sample.department
      - sample.parking_spot

2事前知識：使っている技術

コードを読むときに前提になる技術は次のとおりです。どれも使い方は限られているので、この章で押さえる範囲を知っていれば読めます。

2.1 Java 21：record・sealed・パターンマッチ

このコードベースのクラスの多くはrecordです（エンティティ・DTO・スナップショット・request）。recordのコンパクトコンストラクタ（引数リストを書かないコンストラクタ）で、受け取ったリストの複製や値の正規化をしています。

public record NodeLimit(int value) {
  public NodeLimit {
    value = Math.max(value, 0);   // 0以下は「上限なし」（0）へ揃える
  }
}

「描くか省くか」のような場合分けは、sealed interfaceとswitchのパターンマッチで表します。switchは全パターンの網羅をコンパイラが検査するので、場合を増やすと分岐の書き漏れがコンパイルエラーになります。

public sealed interface RenderingPlan {
  ForeignKeyGroup group();
  record Draw(ForeignKeyGroup group) implements RenderingPlan {}
  record Omit(ForeignKeyGroup group, NodeLimit limit) implements RenderingPlan {}
}

// ErDiagramWriter.writeErDiagramPage（要約）
final PagedSection<?> detail = switch (plan) {
  case RenderingPlan.Omit omit -> /* 図の代わりに外部キー一覧を載せる */
  case RenderingPlan.Draw draw -> /* 図に載せたテーブルの一覧を載せる */
};

2.2 依存関係の組み立て：コンストラクタで受け取り、Componentsが2段階で組み立てる

DI（依存性の注入）は、クラスが使う部品を自分でnewせず、コンストラクタの引数で受け取る書き方です。このツールはDIコンテナ（Guice等）を使わず、誰に何を渡すかをComponents（エントリーポイントと同じパッケージ）がnewで書き下します。押さえる規則は3つです。

• アノテーションなし：コンストラクタに@Inject等は付けない。ArchitectureTestがcom.google.inject・jakarta.injectへの依存を検出する。
• 具象クラスもComponentsがnewする：コントローラー・2つのユースケース・SchemaExportPipeline・OutputDirectoryValidatorも同じ。コンストラクタの引数を変えたときの直し漏れは、コンパイルエラーになる。
• 2段階：出力先の検証をDBへ接続する前に行うため、DB種別に依存しない部品（outputDirectoryValidator()）と、接続して種別が分かってから組み立てる部品（controller(databaseType, sqlSessionFactory)）に分ける。

// Dbxray.createController：DBへ接続するのはここだけ
final SqlSessionFactory sqlSessionFactory = MyBatisSqlSessionFactories.create(connectionSettings);
return components.controller(
    DatabaseTypeDetector.detect(sqlSessionFactory),   // ここで接続して種別を判定
    sqlSessionFactory);

コンストラクタの引数の直し漏れ・CatalogRepositoryの実装の選び漏れ（switchがDatabaseTypeを網羅する）はコンパイルエラーになります。両方のDB種別でコントローラーまで組み立てられることは、DBへ接続しないComponentsTestが確かめます。

2.3 MyBatis：SQLはXML、結果はrecord

MyBatisは、SQLをXMLに書き、結果の列をJavaのオブジェクトへ詰めるライブラリです。このツールが発行するのはすべてSELECTで、更新はありません。

読むときに戸惑いやすい点が4つあります。

• SQLのIDは文字列で組み立てる。mapper XMLの名前空間com.dbxray.domain.repository.postgresql.CatalogRepositoryはJavaのクラス名に見えますが、そういうインタフェースはありません。AbstractCatalogRepositoryが「名前空間＋.＋ID」を文字列で作ってsession.selectListに渡します。IDEで定義へ移動できないので、ID（selectTableInfo等）の文字列でmapper XMLを検索してください。
• 両方のmapperを常に読み込む。mybatis-config.xmlはPostgreSQL用・Oracle用の両方を登録し、DatabaseTypeの名前（postgresql・oracle）で名前空間を選びます。
• 引数はschemaList・tableListの2つだけ。XMLの<if>で、リストが空なら絞り込み自体を外します。そのため空のリストでselectColumnListを呼ぶと全テーブルのカラムを取ってしまうので、Java側で空を弾いています。
• 列とrecordは名前で対応する。SQLの別名（AS "schemaName"）とDTOのコンポーネント名を、mybatis-config.xmlのargNameBasedConstructorAutoMappingで対応させます。resultType="TableDto"はtypeAliasesで付けた短い名前です。

// AbstractCatalogRepository（要約）
baseSqlPath = "com.dbxray.domain.repository." + databaseType.id() + ".CatalogRepository.";

try (SqlSession session = sqlSessionFactory.openSession()) {     // 呼ぶたびにプールから接続を借りる
  return session.selectList(baseSqlPath + sqlId, Map.of("schemaList", schemaList, "tableList", tableList));
} catch (PersistenceException e) {
  throw new RuntimeException("Failed to select: " + baseSqlPath + sqlId, e);   // どのSQLかを添えて包む
}

実行したSQL（DEBUG）と取得した行（TRACE）は、MyBatisがmapperの名前空間（このツールのパッケージ配下）のロガーへ出します。既定のレベルはINFOなのでログには残らず、調べるときだけ-Ddbxray.log.level=debugで上げます（2.6節）。Oracle用のmapper（838行）は、LONG型の列（ビューのソース・トリガーの本体等）やDBのバージョン（DBMS_DB_VERSION）を読むためにSQLの中でPL/SQLの関数を定義する（WITH FUNCTION）など、PostgreSQL用（670行）より手が込んでいます。DBごとの違いはSQLで吸収し、同じDTOへ揃えます。

2.4 Mermaid の erDiagram

ER図は、Markdownの中に書くMermaid記法のテキストです。GitHubは```mermaidのコードブロックを図として描画します。サンプルのdepartmentの定義書に出力されたER図をそのまま示します。

```mermaid
erDiagram
    sample_department["department"]
    sample_employee["employee（従業員）"]
    sample_department ||--o{ sample_employee : "employee_department_id_fkey"
    sample_department {
        integer department_id PK
        character_varying department_code
        character_varying department_name
    }
    sample_employee {
        integer department_id FK "所属部署ID"
    }
```

Mermaidのclick構文はGitHubで無効になるため、図からテーブル定義書へは、図の下に置く「ER図に掲載しているテーブル」の表のリンクで辿ります。

2.5 JSON Lines と Jackson

スナップショットは、1行に1オブジェクトのJSONを並べたJSON Lines（.jsonl）です。1テーブルが1行なので、gitの差分がそのままオブジェクト単位の差分になり、--checkも行をオブジェクトとして突き合わせられます。JSONへの変換はJacksonSnapshotSerializerが行い、次の性質に依存しています。

• 項目の順序が固定：recordのコンポーネントの宣言順に出力される。同じ内容からは常に同じ文字列になる（差分検知の前提）。
• 空は出力しない：JsonInclude.Include.NON_EMPTYで、null・空文字・空リストの項目を省く。真偽値のfalseは省かない。
• 日本語はそのまま：非ASCII文字をエスケープしない（git diffで読めるように）。

// snapshot/testdb/database.json
{"formatVersion":1,"name":"testdb","dbms":"PostgreSQL","majorVersion":16}

DBの版はメジャーバージョンだけを持ちます（DatabaseEntity.majorVersion）。マイナー版を更新したときに、--checkが差分を報告しないようにするためです。

domain層はJacksonに依存しません。変換のインタフェースSnapshotSerializerをdomainに置き、Jacksonを使う実装をinfrastructureに置いています。

2.6 log4j2 と ArchUnit

• log4j2（log4j2.xml）：ログを、実行したディレクトリからの相対のvar/log/dbxray.logへ書く。既定のレベルは、このツール（com.dbxray）がINFO、ライブラリがWARN。INFOには、接続先のDBMS・ドライバの版、件数、処理時間のような、1回の実行で数件に収まる調査の起点だけを出す。MyBatisは実行したSQL（DEBUG）と取得した行（TRACE。DBのメタ情報そのもの）をこのツールのパッケージ配下のロガーへ出すため、既定では残さず、調べるときに-Ddbxray.log.level=debug（またはtrace）で上げる。このツールのWARNだけは、標準エラーへも[warn]:付きで出す。処理結果の[result]:はロガーを通さずSystem.outへ直接出す。
• ログに出さないもの：パスワード、接続URL、CLI引数・設定値の値、設定ファイル・サイドカーYAMLの内容を引用するライブラリの例外メッセージ。メッセージの改行は%enc{%m}{CRLF}で\n・\rへ置き換え、DB由来の文字列（関数の定義等）で偽のログ行を作らせない。
• ArchUnit（ArchitectureTest）：レイヤーの依存方向や置き場所などの規約を、単体テストとして検査する。違反するとビルドが失敗する。規約の一覧は3章。

サンプルDBに対して通常実行したときの、既定のレベルのログファイルの全体です（日時とスレッド名を省き、長いパスを短くしています）。

INFO  MyBatisSqlSessionFactories Initializing SqlSessionFactory. [config=mybatis-config.xml]
INFO  MyBatisSqlSessionFactories Initialized SqlSessionFactory.
INFO  DatabaseTypeDetector Connected to the database. [product=PostgreSQL 16.15 (…), driver=PostgreSQL JDBC Driver 42.7.13]
INFO  ExportSchemaController [START] exportSchema
INFO  SidecarYamlRepository Loaded sidecar. [annotations=…/annotations.sample.yml, tableCount=2, relationCount=1, viewpointCount=3]
INFO  SchemaExportPipeline Skipping orphan table annotation check because the output target is filtered.
INFO  SchemaExportPipeline Merged logical relations declared in the sidecar. [relationCount=1]
INFO  SchemaExportPipeline Exported schema objects. [tables=15, functions=11, sequences=9, types=3, triggers=5]
INFO  ExportSchemaController [ END ] exportSchema [elapsedMillis=1395]

メッセージは英語で要旨を先に書き、値は末尾の[key=value, …]にまとめる、というのがこのリポジトリのログの書式です（docs/development/coding-guidelines.mdの「ログ」）。

3全体像と読む順

com.dbxrayの下は、4つの層と、層の外の2つ（config・shared）に分かれます。依存の向きはpresentation → application → domain ← infrastructureで、domainは他のどの層にも依存しません。DB・ファイル・JSONとやり取りするインタフェースをdomainに置き、その実装をinfrastructureに置く（依存関係逆転）ことで、外部に触れるコードをドメインの外へ出しています。

構造の規約（ArchitectureTestが検査するもの）

次の規約はArchUnitの単体テストで検査され、破るとビルドが失敗します。違反したら、テストを緩めずに依存や置き場所のほうを直す、というのがこのリポジトリの方針です（docs/development/coding-guidelines.md）。

クラス名の接尾辞が表す役割

クラス名の本体（何についてのクラスか）は、利用者向けのドキュメントの呼び方に揃えた用語集（domain-model.md）に従います。ただしForeignKeyEntity・ForeignKeysは歴史的経緯による名前で、外部キーだけでなく論理リレーションも含む「関連」を表します。

おすすめの読む順

上から順に読むと、外側（起動と入口）から内側（ルール）へ進めます。

1. Dbxray：main→run→Components.create→createController。処理全体の骨格です（4章）。
2. ExportSchemaControllerと2つのユースケース：2つのモードの違いが「どのSinkを渡すか」だけだと分かります。
3. SchemaExportPipeline：取得の順序と、スキーマ・チャンク単位の分割。6章の図と合わせて読むと速いです。
4. ExportSinkと3つの…SinkFactory：出力形式ごとに「いつ何を書くか」（6章の表）。
5. domain.model.target：ExportTargets・TableDefinitionContent・TableScope。取得したデータを組み立てる単位です（8章）。
6. domain.model.table・relation：TableKey・ForeignKeys・ForeignKeyGroups・Cardinality。関連とER図のルールです（9章）。
7. 関数が利用しているテーブルの抽出（--preview）：FunctionTableUsageAnalyzer→FunctionBodyLocator→TableReferenceScanner→SqlLexerの順に、9.9節の図と合わせて読みます。
8. 気になる出力のWriter→Templates：たとえばTableDefinitionWriter（セクションの順）→TableDefinitionTemplates（各セクションの組み立て）。
9. infrastructure：AbstractCatalogRepositoryとmapper XML、SidecarYamlRepository。
10. 入口の検証：CliArguments・DbxrayProperties・ConnectionSettings・FailureReporter（5章）。

4起動から終了までの流れ

Dbxray.mainは、処理全体を1つのtry-catchで囲み、次の順に進みます。前半（1〜6）はDBへ接続せずに入力を検証し、後半（7〜11）で接続して出力します。入力の誤りを接続より前に報告するのは、DBに接続できない環境（接続情報の誤り・DBの停止中）でも、設定の誤りに先に気付けるようにするためです。

// Dbxray.run（通常実行。runCheckも同じ形）
System.out.println("Starting output of database documents. …");
cliArguments.requireKnownArguments();
final ConfigFile configFile = ConfigFile.load(cliArguments.configPath());   // 設定ファイルは1回だけ読む
final ExportSchemaRequest request =
    DbxrayProperties.of(configFile, cliArguments.settingOverrides())
        .toExportSchemaRequest(cliArguments.isRmDist(), cliArguments.isPreview());
final Components components = Components.create();
components.outputDirectoryValidator().validate(request);
final ConnectionSettings connectionSettings = connectionSettings(configFile, cliArguments);   // ConnectionSettings.merge
final ResultDto resultDto = createController(components, connectionSettings).execute(request);
System.out.println(resultDto.resultMessage());
return ExitStatus.SUCCESS;

入口で文字列を型に変える

設定値は生の文字列のまま深い層へ渡しません。DbxrayPropertiesが空白を除き、整数へ変換し、出力対象の条件をTargetSelection.ofで型（TableScope・OutputObjectTypeの集合）へ変換します。誤りは1件ずつではなく、見つかった分をまとめて報告します。結果はrequestのrecordになり、エントリーポイント→コントローラー→ユースケースの3層を分解・再構築されずに通ります。

• --previewは機能の集合に変える：--check・--rm-distと同じ値を持たないフラグで、設定ファイルの項目にはありません。CliArguments.isPreviewが真なら、DbxrayProperties.toExportSchemaRequestがPreviewFeatureのすべてをpreviewFeaturesに入れます（機能を個別に選ぶ引数はありません）。--checkではrunCheckが「効果が無い」旨を表示するだけで、CheckDocumentDiffRequestは持ちません（7章）。
• 設定ファイルの探し方：ConfigFileは、--configで指定したファイル、無ければ実行したディレクトリのconf/config.ymlを読みます。jarの場所ではなくカレントディレクトリが基準で、配布用のrun.sh・run.batは自分のディレクトリへ移動してから起動します。全項目をCLI引数で上書きする場合でも、設定ファイル自体は必要です（実行するディレクトリを誤ったときに、既定の出力先へ黙って出力しないため）。
• 設定項目の仕様は1つの表に持つ：DbxrayProperties.SETTINGSが、項目ごとに設定ファイルでの位置（output.path等）・上書きするCLI引数名（--output-path等）・値の形式（1つの値・整数・リスト）を持ちます。CliArgumentsはこの表から上書きの引数を引くため、設定項目を足せば上書きの引数も増えます。
• 接続情報：ConnectionSettingsは設定ファイルのdatabaseに、環境変数DBXRAY_DB_PASSWORDのパスワード、CLI引数の順で値を重ねて検証します。ファイルにpasswordを書くと誤りです（作業ディレクトリのファイルはAIエージェント等のツールから読まれ得るため、秘密をファイルに残さない）。urlにパスワードを埋め込む書き方（?password=・sslpassword=・Oracleのuser/pass@）も、同じ理由で誤りにします。

5失敗の扱いと終了コード

失敗は3種類に分けて扱います。どれに当たるかで、表し方と利用者への報告が変わります。

捕まえるのは main の1箇所だけ

コントローラー・ユースケースは例外を捕まえません。mainがThrowableまで捕まえてFailureReporterに渡し、終了コード2で終わります（Errorまで捕まえるのは、捕まえないとJVMが終了コード1で終わり、--checkの「差分あり」と区別できなくなるため）。途中の層でcatchしてよいのは、次の3つの場合だけです。

包むときは原因（cause）を渡し、tryの範囲は置き換えたい呼び出しだけに絞ります。例外はYAMLの構文誤りで、SnakeYAMLの例外のメッセージは誤りの行をそのまま引用するため（設定ファイルに誤って書いたパスワードが画面とログに出得る）、YamlSyntaxErrorsで種類と位置だけの文言にし、原因は渡しません。UserCorrectableExceptionを投げるのは、入口（CLI引数・設定・出力先の検証）と、利用者の入力・実行環境に触れるインフラ（DBへの接続・サイドカーYAMLの読み込み）だけで、domain・applicationでは投げません。

FailureReporter の報告の形

[errmsg]に例外のメッセージを、[cause]に原因の連鎖のうち表示に含まれていないものを浅い順に並べます。原因のメッセージを繰り返しているだけの例外（MyBatisの例外等）は省くため、包んだ箇所でDBが返したエラーが失われず、かつ重複もしません。以下は実際の出力です。

$ java -jar dbxray.jar --chek
Starting output of database documents.
Please wait a moment ...

[result]:FAIL
Failed to output database documents.
 [errmsg]:Unknown argument: --chek (values are not shown; specify a value as --name=value) (available arguments: --check, --rm-dist, --preview, --help, --version, --config=<path>, --db-driver=<value>, …, --annotation-path=<value>)

$ java -jar … --chunk-size=abc --output-objects=trigger,view --table='sample.,!'
[result]:FAIL
Failed to output database documents.
 [errmsg]:Invalid configuration in conf/config.yml (overridden by --table, --output-objects, --chunk-size).
  - output.chunkSize must be an integer: abc
  - Invalid table pattern: sample., ! (the table name and the schema name must not be empty)
  - Unknown output object type: view

$ java -jar … --db-url=jdbc:postgresql://localhost:5999/testdb …（DBが待ち受けていないポート）
[result]:FAIL
Failed to output database documents.
 [errmsg]:Could not connect to the database. Check the connection settings (database in the configuration file, --db-* arguments and the DBXRAY_DB_PASSWORD environment variable) and that the database is running.
 [cause]:org.postgresql.util.PSQLException: Connection to localhost:5999 refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections.
 [cause]:java.net.ConnectException: Connection refused

1つ目の(values are not shown; …)は、解釈できない引数の値を伏せている印です（--db-pasword=…のような書き誤りで、パスワードが画面とログファイルに残らないように）。2つ目は、3つの誤りがまとめて1回で報告されている例です。(overridden by …)は、誤った値がCLI引数から来ている可能性を示します。想定外の失敗では、最後にAn unexpected error occurred. See the log file for details. [logFile=./var/log/dbxray.log]が付きます。

警告：処理は続けるが知らせる

サイドカーYAMLの個々の記述の誤りや、DBと付帯情報の乖離は、読み飛ばして警告します（付帯情報の一部の書き誤りで、定義書全体の再生成を止めないため）。警告はWARNのログで、log4j2.xmlがログファイルに加えて標準エラーへ[warn]:付きで出します。以下は、誤りを含むサイドカーYAMLで実行したときの標準エラーです（終了コードは0）。

[warn]:Ignoring unknown key in 'tables' entry of sample.department. [key=descripton, annotations=warn.yml]
[warn]:Ignoring unknown 'cardinality' and falling back to the default. [entry=relations #1, cardinality=多対多, default=1対多, annotations=warn.yml]
[warn]:Ignoring viewpoint. Invalid viewpoint id: '人事' (use only letters, digits, '-' and '_', because it is used as a file name) [entry=viewpoints #1, id=人事, annotations=warn.yml]
[warn]:Annotation exists for a table that was not found (renamed or dropped?). [table=sample.employe]
[warn]:Column annotation exists for a column that was not found (renamed or dropped?). [table=sample.department, column=department_cd]

上の3行はYAMLを読むSidecarYamlRepositoryが直接ログへ出したもの（entry=relations #1は何件目の定義かを示す）、下の2行はExportTargetConsistencyが通知（ConsistencyNotice）として値で返し、SchemaExportPipeline.reportが重要度に応じてログへ出したものです。判定をするドメインサービスは、結果をどこへ出すかを知りません。

出力そのものの食い違いも警告します。関数のオーバーロードの個別定義は{関数名}_{番号}.mdになるため、番号を付けた名前が別の関数の名前と重なる（calcのオーバーロードと関数calc_1）と、後に書いたほうだけが残り、関数一覧のリンクもすべて同じファイルを指します。ExportSchemaUsecaseは書き出しの前にDocumentLocations.functionsSharingDefinitionFileで重なりを求め、Function documents share the same file name, so only the one written last is kept. [file=…, functions=…]を出します（ファイル名は互換性を約束する範囲のため、区切りを変えて避けることはしていません）。

孤児カラム備考の警告は、サイドカーYAMLに書いた順に出ます（TableAnnotationがカラム備考を記述順のまま持ち、orphanColumnNamesは順序のあるListで返す）。同じ入力なら毎回同じ順序になります。

終了コード

--checkで差分があっても、表示の1行目は[result]:SUCCESSです。比較そのものは成功したという意味で、差分の有無は終了コードで判定します。JVMが起動できない場合などmainに入る前の失敗は、Javaの仕様で終了コード1になります。

6取得と書き出しの段取り（SchemaExportPipeline）

通常実行のユースケースは短く、取得と書き出しの段取りをSchemaExportPipelineに任せています。--checkのユースケースも同じパイプラインを使い、違いは渡すExportSinkのリストだけです。

// ExportSchemaUsecase.exportSchema
final Path outputBaseDir = outputPathResolver.resolveOutputBaseDir(request.outputPath());
final ExportTargets targets =
    schemaExportPipeline.fetchTargets(request.targetSelection(), request.sidecarPath());   // 一括取得
final DiagramBoxes diagramBoxes =
    schemaExportPipeline.fetchDiagramBoxes(targets, request.chunkSize());                // ER図の箱
warnFunctionsSharingDefinitionFile(targets.functions());   // 個別定義のファイルが重なる関数を警告（5章）
if (request.rmDist()) {
  removeOutputBaseDir(outputBaseDir);   // 取得に成功してから消す
}
schemaExportPipeline.export(
    targets,
    List.of(
        markdownSinkFactory.create(
            outputBaseDir,
            NodeLimit.of(request.erDiagramMaxNodes()),
            request.erDiagramDistance(),     // テーブル定義書のER図の描画距離（9.7節）
            diagramBoxes,
            targets.foreignKeys()),
        snapshotSinkFactory.create(outputBaseDir),
        insightSinkFactory.create(outputBaseDir)),
    request.chunkSize(),
    request.previewFeatures());   // --previewで有効にした機能。空なら利用テーブルの抽出をしない（9.9節）

軽い情報は一括で、重い情報はチャンクで

対象スキーマ全体を一度にメモリへ載せないよう、取得を2つの粒度に分けています。テーブル一覧・関連・トリガー等は1件が軽く、ER図や被参照情報でスキーマ・チャンクをまたぐ参照を解決するのに全件が要るため、最初に一括で取得して最後まで持ちます。カラム・インデックス・制約はテーブル数に比例して重くなるため、スキーマごと・chunkSize件ごとに取得し、書き出したら捨てます。

サンプルDB（ビューを含む15テーブル、schema=sample）で通常実行したときに発行されたSQLの順序です（-Ddbxray.log.level=debugで実行したログファイルから抜き出したもの）。

15テーブルが既定のchunkSize（3000）に収まるため、12〜14は1回ずつです。chunkSize=1なら12〜14がテーブルの数だけ繰り返されます。--checkでは10（ER図の箱）を発行しません。6の7行は、サンプルの3つのビューが参照するテーブルの数の合計です（9.8節）。

出力形式ごとのSink

ExportSinkは「取得した情報を1つの出力形式で書き出す」インタフェースで、5つのメソッドを持ちます。パイプラインは取得した順にこれを呼ぶだけで、何をどのファイルへ書くかは実装（…SinkFactoryの内部クラス）が決めます。出力先は、Sinkを作るときに渡します。

writeFunctionDefinitionsが受け取るのは、関数・プロシージャ1つ分の出力内容FunctionDefinitionContent（関数＋利用しているテーブル）のリストです。パイプラインがスキーマごとに、--previewのときだけFunctionTableUsageAnalyzerで抽出し、そうでなければ「抽出していない」印（FunctionTableUsage.notAnalyzed()）を持たせます。Sinkは抽出するかどうかを知らず、Markdownは「利用しているテーブル」の節を出すか、参考情報はファイルを書くか消すかを、この印で決めます（9.9節）。

突き合わせの通知はログへ

取得の途中で、出力対象のテーブルと、関連・付帯情報・観点をExportTargetConsistency（ドメインサービス）が突き合わせ、気付くべき事柄をConsistencyNoticeの値で返します。パイプラインのreportが重要度に応じて、INFOはログファイルだけへ、WARNはログファイルと標準エラーへ出します。通知の種類は9.2節にまとめています。

7差分検知（--check）

--checkは「DBの今の状態から作ったスナップショット」と「出力先にコミット済みのスナップショット」を比べます。取得は通常実行と同じパイプラインで、Sinkをスナップショットの1つに減らし、書き込み先を一時ディレクトリにするだけです。

// CheckDocumentDiffUsecase.checkDocumentDiff
final Path committedDir = outputPathResolver.resolveOutputBaseDir(request.outputPath());
final Path generatedDir = fileRepository.createTempDirectory(CHECK_TEMP_DIR_PREFIX);
try {
  final ExportTargets targets =
      schemaExportPipeline.fetchTargets(request.targetSelection(), request.sidecarPath());
  schemaExportPipeline.export(
      targets, List.of(snapshotSinkFactory.create(generatedDir)), request.chunkSize(),
      Set.of());   // プレビューの機能はスナップショットを変えないため、差分検知では有効にしない
  return snapshotDiff.compare(
      outputPathResolver.resolveSnapshotDirectory(generatedDir),
      outputPathResolver.resolveSnapshotDirectory(committedDir));
} finally {
  fileRepository.deleteDirectory(generatedDir);
}

行をオブジェクトとして突き合わせる

SnapshotDiffは両方のディレクトリのファイルを読み、1行ごとに「どのオブジェクトの行か」の表示名を付けて突き合わせます。表示名はSnapshotKind.identifyが作り、同じ表示名でも別のファイル（別のDB）なら別物として扱います（内部のrecord Targetはファイルと表示名の組）。

内容が違うものは、両側の行をSnapshotSerializer.formatForDiffで「1項目1行・配列は1要素1行」に整形してから、UnifiedDiffGenerator（Myers法の自前実装。前後3行の文脈）でunified diffにします。1行のJSONのままだと、差分が「丸ごと削除＋丸ごと追加」にしかならないためです。整形後の行番号は、ファイル上の行番号とは対応しません。

サンプルDBにsample.employee.nicknameカラムとsample.tmp_new_tableテーブルを足してから--checkした実際の出力です（終了コード1）。

[result]:SUCCESS
Difference detected between the generated document and the committed document.
Only in generated document (possibly missing commit):
 - table sample.tmp_new_table
Content differs:
 - table sample.employee
--- committed/testdb/sample/tables.jsonl (table sample.employee)
+++ generated/testdb/sample/tables.jsonl (table sample.employee)
@@ -15,6 +15,7 @@
     {"name":"profile","logicalName":"プロフィール（JSON）","type":"jsonb","primaryKey":false,"notNull":true,"defaultValue":"'{}'::jsonb"}
     {"name":"hired_date","logicalName":"入社日","type":"date","primaryKey":false,"notNull":true,"defaultValue":"CURRENT_DATE"}
     {"name":"updated_at","logicalName":"更新日時","type":"timestamp without time zone","primaryKey":false,"notNull":true,"defaultValue":"now()"}
+    {"name":"nickname","type":"text","primaryKey":false,"notNull":false}
   ]
   "indexes": [
     {"name":"employee_employee_code_key","method":"btree","unique":true,"primary":false,"definition":"CREATE UNIQUE INDEX employee_employee_code_key ON sample.employee USING btree (employee_code)"}

足したカラムにはコメントが無いためlogicalNameの項目がありません（空は出力しない、2.5節）。

検知しないもの

• Markdownだけの差分：手作業の編集・削除、ツールの更新による出力形式の変更。Markdownは生成しないためです。
• 生成日：スナップショットに含めないため、生成した日と別の日に実行しても差分になりません。
• 観点・関数の利用テーブル（参考情報）：--checkでは参考情報のSinkを使わず、最初から生成しません。「生成してから除外する」方式ではないので、参考情報の種類が増えても除外リストを保守する必要がありません。
• プレビューの機能（--preview）：スナップショットの内容を変えないため、--checkでは有効にしません。--checkと同時に指定しても効果が無く、runCheckがNote: --preview has no effect in --check mode.と表示します（関数が利用しているテーブルの抽出も行いません）。
• 個々のパーティション：スナップショットはパーティションキーだけを持ち、パーティションを持ちません。パーティションを自動で追加する運用でも、追加のたびに差分になりません。
• DBのマイナー版の更新：database.jsonはメジャーバージョンだけを持つため、マイナー版を上げても差分になりません。

8データの持ち方

8.1 テーブルキーで繋ぐ

このツールはDBを読むだけなので、更新の整合性を守るための集約や状態遷移はありません。代わりに設計の軸になっているのがテーブルキー（TableKey＝スキーマ名＋物理テーブル名）です。カラム・制約・トリガー・関連・付帯情報は、所属するテーブルをオブジェクトの参照ではなくテーブルキーで指します。だから、別々のSQLで、別々の時点で取得した情報を、後からテーブルキーで引き合わせて1テーブル分に組み立てられます。

ForeignKeysとViewReferencesは索引を2つ持ちます。ForeignKeysは、参照元のテーブルキーで引く索引（自分が参照している関連）と、参照先のテーブルキーで引く索引（自分を参照している関連＝被参照）です。被参照の索引からは自己参照を除きます（定義書の「外部キー情報」と「被参照情報」に二重に載らないように）。ViewReferencesも同じ形で、ビューのテーブルキーで引く索引（belongingTo。ビューが参照するテーブル）と、参照されるテーブルのテーブルキーで引く索引（referencingTo。そのテーブルを参照しているビュー）を持ちます（9.8節）。

8.2 取得の単位と、1テーブル分の組み立て

一括取得したExportTargetsと、チャンク単位で取得したTableDetailから、テーブルごとにTableDefinitionContent.assembleで「1テーブル分の出力内容」を組み立てます。これがテーブル定義書1ファイル、スナップショット1行に対応する書き出しの単位です。

テーブル定義書のER図は、この項目の関連からではなく、MarkdownExportSinkが対象範囲全体のForeignKeysから求めるDiagramNeighborhoodで描きます（9.7節）。描画距離が2以上だと、関連先のテーブルが持つ関連まで要るためです。TableDefinitionContentはスナップショットと共有するため、Markdownだけが使う図の範囲は持ちません。

関数・プロシージャはテーブルに属さないため、テーブルキーでは束ねません。関数1つ分をFunctionDefinitionContent（function＋tableUsage）として持ち、スキーマ単位で取得した定義本体から作ります。tableUsageは、--previewのときだけ定義本体から抽出し、そうでなければFunctionTableUsage.notAnalyzed()です。これが、関数の定義書1ファイル、functions.jsonlの1行（tableUsageは含めない）、functionTableUsages.jsonの1件に対応する書き出しの単位です（9.9節）。

8.3 「値が無い」の表し方

値が無いことの表し方は、段階ごとに決まっています。これを知っていると、nullチェックがほとんど無い理由と、どこで変換すべきかが分かります。

8.4 サイドカーの3種類の流れ先

SidecarYamlRepositoryがYAMLをSidecar（record）へ読み込み、fetchTargetsの中で3つに分かれて流れます。YAMLの読み込みは型の変換に専念し、ルールはドメインのメソッドに任せています。

8.5 不変と null の約束

• recordはコンパクトコンストラクタでリストをList.copyOfし、集合のクラスも変更できないリスト・マップだけを返します。生成した後に中身が変わることはありません。
• Sidecar・TableAnnotationはnullを空へ揃え、Annotations.belongingToは付帯情報が無いテーブルにもTableAnnotation.EMPTYを返します。呼び出し側はnullを気にしません。
• Tables.bySchema()・ForeignKeys.groupBySchema()は、結果をフィールドに持たず呼ぶたびに作ります。利用側のスコープを抜けたら解放されるようにするためです（メモリ効率）。

9ドメインの中心ロジック

9.1 出力対象の絞り込み（TableScope・TableNamePatterns）

設定のschema・tableから入口で1回だけTableScopeを組み立て、テーブルごとにmatchesで判定します。スキーマの絞り込みはSQLのINで、テーブル名パターンの判定はJavaで行います（ワイルドカード・除外はSQLの完全一致では表せないため）。

テーブル名パターン（TableNamePatterns）の規則は、出力対象の範囲と観点の所属テーブルで共通です。

• *は0文字以上の任意の文字列。ほかの文字はそのまま一致させる。
• 先頭の!は除外。除外は包含より優先する。包含が1件も無ければ、除外に一致しない全テーブルが対象。
• スキーマ.テーブルでスキーマを限定する。.が無ければ全スキーマ。
• テーブル名・スキーマ名の部分が空のもの（!だけ、sample.、.employee）は誤り。どのテーブルにも一致しない書き誤りだからです。

TableScope.isFiltered()（スキーマかテーブルが指定されている）は、突き合わせの通知を抑えるかの判断に使います。絞り込みで外れたのか、リネーム・削除で乖離したのかを区別できないためです（次節）。

9.2 関連の合流と突き合わせ（ExportTargetConsistency）

外部キー制約を張らないDBでは、カタログの外部キーだけではER図がほとんど空になります。そこでサイドカーで宣言した論理リレーションを、物理の外部キーと同じ集合（ForeignKeys）へ合流させます。合流させることで、ER図のグループ分割（連結成分）、スキーマ跨ぎの関連の抽出（crossSchema）、被参照（referencingTo）に、追加の実装なしで反映されます。読み手が「DBに制約がある」と誤読しないよう、区別は2箇所で付けます。

• 定義書のセクション：physicalBelongingToは「外部キー情報」へ、logicalBelongingToは「論理リレーション情報」（注意書き付き）へ。
• ER図の線種：RelationTypeが線種を持ち、物理は実線--、論理は破線..。

合流の前に、参照元・参照先の両方が出力対象のテーブルにある関連だけを残します（片側だけ残すと、定義書の無いテーブルがER図にだけ箱として現れるため）。除いたことを知らせるかは由来で違います。突き合わせの通知の一覧です。

9.3 多重度の判定（Cardinality）

外部キーそのものは「関連がある」ことしか示しません。多重度は、参照元（子）の外部キー列に付いた制約から機械的に決めます。SQLが2つの真偽値を返し、ForeignKeyDto.toEntityがCardinality.of(unique, mandatory)で多重度にします。

• 一意性は列名の一致ではなく包含関係で判定します（FK(a, b)にUNIQUE(a)があれば外部キー全体も一意）。一意索引も含め、条件付きの部分インデックスは除きます（PostgreSQLのmapperのchild_key_unique）。
• 子側が「1以上」になることはありません。「親1件につき子が1件以上」はテーブル定義で表せないためです。
• 論理リレーションはDBに制約が無いので判定できず、YAMLのcardinality（Cardinality.fromLabel）か、既定値の1対多を使います。サンプルのaudit_log.record_id → employeeは0..1対多と宣言されています。

9.4 ER図の出し分け（ForeignKeyGroups・RenderingPlan）

Mermaidは大きすぎる図を描けないため、スキーマ別ER図1枚のテーブル数に上限（erDiagramMaxNodes、既定80、0以下は上限なし）があります。「ノード」は関連を持つテーブルで、関連の無いテーブルは図に描きません（全テーブルはテーブル一覧に載る）。ページ構成はForeignKeyGroups.composeが1回で決め、各ページで描くか省くかはForeignKeyGroup.planRenderingが決めます。Writer・テンプレートはその結果に従うだけです。

• 連結成分（connectedComponents）：外部キーの両端を同じまとまりとして併合するUnion-Find（経路圧縮付き）。a→bとb→cは1つの成分になります。並びはノード数の降順、同数なら先頭のテーブル名の昇順で、何度実行しても同じです。
• まとめ直し（pack）：成分ごとに1ページにすると2テーブルだけの図が大量にできるため、上限に収まる限り複数の成分を同じページに入れます（先頭から空きのあるグループに入れる貪欲法）。同じページの成分同士は線で繋がらないので、関連を誤読するおそれはありません。
• 分けても1つにしかならない場合は、スキーマのページと同じ内容のグループページができるだけなので、分けずにSingleにします。この場合は上限を超えているのでOmitになり、図の代わりに外部キー一覧を載せます。
• 観点ページは人が選んだまとまりなので分けません（ViewpointContent.relationsにplanRenderingだけを使う）。テーブル定義書のER図は分割せず、上限は描画距離を縮めるかの判断にだけ使います（9.7節）。

// 上限5で出力したスキーマ別ER図（erDiagram_testdb_sample.md）の本文
## ER図

ER図に描画するテーブル数が12件となり、上限（erDiagramMaxNodes = 5件）を超えるため、
外部キーで繋がったテーブルのまとまりごとに2個のグループへ分割しました。

## グループ一覧

| No. | テーブル数 | 外部キー数 | 主なテーブル | Link |
|:---|:---|:---|:---|:---|
|1|10|10|sample.employee|[■](./erDiagram_testdb_sample_group1.md)|
|2|2|1|sample.shipment|[■](./erDiagram_testdb_sample_group2.md)|

「主なテーブル」はForeignKeyGroup.mainTableで、最も多くの関連が接続するテーブルです。group1の外部キー数10には、論理リレーションaudit_log.record_idも含まれます（合流しているため）。

9.5 ER図の箱に何を表示するか（DiagramBoxes）

ER図はチャンクより前（writeOverview）に書きますが、箱にはカラムを表示します。そこでfetchDiagramBoxesが、関連を持つテーブルのカラムだけをスキーマ・チャンク単位で別に取得し、DiagramBoxes.Builderが関連カラム（関連の参照元・参照先として使われるカラム）だけを残して他を捨てます。

• relationColumnsOf(drawnRelations)は、その図に描く関連で使われるカラムだけをテーブルごとに返し、参照元のカラムにFKを付けます（DiagramColumn）。
• テーブル定義書のER図では、自テーブルだけは全カラム（TableDetailのカラム）を表示し、相手のテーブルは関連カラムだけを表示します。
• 箱の表示名はMermaidSupport.assignLabelsが決めます。ふつうはテーブル名で、同じ図の中に同名のテーブルが複数のスキーマにあるときだけスキーマ.テーブルにし、論理名があれば「（論理名）」を付けます。
• Mermaidの識別子は記号を_に置き換えるため、別のテーブルが同じ識別子になり得ます（日本語の同じ文字数のテーブル名、sales.archive_ordersとsales_archive.orders等）。MermaidSupport.assignNodeIdsが_2・_3を付けて重複を避けます。スキーマ別ER図・観点のER図・テーブル定義書のER図のすべてがこれを使い、識別子を作るmermaidIdはprivateにして素通りできないようにしています（別のテーブルが1つの箱にまとまり、自己参照の線が引かれるのを防ぐ）。
• 図の本体（別名の宣言・関係線・箱）はMermaidSupport.erDiagramCodeBlockが組み立てます。テーブル定義書のER図とスキーマ別ER図で同じ手順を使うため、関係線の向き（参照先→参照元）を2か所で揃えておく必要がありません。

9.6 長い表のページ分割（PagedSectionWriter）

GitHubで表として表示できる行数には限りがあるため、行が多くなり得る一覧はすべてPagedSectionWriterを通して書きます。3,000行以下なら本体ページに表を埋め込み、超えるなら{本体のファイル名}_{n}.mdへ分けて本体にはリンクだけを載せます。行の文字列はページ単位で作り、全行分を同時にメモリに持ちません。対象は、テーブル一覧、ER図の掲載テーブル・外部キー一覧、スキーマ跨ぎの外部キー、トリガー/関数/シーケンス/型の一覧、観点の所属テーブル・観点一覧です。

9.7 テーブル定義書のER図の描画距離（DiagramNeighborhood）

テーブル定義書のER図は、既定では自テーブルの関連だけを描きます。設定のoutput.erDiagramDistance（--er-diagram-distance。1〜3、既定1）を上げると、関連先のテーブルが持つ関連まで描きます。どこまで描くかはForeignKeys.neighborhoodOfが決め、結果をDiagramNeighborhood（描く関連・描いた距離・指定された距離）で返します。

1. たどる：自テーブルから関連を向きを問わず幅優先でたどります（参照先の索引と被参照の索引の両方を見る）。距離nなら、n−1段目までに到達したテーブルが持つ関連を、近い順に集めます。距離1は自テーブルの関連だけで、従来の出力と同じです。
2. 縮める：図のテーブル数がerDiagramMaxNodes（NodeLimit）を超えるなら、超えなくなるまで距離を1つずつ縮めます。1でも超える場合は1で描きます（自テーブルの関連は省かない）。
3. 知らせる：縮めた場合（isShortened）は、TableDefinitionTemplates.erDiagramが図の前にその旨を書きます。

サンプルのdepartmentを距離2で出力すると、関連先のemployeeが持つ関連（自己参照・attendance・employee_history・employee_profile等）まで描かれ、図のテーブルは2から8に増えます。距離3と上限5を指定すると、上限を超えるため1段で描き、次の1文が付きます。

## ER図

関連するテーブルが多く、3段先までを描画するとテーブル数が上限（erDiagramMaxNodes）を超えるため、1段先までを描画しています。

```mermaid
erDiagram
    sample_department["department"]
    sample_employee["employee（従業員）"]
    sample_department ||--o{ sample_employee : "employee_department_id_fkey"
    …

上限を3にしているのは、関連の多いDBでは段数を増やすと図がすぐに大きくなり読めなくなるためです（DbxrayProperties.MAX_ER_DIAGRAM_DISTANCE）。範囲外の値は既定値に置き換えず、設定の誤りにします。図の関連線は、どの段の関連も「参照先 → 参照元」の向きで同じMermaidSupport.relationLineで描きます。

9.8 ビューが参照するテーブル（ViewReferences）

ビュー・マテリアライズドビューが参照するテーブル（ビューを含む）は、ビューのSQLを解析せず、DBが保持する依存関係から取得します（PostgreSQLはpg_depend・pg_rewrite、OracleはALL_DEPENDENCIES）。1件がViewReferenceEntity（参照する側のビューと、参照されるテーブル）で、集合がViewReferencesです。

• 取得の範囲：外部キーと同じく対象範囲全体を一括で取得し（SchemaExportPipeline.fetchViewReferences）、参照する側が出力対象のビューのものだけを残します。参照される側は、出力対象外のスキーマのテーブルも事実として残します（サンプルのattendance_monthly_viewはsample_archive.departmentを参照）。
• SQLで揃えること：同じテーブルへの参照は1件にまとめ、自身への参照とDBMSが管理するスキーマのテーブルへの参照は含めません。パーティションへの参照は、パーティション表（根）への参照とします。
• 両方向で使う：ビューの定義書の「参照するテーブル」とスナップショットのreferencedTables（belongingTo）、テーブルの定義書の「参照しているビュー」（referencingTo。テーブルを変えたときに影響を受けるビューを知るため）。逆向きはスナップショットに持たせず、mcp-serverがreferencedTablesから逆引きします（get_tableのreferencedByViews）。

// view/attendance_monthly_view.md の「参照するテーブル」
| No. | 参照先 | 区分 |
|:---|:---|:---|
|1|sample.attendance|table|
|2|sample.employee_directory_view|view|
|3|sample_archive.department|table|

9.9 関数・プロシージャが利用しているテーブルの抽出（--preview）

ビューが参照するテーブル（9.8節）と違い、DBは関数・プロシージャの依存関係を保持しません。そこで、定義本体（FunctionEntity.definition）のSQLを読んで、利用している出力対象のテーブルと操作（C・R・U・D）を機械的に拾います。DBが持つ事実ではない参考値で、精度にリスクがあるため、--previewを付けたときだけ動くプレビューの機能（PreviewFeature.FUNCTION_TABLE_USAGE。互換性の対象外）として入れています。

設計の軸は2つです。

• 完全な構文解析はしない：「このキーワードの後ろの名前はテーブル」というきっかけと、前後の字句だけで判定します。構文解析器という依存を増やさず、構文の誤りや未対応の構文があっても止まらずに次の文から読み直せるようにするためです。呼び出している関数・動的SQLの中の参照は追いません（含まないことを定義書・MCPのツールの説明に書きます）。
• どんな入力でも例外を投げず、入力の長さに比例する時間で終える：定義本体はDBでCREATEの権限を持つ人が書ける入力です。正規表現を使わず1文字ずつ読み（ArchitectureTestが検査。3章）、閉じていない文字列・コメントは例外にせず「読み切れなかった」印にします（コンパイルに失敗した本体もDBに残り得るため）。

1. 字句に分ける（SqlLexer）：先頭から1文字ずつ読み、今いる場所が文字列・コメント・識別子のどれかを状態として持ちます。コメントと文字列は互いの中で効かない（文字列の中の--はコメントにならず、コメントの中の'は文字列を始めない）ため、同時に左から読まないと区別できません。規則はDBで違います（PostgreSQLはブロックコメントの入れ子・ドル引用符・E'…'、Oracleはq'[…]'・条件付きコンパイル）。そのため、DBMS種別を文字列ではなくDbmsのenumにして、switchで網羅的に切り替えます（DBMSを足すとコンパイルエラーで気付ける）。
2. 本体を切り出す（FunctionBodyLocator）：引数・戻り値の型の見出しは解析しません（RETURNS SETOF t・p t%ROWTYPEをテーブルの利用と誤らないため）。実装はDBMSごとです。
   PostgreSQL（PostgresBodyLocator）：pg_get_functiondefは本体を常にドル引用符で囲むため、見出しの後の最上位のドル引用符の中身を字句に分け直します。SQL標準の本体（BEGIN ATOMIC … END・RETURN 式）は、最上位のBEGIN ATOMIC・RETURNから終わりまでです。
   Oracle（OracleBodyLocator）：単独の関数・プロシージャは見出しのIS・ASの後ろ全体です。パッケージのサブプログラムは、どれも定義にパッケージ全体が入っているため、PackageSubprogramsがBEGIN・CASEとENDの対応を数えて、パッケージ本体の最上位のサブプログラムの範囲を求めます。オーバーロードは引数名で対応付け、区別できなければすべての本体からまとめて抽出します（overloadsMerged）。
3. 拾う（TableReferenceScanner）：字句を先頭から1回なめ、きっかけのキーワードの後ろの名前と操作をTableReferenceにします。文の状態（StatementState）は;と最上位のLOOPで丸ごと作り直すため、括弧の数が合わない文があっても次の文から読み直せます。動的SQL（EXECUTE・EXECUTE IMMEDIATE・DBMS_SQL等）は、含むことだけをDynamicSqlKindで示します。
4. 照らす（FunctionTableUsageAnalyzer）：拾った名前のうち、出力対象のテーブル（ビュー・マテリアライズドビューを含む）と一致したものだけを残します。CTEの名前・変数・DUAL等や、出力対象外のスキーマ・テーブルはここで落ちます。テーブルごとに操作をまとめ、スキーマが決まったものをスキーマ名・テーブル名の順に、決まらないものをその後に並べます。

操作とそのきっかけ。操作はCrudOperationです。細かい規則（括弧で囲んだJOIN・インラインビューへのDML・MERGEの各WHEN等）は、TableReferenceScannerTestのケースの一覧がそのまま仕様になっています。

権限・トリガー・行ロックの構文にもINSERT・UPDATE・DELETE・TRUNCATE・EXECUTEの語が現れます（GRANT SELECT, TRUNCATE ON a, b TO r・CREATE TRIGGER … BEFORE TRUNCATE ON t・GRANT EXECUTE等）。直前の語（GRANT・ON・BEFORE等）でこれらを文として読まず、後ろのカンマ区切りの名前に操作を付けないようにしています。

スキーマ修飾の無い名前。スキーマは、定義から決まる場合だけ決めます。決まらない場合は、同じ名前の出力対象のテーブルがあるスキーマをすべて候補として持ち、候補が1つでもそのスキーマに決めつけません（SchemaResolution・TableUsage.schemaCandidates）。

解析しなかった・限界がある場合。状態はTableUsageStatusで表し、定義書では表の代わりに（または表の前に）その旨を書きます。

サンプルのclose_project（プロシージャ。--previewで出力した関数の定義書から抜粋）と、スキーマが決まらない例のcount_rows（functionTableUsages.jsonから抜粋）です。

// function/close_project.md
## 利用しているテーブル

定義本体から機械的に抽出した参考値です。呼び出している関数・プロシージャの中の参照と、動的SQLの中の参照は含みません。

| No. | テーブル | 区分 | C | R | U | D |
|:---|:---|:---|:---|:---|:---|:---|
|1|sample.audit_log|table|○|○|||
|2|sample.employee|table|||○||
|3|sample.project|table||○|||
|4|sample.project_assignment|table||○||○|

// insights/testdb/sample/functionTableUsages.json の functions のうち count_rows（整形）
{"name":"count_rows", "arguments":"p_table_name text", "definitionHash":"a600475c…",
 "status":"analyzed",
 "tables":[{"name":"employee", "schemaResolution":"search_path",
            "schemaCandidates":["sample"], "operations":["R"]}],
 "dynamicSql":["EXECUTE"]}

精度をどう確かめているか。精度にリスクがある機能なので、テストの種類を分けています。サンプル（PostgreSQLの関数11件・Oracleのサブプログラム6件）は、全件がDDLから見て正しいことを確かめてあり、OracleはALL_DEPENDENCIESの参照先とも一致しました（PR #137の手元の確認）。実際の業務DBでの精度の確認は、プレビューを外す前に行う予定です（Issue #134）。

10出力物とソースの対応

出力する各ファイルについて、書き出すメソッドと、中身を組み立てるクラスの対応です。Markdownは「Writerが段取りし、Templatesが文字列を組み立てる」、スナップショットは「Writerがrecordを作ってJSONにする」という分担です。

どの一覧を出すかはMarkdownExportSinkFactory.listDocumentsが1箇所で決めます。テーブル一覧は常に、ER図一覧はテーブルがあれば、関数・シーケンス・型・トリガーの一覧は対象が1件以上あれば、観点一覧は観点を宣言していれば出します。READMEのリンクとテーブル一覧の「関連ドキュメント」もこの結果を使うため、空の一覧を出したり、存在しない一覧へリンクしたりしません。

テーブル定義書のセクション

TableDefinitionWriter.writeTableDefinitionは、テンプレートのメソッドが返す文字列を次の順に並べて1ファイルにします。空文字を返したセクションは出力されません。

関数・プロシージャの定義書のセクション

ObjectDefinitionTemplates.functionFileが、次の順に並べて1ファイルにします。「利用しているテーブル」は、--previewで抽出した実行だけの節で、FunctionTableUsageTemplates.sectionが空文字を返す（NOT_ANALYZED）と出力されません。関数・プロシージャ一覧（functionList_{DB名}.md）には列を足しません。

Writer と Templates の分担

• Writerは「何を・どの順で・どのファイルに書くか」の段取りだけを持ちます。Markdownの文字列を自分で組み立てません。
• Templatesは副作用の無いstaticメソッドで、行・セクションの文字列を組み立てます。絞り込みやグラフの計算などのロジックは持ちません（それはdomain.modelの仕事）。
• 種別をまたいで使う部品はwriter.templateにあります。MarkdownTemplateSupport（基本情報のセクション、表の1行row、リンクのセル[■](…)、エスケープescapeTableCell・escapePipe・escapeHtml・escapeInline、コードブロック・コードスパンの囲みcodeFence・codeSpan、真偽値のmarker）、MermaidSupport（識別子・表示名・属性・関連線）、PagedSectionTemplates（見出し・ページ送り・戻るリンク）です。

ファイル名と相対リンクの規則

ファイル名・パス・リンクを、テンプレートやWriterがString.format等で直接組み立てることはしません。出力先の絶対パスとドキュメント間の相対リンクが同じ規則を参照するため、ファイル名を変えてもパスとリンクが食い違いません。

相対リンクは、リンク元が{DB名}/直下ならlinkFromDatabaseRoot（./を付ける）、{スキーマ}/{区分}/の下の個別定義書ならlinkFromDefinition（../../を付ける）で作ります。サンプルのdepartment.mdには[人事管理](../../viewpoint_testdb_personnel.md)・[テーブル一覧へ](../../tableList_testdb.md)が出力されています。

DB由来の文字列を信頼しない

DB名・スキーマ名・テーブル名・コメント・関数やビューの定義は、ツールを実行する人とは別の人（DBでCREATE・COMMENTの権限を持つ人）が書ける入力です。引用符で囲んだ識別子には/・..・改行・HTMLも書けるため、出力・パスに使う箇所はすべて決まった部品を通します（docs/development/coding-guidelines.mdの「セキュリティ」）。サイドカーYAMLは利用者自身が書くため、説明文はMarkdownとしてそのまま出力します。

名前に上の文字を含まない限り、ファイル名は名前のままです。DB由来の文字列を受け取るテンプレートを足したら、MarkdownInjectionTestのrenderedDocumentsにも足します。関数の「利用しているテーブル」も、テーブル名・スキーマ名はescapeTableCell、候補の一覧と解析しなかった言語の名前はescapeInlineを通し、危険な文字列を入れた入力をMarkdownInjectionTestで確かめています。

11ソースごとの役割

main配下のクラスと、リソース・テストの一覧です。似た小さなクラスは1行にまとめ、package-infoは最後に1行でまとめています。「使う相手・使われる相手」の→は使う相手、←は使われる相手です。

./gradlew buildは、domain配下（com/dbxray/domain/**）の単体テストのカバレッジがline 95%・branch 85%を下回ると失敗します。結合テストはDockerが必要なため、別のタスク（integrationTest・oracleIntegrationTest）に分かれています。

12変更するときの道しるべ

よくある変更ごとに、触る場所と確かめ方をまとめます。規約の原文はdocs/development/coding-guidelines.mdの「変更の種類ごとに必要な作業」にあります。

設定項目を1つ足すとき

1. DbxrayPropertiesのSETTINGSに項目（設定ファイルでの位置・CLI引数名・値の形式）を足し、既定値と変換を書く。上書きのCLI引数はCliArgumentsがこの表から引く。
2. 値をrequest（ExportSchemaRequest・必要ならCheckDocumentDiffRequest）に足し、使う層まで同じrecordで運ぶ。文字列のまま深い層へ渡さず、入口で型にする。
3. 配布するconf/config.yml（全項目が未指定）に項目を並べ、docs/usage/cli.mdの設定の表（CLI引数の列を含む）を更新する。
4. DbxrayPropertiesTest・CliArgumentsTestに、未指定・誤った値・上書きのテストを足す。

DBから取得する項目を足すとき

1. PostgreSQL用とOracle用の両方のmapper XMLに列を足す。別名はDTOのコンポーネント名と同じにする。
2. DTO（record）にコンポーネントを足し、toEntity()で値の形を揃える（無い値はDtoValues.textで空文字、連結された値はsplitでリスト）。業務ルール（既定値の決定・名前の生成等）はDTOやリポジトリに書かず、ドメインのメソッドに持たせる。
3. エンティティに項目を足し、表示はテンプレートで（連結・エスケープ・○）。機械が読む必要があれば…Snapshotにも足す（値の形は8.3節、「空は出力しない」は2.5節）。
4. ./gradlew integrationTestを実行し、PostgresCatalogRepositoryITに取得結果のテストを足す。Oracle側を変えたら./gradlew oracleIntegrationTestとOracleCatalogRepositoryIT。出力が変わるなら、verifyスキルの手順でベースラインを出し直す。

テーブル定義書にセクションを足すとき

• 中身をTableDefinitionContent.assembleで1テーブル分に抜き出せるようにし、TableDefinitionTemplatesにセクションを返すメソッドを足して、TableDefinitionWriterの並びに加える。条件付きのセクションは空文字を返せば出力されない。
• Writerの中でMarkdownの文字列を組み立てない。ファイル名やリンクはDocumentLocationsの規則を使う。

出力形式を足すとき

• ExportSinkを実装したクラスと、それを作る…SinkFactoryをdomain.service.exportに作り、FactoryをComponentsで組み立てて、ユースケースが渡すリストに加える。--checkで比較したいかどうかで、CheckDocumentDiffUsecaseのリストに加えるかを決める。
• 配置の規則は…Locationsに、パスの解決はOutputPathResolverに足す（application層でパスの文字列を組み立てない）。

新しいドメインサービス・リポジトリを足すとき

• 依存はコンストラクタの引数で受け取る（@Injectは付けない）。Componentsにnewを足す。DB種別で実装が変わるものや、それに依存するものはComponents#controllerの中へ。
• 組み立ての漏れ・引数の不一致はコンパイルエラーになり、両方のDB種別で組み立てられることはComponentsTestで分かる。ファイルを読み書きするならFileRepositoryを受け取る（Filesを直接使うとArchitectureTestが落ちる）。日付が要るならClockを受け取る。

プレビューの機能を足す・外すとき

• 足す：PreviewFeatureにenumの値を足し、SchemaExportPipelineなどの有効かどうかで分かれる箇所だけが、request.previewFeatures()を見ます。--previewは機能を個別に選ばず全部を有効にするため、引数は増えません。出力が増えるファイルは、スナップショットに入れず、参考情報（insights/）か、--previewのときだけ出す節にします（スナップショットを変えると--checkの結果が変わるため）。
• 互換性の扱い：プレビューの機能の出力・挙動は互換性の対象外です。docs/usage/cli.mdの「プレビューの機能」の表に足し、PRにpreviewラベルを付けます（CONTRIBUTING.md）。
• ベースライン：--previewで変わる・増えるファイルだけを、差分のベースラインdocs/sample/{postgres,oracle}/output-previewに置きます。既定のベースラインと重複して持たず、結合テストが既定のものに重ねて比べます。サンプルの関数が変わったときも作り直します（verifyスキルの手順）。
• 外す（--previewなしでも動くようにする）：機能追加として扱い、リリースノートで知らせます。実際の業務DBでの精度の確認を、外す前に行います。

関数の定義本体を読むコードを足す・変えるとき

• 字句の規則はSqlLexerに、テーブルの判定はTableReferenceScannerに、DBごとの切り出しは…BodyLocatorに置きます。正規表現は使いません（ArchitectureTestが検出する）。どんな入力でも例外を投げず、入力の長さに比例する時間で終えるようにします。
• 判定の規則を変えたら、TableReferenceScannerTest・FunctionBodyLocatorTestのケースの一覧に足します。範囲の切り出し（PackageSubprograms）を変えたときは、GeneratedPackagesTestも確かめます（後ろのサブプログラムすべてに波及するため）。
• DBMSを足したら、Dbmsのenumに足します。switchが網羅的なため、DBごとに分岐している箇所がコンパイルエラーで分かります。

スナップショットの形式を変えるとき

• スナップショットはmcp-serverとの契約です。互換性の無い変更ならDatabaseSnapshot.FORMAT_VERSIONを上げ、mcp-serverのSnapshotDirectoryReader.SUPPORTED_FORMAT_VERSIONを追従させる。
• ./gradlew :mcp-server:testを実行する（SampleSnapshotContractTestがベースラインを読む）。項目の追加は互換で、mcp-serverを変えなくてもget_table等の結果に現れます（mcp-server 読解ガイドの6章）。

確かめ方の早見表

やってはいけないこと

• 途中の層でcatchしてログを出し、再スローする（報告はFailureReporterだけが行う）。catch (Exception e)で広く包む（別の失敗まで同じ文言になり、原因も消える）。
• domain・applicationでUserCorrectableExceptionを投げる（利用者が直せる入力の誤りは、ユースケースを呼ぶ前に入口で検証する）。
• SQLでMarkdown向けのエスケープや表示用の連結をする（スナップショットにMarkdownの記法が混ざる）。
• 判定をするドメインサービスが、警告をログへ直接出す（通知を値で返し、出力は呼び出し側に任せる）。
• ループの中で毎回TableNamePatterns.of(…)のような値オブジェクトを組み立て直す（入口で1回組み立てて使い回す）。
• DB由来の名前をPath.resolveやString.formatで直接パス・Markdownにつなぐ（…Locations・OutputPathResolverと、エスケープの部品を通す。10章の「DB由来の文字列を信頼しない」）。
• CLI引数・設定値・接続URLの値を、例外のメッセージやログにそのまま含める（書き誤りの引数にパスワードが入り得る）。
• 関数の定義本体を読むコードに正規表現を使う、定義本体の字句の読み取りで例外を投げる（DB由来の入力でバックトラックによる極端な遅さ・処理の中断を招く。9.9節）。
• InsightWriter以外でファイルを削除する、削除の対象を広げる（ファイルの削除は、前回のfunctionTableUsages.jsonを1つ消す1箇所だけで、ArchitectureTestがInsightWriter以外のdeleteFileの呼び出しを検知する。ディレクトリの削除は--rm-distの出力先だけ）。
• プレビューの機能の結果を、スナップショットに入れる（--checkの比較対象が変わり、互換性の対象外のものを契約に混ぜることになる）。

13用語集

利用者向けのドキュメントでの呼び方とコード上の名前の対応です。全体はdomain-model.mdの用語集にあります。

テーブルキー

TableKey。スキーマ名＋物理テーブル名。テーブルの識別子で、カラム・関連・付帯情報とテーブルを結ぶ。

テーブル

TableEntity。テーブル・ビュー・マテリアライズドビューの総称（区分はTableType）。

詳細情報

TableDetail。1テーブル分のカラム・インデックス・制約。チャンク単位で取得する。

出力対象

ExportTargets。一括取得した軽い情報の組（条件ではなくデータ）。何を出力するかの条件は「出力対象の絞り込み条件」（TargetSelection）と呼んで区別する。

出力対象の範囲

TableScope。設定のschema・table。

テーブル名パターン

TableNamePatterns。table=の記法（ワイルドカード・除外・スキーマ修飾）。観点の所属テーブルの指定でも使う。

出力対象オブジェクト種別

OutputObjectType。設定のtarget.objects（trigger・function・sequence・type）。

1テーブル分の出力内容

TableDefinitionContent。テーブル定義書1ファイル・スナップショット1行分。

関数1つ分の出力内容

FunctionDefinitionContent。関数・プロシージャの定義書1ファイル・スナップショットと参考情報の1件分（関数＋利用しているテーブル）。

プレビューの機能

PreviewFeature（--preview）。精度・出力の形を固めている途中で、付けたときだけ動く機能。互換性の対象にせず、スナップショットは変えない。

利用しているテーブル

FunctionTableUsage・TableUsage・FunctionTableUsageAnalyzer。関数・プロシージャの定義本体から機械的に抽出した、利用している出力対象のテーブルと操作。呼び出し先の関数・動的SQLの中は含まない参考値。

操作（C・R・U・D）

CrudOperation。利用しているテーブルへの作成・読み取り・更新・削除。TRUNCATEはD、MERGEはWHEN句の操作。

スキーマが決まらない名前

SchemaResolution・TableUsage.schemaCandidates。スキーマ修飾が無く、定義からは決まらない名前（search_path・current_user・synonym）。同じ名前の出力対象のテーブルがあるスキーマを候補として示し、決めつけない。

動的SQL

DynamicSqlKind。実行時に組み立てるSQL（EXECUTE・EXECUTE IMMEDIATE等）。中の参照は抽出できないため、含むことだけを示す。

字句（トークン）

SqlToken。定義本体を、空白・コメントを除いて分けた最小の単位（SqlLexerが作る）。

DBMS種別

Dbms。接続先のDBMS（PostgreSQL・Oracle）。基本情報に出す表示名と、定義本体の字句の規則の切り替えに使う。

関連

ForeignKeyEntity・ForeignKeys。外部キー（物理、RelationType.PHYSICAL）と論理リレーション（論理、LOGICAL）の総称。クラス名は歴史的経緯でForeignKey。

論理リレーション

DBに制約が無く、サイドカーYAMLのrelationsで宣言した関連。ER図では破線。

被参照の関連

incomingRelations・ForeignKeys.referencingTo。自分を参照している関連（自己参照を除く）。

多重度

Cardinality。参照元の外部キー列の一意性とNOT NULLから決まる、関連の両端の件数の関係。

描画距離

output.erDiagramDistance・DiagramNeighborhood。テーブル定義書のER図に描く関連の段数。1は自テーブルの関連だけ。図が上限を超える場合は縮める。

ビューが参照するテーブル／参照しているビュー

ViewReferenceEntity・ViewReferences。ビュー・マテリアライズドビューが参照するテーブル（referencedTables）と、その逆向き（referencingViews。MCPではreferencedByViews）。DBの依存関係から取得する。

ノード

ER図に描くテーブル。関連を持つテーブルだけを数える。

グループ

ForeignKeyGroup。1枚のER図に描く関連のまとまり。上限を超えると連結成分ごとにまとめ直す（ForeignKeyGroups）。

関連カラム

関連の参照元・参照先として使われるカラム。ER図の箱（DiagramBoxes）に表示する。

サイドカー

Sidecar。DBに無い情報を書くYAML（設定のキーはannotations、コード上はsidecarPath）。手動付帯情報・論理リレーション・観点を持つ。

手動付帯情報

Annotations・TableAnnotation。テーブル説明・テーブル備考・カラム備考。

集計（metrics）

DB単位のREADMEに載せる、出力対象のスキーマごとの数（オブジェクト・論理名の記述状況・関連と読み解きの状況）。出力したドキュメントと数が合うよう、SQLでは数えず取得した結果から数える。

孤児付帯情報

実在しないテーブル・カラムに対する付帯情報。リネーム・削除の見落としとして警告する。

観点

Viewpoint。業務ドメイン別にテーブルをまとめる切り口。観点ページと観点一覧になり、スナップショットには含めない。

突き合わせの通知

ConsistencyNotice。出力対象と関連・付帯情報・観点を突き合わせた結果。重要度に応じてログへ出す。

基本情報

BaseInfoEntity。各ドキュメントの先頭に載せるRDBMS（メジャーバージョンを添える）・DB名・作成日。作成日はDBではなくClockから。

チャンク

詳細情報をまとめて取得・出力するテーブルの塊。大きさは設定のchunkSize（既定3000、0以下でスキーマ全体）。

Sink

ExportSink。取得した情報を1つの出力形式で書き出すもの。Markdown・スナップショット・参考情報の3つ。

スナップショット

domain.model.snapshot。取得結果を構造化したJSON Lines。生成日を含まず、--checkの比較対象で、mcp-serverの入力。

参考情報（insights）

domain.model.insight。スナップショットの事実とは別にAIへ渡す情報（観点と、--previewのときの関数の利用しているテーブル）。--checkの対象外。

利用者が直せる誤り

UserCorrectableException。設定・入力・実行環境を見直せば解消する失敗。報告にスタックトレースを含めない。