# 機能設計書 166-Invoke-DbaDbDataGenerator

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Invoke-DbaDbDataGenerator`コマンドレットに関する機能設計書である。このコマンドは、JSON構成ファイルに基づいて構成駆動型のルールを使用し、SQL Serverデータベーステーブルにリアルなテストデータを生成する機能を提供する。

### 本機能の処理概要

Invoke-DbaDbDataGeneratorは、JSON構成ファイルに基づいてランダムに生成された現実的なテストデータをデータベーステーブルに挿入する。Bogusライブラリを使用して、名前、住所、電話番号、日付などの偽だが信頼性のあるデータを作成し、列の制約とデータ型を尊重する。開発環境の作成、テストシナリオ、本番データを使用しないデモデータベースの構築に最適。

**業務上の目的・背景**：
開発・テスト環境では、本番データを使用せずに現実的なテストデータが必要となることが多い。個人情報保護の観点から本番データをそのままコピーすることは避けるべきであり、このコマンドは本番データを使用せずに一貫性のあるテストデータを生成することで、安全な開発・テスト環境の構築を支援する。

**機能の利用シーン**：
- 開発環境のテストデータ生成
- 負荷テスト用の大量データ生成
- デモ環境のサンプルデータ作成
- プライバシー準拠のテストデータセット構築
- CI/CD パイプラインでの自動テストデータ生成

**主要な処理内容**：
1. JSON構成ファイルの読み込みと検証
2. Bogusライブラリを使用したFakerオブジェクトの初期化
3. 各テーブルの処理
   - ユニークインデックスに対応した値の生成
   - IDENTITYカラムの処理
   - 各カラムのデータ生成
4. INSERT文の構築と実行
5. 結果の返却

**関連システム・外部連携**：
- Bogusライブラリ（偽データ生成）
- SQL Server Database Engine
- Test-DbaDbDataGeneratorConfig（構成検証）
- Get-DbaRandomizedValue（ランダム値生成）

**権限による制御**：
- 対象テーブルへのINSERT権限が必要
- IDENTITY_INSERTの設定権限が必要（IDENTITYカラム使用時）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主機能 | コマンドラインからの直接実行 |

## 機能種別

データ生成 / テストデータ作成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | ターゲットのSQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替資格情報 | - |
| Database | string[] | No | データ生成対象データベース（未指定時は構成ファイルから取得） | - |
| FilePath | object | Yes | JSON構成ファイルのパス（ローカルまたはHTTP URL） | パイプライン入力対応 |
| Locale | string | No | ロケール（デフォルト: 'en'） | - |
| CharacterString | string | No | ランダム文字列生成に使用する文字セット | デフォルト: 英数字 |
| Table | string[] | No | 処理対象テーブル | - |
| Column | string[] | No | 処理対象カラム | - |
| ExcludeTable | string[] | No | 除外するテーブル | - |
| ExcludeColumn | string[] | No | 除外するカラム | - |
| MaxValue | int | No | 文字列カラムの最大長オーバーライド | - |
| ExactLength | switch | No | 既存データの長さに一致させる | - |
| ModulusFactor | int | No | NULL値の頻度制御（デフォルト: 10） | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- JSON構成ファイル（ローカルファイルまたはHTTP URL）
- コマンドライン引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（computer\instance） |
| Database | string | データが生成されたデータベースの名前 |
| Schema | string | テーブルを含むスキーマ名 |
| Table | string | 生成データが挿入されたテーブル名 |
| Columns | string[] | 生成データを受け取ったカラム名の配列 |
| Rows | int | テーブルに生成・挿入された行数 |
| Elapsed | TimeSpan | データ生成と挿入にかかった時間（prettytimespan形式で表示） |
| Status | string | 操作の結果 - 成功完了時は"Done" |

### 出力先

コンソール（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   ├─ Bogus.Fakerオブジェクトの初期化
   ├─ サポートデータ型リストの定義
   └─ サポートFakerタイプ/サブタイプの取得
2. processブロック
   ├─ 構成ファイルの読み込み（HTTP URLまたはローカル）
   ├─ Test-DbaDbDataGeneratorConfigによる検証
   ├─ 未サポートデータ型のチェック
   └─ インスタンスループ
       ├─ Connect-DbaInstance
       ├─ データベース取得
       └─ テーブルループ
           ├─ ユニークインデックス値の生成
           ├─ IDENTITYカラム処理
           ├─ INSERT文構築
           ├─ トランザクション内でのクエリ実行
           └─ 結果オブジェクト生成
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Bogus.Faker初期化]
    B --> C{FilePathはHTTP?}
    C -->|Yes| D[Invoke-RestMethod]
    C -->|No| E[Test-Path確認]

    D --> F[テーブル構成取得]
    E --> G{ファイル存在?}
    G -->|No| H[Stop-Function]
    G -->|Yes| I[Test-DbaDbDataGeneratorConfig]

    I --> J{検証OK?}
    J -->|No| K[Stop-Function]
    J -->|Yes| L[ConvertFrom-Json]

    L --> F
    F --> M[未サポートデータ型チェック]
    M --> N[SqlInstanceループ]

    N --> O[Connect-DbaInstance]
    O --> P[データベース取得]
    P --> Q[テーブルループ]

    Q --> R{ExcludeTableに該当?}
    R -->|Yes| Q
    R -->|No| S{テーブル存在?}
    S -->|No| T[Stop-Function Continue]
    S -->|Yes| U{HasUniqueIndex?}

    T --> Q
    U -->|Yes| V[ユニーク値生成ループ]
    U -->|No| W[カラム処理]

    V --> W
    W --> X[INSERT文構築]
    X --> Y[行数ループ]

    Y --> Z[カラムループ]
    Z --> AA{Nullable & ModulusFactor該当?}
    AA -->|Yes| AB[NULL設定]
    AA -->|No| AC{Identityカラム?}

    AC -->|Yes| AD[Identity値計算]
    AC -->|No| AE[Get-DbaRandomizedValue]

    AB --> AF[値をInsertに追加]
    AD --> AF
    AE --> AF

    AF --> AG{次のカラム?}
    AG -->|Yes| Z
    AG -->|No| AH{次の行?}
    AH -->|Yes| Y
    AH -->|No| AI[トランザクション実行]

    AI --> AJ{実行成功?}
    AJ -->|No| AK[Stop-Function]
    AJ -->|Yes| AL[結果オブジェクト出力]

    AK --> Q
    AL --> AM{次のテーブル?}
    AM -->|Yes| Q
    AM -->|No| AN{次のインスタンス?}
    AN -->|Yes| N
    AN -->|No| AO[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Localeデフォルト | Locale未指定時は'en'（英語） | Locale未指定 |
| BR-002 | ModulusFactor | 10行ごとにNULL値を設定 | Nullableカラム、ModulusFactor=10（デフォルト） |
| BR-003 | ユニークインデックス | ユニークインデックスを持つカラムは一意な値を生成 | HasUniqueIndex=true |
| BR-004 | IDENTITY処理 | IDENTITYカラムはSET IDENTITY_INSERTを使用 | Identityカラム存在時 |
| BR-005 | TruncateTable | TruncateTable=trueの場合、データ生成前にテーブルをTRUNCATE | 構成で指定 |
| BR-006 | 未サポートデータ型 | hierarchyid、geography、xml、geometryは非対応 | 常時 |

### 計算ロジック

**次のIDENTITY値の計算**:
```
nextIdentity = CurrentIdentity + IdentityIncrement
```

**NULL頻度の計算**:
```
(nullmod++) % ModulusFactor == 0 の場合にNULL
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| TruncateTable | 対象テーブル | TRUNCATE | テーブル内データ削除（オプション） |
| データ生成 | 対象テーブル | INSERT | 生成データの挿入 |
| IDENTITY取得 | sys関数 | SELECT | IDENT_CURRENT, IDENT_INCR, IDENT_SEED |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | FileNotFound | 構成ファイルが存在しない | Stop-Function |
| - | ConfigError | 構成ファイル検証失敗 | Stop-Function |
| - | UnsupportedType | 未サポートデータ型を含む | Stop-Function |
| - | ConnectionError | SQL Server接続失敗 | Stop-Function -Continue |
| - | TableNotFound | テーブルが存在しない | Stop-Function -Continue |
| - | InsertError | INSERT実行失敗 | Stop-Function -Continue |

