# 機能設計書 189-New-DbaDbDataGeneratorConfig

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `New-DbaDbDataGeneratorConfig` コマンドレットの機能設計書である。このコマンドレットは、SQL Serverデータベーステーブルにリアルなテストデータを生成するためのJSON設定ファイルを作成する機能を提供する。

### 本機能の処理概要

本機能は、データベースのテーブル構造を分析し、各カラムに適切なフェイクデータを設定するためのJSON設定ファイルを生成する。カラム名、データ型、制約、リレーションシップを調べ、Bogusライブラリを使用したデータ生成ルールを自動的にマッピングする。「Address」「Email」「Phone」などの一般的なパターンに一致するカラム名には、文脈的に適切なフェイクデータタイプが自動的に割り当てられ、その他のカラムにはSQLデータ型に基づいた適切なデフォルトが設定される。

**業務上の目的・背景**：開発データベースには本番データの代わりにリアルなテストデータが必要である。本番データを使用すると個人情報保護の問題が発生する可能性があり、手動でテストデータを作成するのは時間がかかる。本機能により、本番スキーマを模倣しつつ機密情報を含まない開発・テスト用データベースを作成するための設定を自動生成できる。

**機能の利用シーン**：
- 開発環境用のテストデータ生成設定の作成
- デモ環境の構築準備
- 本番スキーマを持つトレーニングデータベースの作成
- アプリケーションテスト用の意味のあるデータセット生成

**主要な処理内容**：
1. データベースへの接続とテーブル構造の取得
2. 各カラムの分析（名前、データ型、制約）
3. columntypes.jsonからのマスキングタイプ同義語マッピング
4. カラムタイプに応じたデータ生成ルールの設定
5. Identity列、外部キー、ユニークインデックスの処理
6. JSON設定ファイルの生成と保存

**関連システム・外部連携**：Bogusライブラリ、columntypes.json設定ファイル

**権限による制御**：対象データベースへのSELECT権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 59 | データ生成 | 補助機能 | データ生成設定の作成 |

## 機能種別

設定ファイル生成 / メタデータ分析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | 必須 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | - |
| Database | string[] | No | 処理対象データベース | - |
| Table | string[] | No | 処理対象テーブル（ワイルドカード対応） | - |
| ResetIdentity | switch | No | Identity列をシード値にリセット | - |
| TruncateTable | switch | No | データ挿入前にテーブルを切り詰め | - |
| Rows | int | No | 生成する行数 | デフォルト1000 |
| Path | string | Yes | 設定ファイルの保存先ディレクトリ | 必須 |
| Force | switch | No | 保存先ディレクトリを強制作成 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SQL Serverデータベースのメタデータ（テーブル、カラム、制約）
- columntypes.json（データ型同義語マッピング設定）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | 設定ファイル名 |
| FullName | string | 設定ファイルの完全パス |
| Length | long | ファイルサイズ（バイト） |
| CreationTime | datetime | 作成日時 |
| LastWriteTime | datetime | 最終更新日時 |
| DirectoryName | string | 親ディレクトリパス |

### 出力先

JSONファイル（命名規則: servername.databasename.DataGeneratorConfig.json）

### JSON設定ファイル構造

```json
{
  "Name": "データベース名",
  "Type": "DataGenerationConfiguration",
  "Tables": [
    {
      "Name": "テーブル名",
      "Schema": "スキーマ名",
      "Columns": [
        {
          "Name": "カラム名",
          "ColumnType": "データ型",
          "CharacterString": null,
          "MinValue": null,
          "MaxValue": 100,
          "MaskingType": "Random",
          "SubType": "String",
          "Identity": false,
          "ForeignKey": false,
          "Composite": false,
          "Nullable": true
        }
      ],
      "ResetIdentity": false,
      "TruncateTable": false,
      "HasUniqueIndex": false,
      "Rows": 1000
    }
  ]
}
```

## 処理フロー

### 処理シーケンス