### リトライ仕様

リトライ機能なし（エラー発生時は次のテーブル/インスタンスに継続）

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

- INSERT操作はトランザクション内で実行
- $sqlconn.BeginTransaction()でトランザクション開始
- 成功時: $transaction.Commit()
- 失敗時: エラーハンドリング（明示的なロールバックなし）

## パフォーマンス要件

- 行数に比例した処理時間が発生
- ユニークインデックス値の生成は追加のオーバーヘッド
- ConfirmImpact='High'（大量データ生成のため確認推奨）

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

- 生成データは偽データであり、本番データは含まない
- 構成ファイルにはセンシティブな情報を含めないこと推奨

## 備考

- Bogusライブラリに依存（.NET偽データ生成ライブラリ）
- HTTP URLからの構成ファイル読み込みをサポート

---

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

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

### 推奨読解順序

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

JSON構成ファイルの構造とサポートデータ型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | サポートデータ型 | 144行目 | supportedDataTypesリスト |
| 1-2 | Fakerタイプ | 145-149行目 | supportedFakerMaskingTypes, supportedFakerSubTypes |

**読解のコツ**: Bogusライブラリの構造を理解することで、MaskingTypeとSubTypeの関係が明確になる。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbDataGenerator.ps1 | `public/Invoke-DbaDbDataGenerator.ps1` | 関数全体の構造とパラメータ定義 |

**主要処理フロー**:
1. **114-132行目**: パラメータ定義
2. **134-151行目**: beginブロック（Faker初期化）
3. **153-527行目**: processブロック（メイン処理）

#### Step 3: 構成ファイル読み込みと検証

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ファイル読み込み | 156-180行目 | HTTP/ローカルファイル判定と読み込み |
| 3-2 | 未サポートチェック | 182-191行目 | データ型検証 |

**主要処理フロー**:
- **156-158行目**: HTTP URL判定
- **160-163行目**: ローカルファイル存在確認
- **165-170行目**: Test-DbaDbDataGeneratorConfigによる検証
- **172-179行目**: JSON読み込み

#### Step 4: データ生成と挿入

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ユニーク値生成 | 226-302行目 | HasUniqueIndexのハンドリング |
| 4-2 | INSERT構築 | 369-482行目 | 行ごとのINSERT文構築 |
| 4-3 | トランザクション | 488-518行目 | トランザクション実行と結果出力 |

**主要処理フロー**:
- **326-341行目**: TruncateTableオプション処理
- **343-367行目**: IDENTITY値取得
- **369行目**: INSERT文開始
- **373-482行目**: 行・カラムループによる値生成
- **488-494行目**: SqlCommand実行
- **501-517行目**: Commit & 結果出力

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

```
Invoke-DbaDbDataGenerator
    │
    ├─ New-Object Bogus.Faker
    │
    ├─ Test-DbaDbDataGeneratorConfig
    │      └─ 構成ファイル検証
    │
    ├─ Connect-DbaInstance
    │
    ├─ Get-DbaDatabase
    │
    ├─ Invoke-DbaQuery (TruncateTable時)
    │
    ├─ Get-DbaRandomizedValue
    │      └─ 各カラムの値生成
    │
    └─ SqlCommand.ExecuteNonQuery
           └─ INSERT実行
```

### データフロー図

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

FilePath(JSON) ─────────────▶ JSON構成読み込み
        │                               │
        ▼                               ▼
Locale ──────────────────────▶ Bogus.Faker初期化
CharacterString ─────────────▶
                                        │
SqlInstance ─────────────────▶ Connect-DbaInstance
SqlCredential ───────────────▶
Database ────────────────────▶ Get-DbaDatabase
                                        │
Table ───────────────────────▶ テーブルフィルタリング
ExcludeTable ────────────────▶
                                        │
                               ユニーク値生成（HasUniqueIndex）
                                        │
Column ──────────────────────▶ カラムフィルタリング
ExcludeColumn ───────────────▶
                                        │
MaxValue ────────────────────▶ Get-DbaRandomizedValue
ModulusFactor ───────────────▶
                                        │
                               INSERT文構築 & 実行
                                        │
                                        ▼
                               ┌────────────────────┐
                               │ PSCustomObject生成  │──────▶ コンソール出力
                               │ - Database         │
                               │ - Schema           │
                               │ - Table            │
                               │ - Columns          │
                               │ - Rows             │
                               │ - Elapsed          │
                               │ - Status           │
                               └────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbDataGenerator.ps1 | `public/Invoke-DbaDbDataGenerator.ps1` | ソース | メイン関数定義 |
| Test-DbaDbDataGeneratorConfig.ps1 | `public/Test-DbaDbDataGeneratorConfig.ps1` | ソース | 構成ファイル検証 |
| Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | ソース | ランダム値生成 |
| New-DbaDbDataGeneratorConfig.ps1 | `public/New-DbaDbDataGeneratorConfig.ps1` | ソース | 構成ファイル生成 |