```
1. beginブロック処理
   └─ columntypes.json読み込み
   └─ 出力パスの検証/作成
2. processブロック処理
   └─ データベース取得（Get-DbaDatabase）
3. 各データベース処理
   └─ テーブルコレクション取得
4. 各テーブル処理
   └─ ユニークインデックス有無確認
   └─ カラムコレクション取得
5. 各カラム処理
   └─ 非サポート型のスキップ（computed, hierarchyid, geography, geometry, xml）
   └─ columntypes.jsonからの同義語マッチング
   └─ データ型に応じたMaskingType/SubType設定
6. テーブル設定オブジェクト作成
7. データベース設定オブジェクト作成
8. JSONファイル出力
   └─ ConvertTo-Jsonで変換
   └─ Set-Contentで保存
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[columntypes.json読み込み]
    B --> C[出力パス確認/作成]
    C --> D[Get-DbaDatabase]
    D --> E{データベース存在?}
    E -->|No| F[Stop-Function]
    E -->|Yes| G[各テーブルを処理]
    G --> H[各カラムを処理]
    H --> I{computed/非サポート型?}
    I -->|Yes| J[スキップ]
    I -->|No| K{columntypes同義語マッチ?}
    K -->|Yes| L[同義語設定を使用]
    K -->|No| M[データ型からデフォルト設定]
    L --> N[カラム設定追加]
    M --> N
    J --> O{次のカラム?}
    N --> O
    O -->|Yes| H
    O -->|No| P[テーブル設定追加]
    P --> Q{次のテーブル?}
    Q -->|Yes| G
    Q -->|No| R[JSON出力]
    R --> S[Get-ChildItem]
    S --> T[結果出力]
    T --> U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 非サポート型スキップ | computed, hierarchyid, geography, geometry, xmlカラムはスキップ | カラム処理時 |
| BR-002 | 同義語優先 | columntypes.jsonの同義語に一致する場合は定義済み設定を使用 | カラム名マッチ時 |
| BR-003 | デフォルト行数 | Rows未指定時は1000行 | Rows未指定時 |
| BR-004 | 命名規則 | ファイル名は「servername.databasename.DataGeneratorConfig.json」 | 常時 |

### 計算ロジック

| ColumnType | MaskingType | SubType | MaxValue |
|------------|-------------|---------|----------|
| bit/bool | Random | Bool | null |
| bigint | Random | Number | 9223372036854775807 |
| int | Random | Number | 2147483647 |
| smallint | Random | Number | 32767 |
| tinyint | Random | Number | 255 |
| date/datetime/datetime2 | Date | Past | null |
| float | Random | Float | null |
| varbinary | Random | Byte | MaximumLength |
| 上記以外 | Random | String | MaximumLength |

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| メタデータ取得 | sys.tables, sys.columns等 | SELECT | テーブル・カラム情報の取得 |

本機能はメタデータの読み取りのみを行い、データの変更は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | columntypes.json読み込み失敗 | ファイル破損または不存在 | モジュール再インストール |
| - | パス作成失敗 | ディレクトリ作成権限なし | 権限確認またはForce使用 |
| - | データベースなし | 指定データベースが存在しない | データベース名確認 |
| - | テーブルなし | データベースにテーブルがない | テーブル存在確認 |
| - | JSON出力失敗 | ファイル書き込み権限なし | パス権限確認 |

### リトライ仕様

リトライ処理は実装されていない。

## トランザクション仕様

トランザクション管理なし（読み取り専用操作）

## パフォーマンス要件

- テーブル数・カラム数に比例した処理時間
- 大規模データベースでは数分かかる場合あり

## セキュリティ考慮事項

- 対象データベースへのSELECT権限が必要
- 設定ファイルにはスキーマ情報のみが含まれ、実データは含まれない
- 出力パスへの書き込み権限が必要

## 備考

- 生成された設定ファイルはInvoke-DbaDbDataGeneratorで使用
- columntypes.jsonはモジュール内のbin/datamaskingディレクトリに配置
- Bogusライブラリの機能に基づいたデータ生成タイプを使用

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

パラメータ定義と設定ファイル構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaDbDataGeneratorConfig.ps1 | `public/New-DbaDbDataGeneratorConfig.ps1` | 103-117行目のparamブロック |

**読解のコツ**: Rowsのデフォルトは1000。Pathは必須パラメータ。

#### Step 2: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDbDataGeneratorConfig.ps1 | `public/New-DbaDbDataGeneratorConfig.ps1` | 119-140行目のbeginブロック |

**主要処理フロー**:
- **122-125行目**: columntypes.json読み込み
- **128-139行目**: 出力パスの検証と作成

#### Step 3: カラム処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbDataGeneratorConfig.ps1 | `public/New-DbaDbDataGeneratorConfig.ps1` | 188-322行目のカラム処理 |

**主要処理フロー**:
- **189-208行目**: 非サポート型のスキップ（computed, hierarchyid等）
- **219-221行目**: columntypes同義語マッチング
- **223-236行目**: 同義語マッチ時の設定
- **238-306行目**: データ型に応じたデフォルト設定（switch文）

#### Step 4: JSON出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaDbDataGeneratorConfig.ps1 | `public/New-DbaDbDataGeneratorConfig.ps1` | 353-370行目のJSON出力処理 |

**主要処理フロー**:
- **356行目**: ファイルパス構築（servername.databasename.DataGeneratorConfig.json）
- **361行目**: ConvertTo-JsonでJSON変換（Depth 5）
- **362行目**: Get-ChildItemでFileInfo返却

### プログラム呼び出し階層図

```
New-DbaDbDataGeneratorConfig
    │
    ├─ Get-Content (columntypes.json)
    │      └─ データ型同義語マッピング読み込み
    │
    ├─ Get-DbaDatabase
    │      └─ データベース情報取得
    │
    ├─ Get-DbaDbTable (Table指定時)
    │      └─ テーブルフィルタリング
    │
    ├─ テーブル/カラム処理
    │      ├─ $tableobject.Indexes.IsUnique
    │      └─ $tableobject.Columns
    │
    ├─ ConvertTo-Json
    │      └─ 設定オブジェクトのJSON変換
    │
    ├─ Set-Content
    │      └─ JSONファイル書き込み
    │
    └─ Get-ChildItem
           └─ FileInfo返却
```

### データフロー図

```
[入力]                    [処理]                         [出力]

SqlInstance ─────────▶ Get-DbaDatabase
Database ────────────▶ テーブル取得
                              │
                              ▼
columntypes.json ────▶ 同義語マッチング
                              │
                              ▼
カラムメタデータ ────▶ MaskingType/SubType決定
                              │
                              ▼
ResetIdentity ────────▶ テーブル設定構築
TruncateTable ────────▶
Rows ─────────────────▶
                              │
                              ▼
                       ConvertTo-Json
                              │
                              ▼
Path ─────────────────▶ Set-Content ─────────────────▶ *.DataGeneratorConfig.json
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDbDataGeneratorConfig.ps1 | `public/New-DbaDbDataGeneratorConfig.ps1` | ソース | メイン機能の実装 |
| columntypes.json | `bin/datamasking/columntypes.json` | 設定 | データ型同義語マッピング |
| Invoke-DbaDbDataGenerator.ps1 | `public/Invoke-DbaDbDataGenerator.ps1` | ソース | 生成設定を使用したデータ生成 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース情報取得 |
| Get-DbaDbTable.ps1 | `public/Get-DbaDbTable.ps1` | ソース | テーブル情報取得 |
