# 画面設計書 59-データ生成

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるデータ生成（Data Generation）機能の設計仕様を記載したものです。JSON構成ファイルに基づいてリアルなテストデータを生成し、開発・テスト用データベースにデータを挿入する機能を提供します。

### 本画面の処理概要

本機能は、SQL Serverデータベースのテーブルに対してランダムだがリアルなテストデータを生成するPowerShellコマンドを提供します。Bogusライブラリを使用して、名前、住所、電話番号、日付などの本物らしいフェイクデータを生成し、カラムの制約やデータ型を尊重しながらデータを挿入します。

**業務上の目的・背景**：開発環境やテスト環境では、本番データを使用せずにリアルなテストデータが必要になります。本機能により、本番データを使用することなく、開発・テスト・デモ用のデータベースにリアルなデータを投入できます。ID列、ユニークインデックス、NULL許容フィールド、外部キー関係を考慮しながらデータ整合性を維持します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします:
- `Invoke-DbaDbDataGenerator` - データ生成の実行

**主要な操作・処理内容**：
1. JSON構成ファイルの読み込みと検証
2. 対象テーブルとカラムの特定
3. ユニークインデックス用の一意値生成
4. 行ごとのランダム値生成
5. INSERT文の構築とトランザクション実行
6. ID列のIDENTITY_INSERT制御

**画面遷移**：本機能はCLIコマンドであり、構成ファイルをパイプライン入力として受け取ることができます。HTTP URLからの構成ファイル読み込みにも対応しています。

**権限による表示制御**：データ生成操作には対象テーブルへのINSERT権限が必要です。ID列がある場合はIDENTITY_INSERT権限も必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 167 | Invoke-DbaDbDataGenerator | 主機能 | データ生成の実行 |

## 画面種別

実行（CLI）

## URL/ルーティング

PowerShellコマンドとして以下のコマンドレット名でアクセス:
- `Invoke-DbaDbDataGenerator`

## 入出力項目

### Invoke-DbaDbDataGenerator パラメータ

| パラメータ名 | 必須 | 型 | 説明 |
|-------------|------|-----|------|
| SqlInstance | No | DbaInstanceParameter[] | 対象SQL Serverインスタンス |
| SqlCredential | No | PSCredential | 認証用資格情報 |
| Database | No | string[] | 対象データベース名 |
| FilePath | Yes | object | JSON構成ファイルパス（パイプライン入力対応） |
| Locale | No | string | フェイクデータのロケール（デフォルト: en） |
| CharacterString | No | string | ランダム文字列に使用する文字セット |
| Table | No | string[] | 対象テーブル |
| Column | No | string[] | 対象カラム |
| ExcludeTable | No | string[] | 除外テーブル |
| ExcludeColumn | No | string[] | 除外カラム |
| MaxValue | No | int | 生成文字列の最大長 |
| ExactLength | No | switch | 元データと同じ長さの値を生成 |
| ModulusFactor | No | int | NULL生成頻度（デフォルト: 10） |
| Force | No | switch | 確認プロンプトをスキップ |
| EnableException | No | switch | 例外を有効化 |

## 表示項目

### Invoke-DbaDbDataGenerator 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLサーバーインスタンス名 |
| SqlInstance | string | フルインスタンス名 |
| Database | string | データベース名 |
| Schema | string | スキーマ名 |
| Table | string | テーブル名 |
| Columns | array | データ生成されたカラム名 |
| Rows | int | 生成された行数 |
| Elapsed | prettytimespan | 処理時間 |
| Status | string | ステータス（Done） |

## イベント仕様

### 1-データ生成実行

1. 構成ファイルの読み込み（ローカルまたはHTTP URL）
2. Test-DbaDbDataGeneratorConfigによる構成検証
3. SQL Server 2005以上の確認
4. 各テーブルに対するデータ生成処理の実行

### 2-テーブルごとのデータ生成処理

1. テーブルの存在確認
2. ユニークインデックス処理（HasUniqueIndex時）
3. TruncateTable実行（指定時）
4. ID列の現在値取得
5. IDENTITY_INSERT ON設定（ID列あり時）
6. INSERT文の構築（Rows数分）
7. トランザクション内でのINSERT実行
8. IDENTITY_INSERT OFF設定
9. 結果オブジェクトの出力

### 3-ユニークインデックス処理

1. ユニークインデックスを持つカラムの特定
2. 各行に対する一意値の事前生成
3. 重複チェックと再生成ループ

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Invoke-DbaDbDataGenerator | 対象テーブル | INSERT | データ行の挿入 |
| Invoke-DbaDbDataGenerator（TruncateTable） | 対象テーブル | TRUNCATE | テーブルの切り捨て |

### サポートされるデータ型

- bigint, bit, bool, char, date, datetime, datetime2, decimal
- int, float, guid, money, numeric, nchar, ntext, nvarchar
- real, smalldatetime, smallint, text, time, tinyint
- uniqueidentifier, userdefineddatatype, varchar

### サポートされないカラム/データ型

- hierarchyid, geography, geometry, xml

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | エラー | Could not find data generation config file $FilePath | ファイル不存在 |
| MSG-002 | エラー | Errors found testing the configuration file | 構成ファイル検証エラー |
| MSG-003 | エラー | Could not parse masking config file | JSONパースエラー |
| MSG-004 | エラー | $columnType is not supported | サポート外データ型 |
| MSG-005 | エラー | Table $tableName is not present in $db | テーブル不存在 |
| MSG-006 | エラー | Unsupported data type '$columnType' for column $columnName | データ型非対応 |
| MSG-007 | エラー | Unsupported masking type '$maskingType' for column $columnName | マスキングタイプ非対応 |
| MSG-008 | エラー | Could not find any unique values in dictionary | ユニーク値不足 |
| MSG-009 | エラー | Error inserting $schema.$table | INSERT失敗 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 構成ファイル不存在 | Stop-Functionで処理停止 |
| 構成ファイル不正 | Stop-Functionで処理停止 |
| テーブル不存在 | Stop-Functionで該当テーブルスキップ |
| データ型非対応 | Stop-Functionで該当カラムスキップ |
| INSERT失敗 | Stop-Functionで処理停止、エラー出力 |

## 備考

- SQL Server 2005以上が必要（MinimumVersion 9）
- 構成ファイルでRowsプロパティにより生成行数を指定
- TruncateTableオプションで既存データを削除してから生成可能
- ModulusFactorでNULL生成頻度を制御（10 = 約10%がNULL）
- ID列がある場合はIDENTITY_INSERTを自動制御
- HTTP URLからの構成ファイル読み込みに対応

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | supportedDataTypes | `public/Invoke-DbaDbDataGenerator.ps1` 行144 | サポートデータ型の定義 |
| 1-2 | Bogus.Faker | Bogusライブラリ | フェイクデータ生成クラス |

**読解のコツ**: 構成ファイルの各テーブルにはRowsプロパティがあり、生成する行数を指定します。各カラムにMaskingType、SubType、MinValue、MaxValueなどを指定します。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbDataGenerator.ps1 | `public/Invoke-DbaDbDataGenerator.ps1` | データ生成のメインロジック |

**主要処理フロー (Invoke-DbaDbDataGenerator)**:
1. **行134-151**: begin ブロック - Faker初期化、サポート型定義
2. **行156-180**: 構成ファイル読み込みと検証
3. **行193-204**: データベース取得
4. **行214-302**: ユニークインデックス処理
5. **行326-341**: TruncateTable、IDENTITY処理
6. **行373-482**: 行ごとの値生成とINSERT文構築
7. **行488-517**: トランザクション実行と結果出力

#### Step 3: ユニークインデックス処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDbDataGenerator.ps1 | `public/Invoke-DbaDbDataGenerator.ps1` 行228-302 | ユニーク値事前生成ロジック |

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

```
Invoke-DbaDbDataGenerator
    |
    +-- begin ブロック
    |       +-- New-Object Bogus.Faker($Locale)
    |       +-- supportedDataTypes定義
    |       +-- supportedFakerMaskingTypes取得
    |       +-- supportedFakerSubTypes取得
    |
    +-- 構成ファイル読み込み
    |       +-- Invoke-RestMethod (HTTP URL時)
    |       +-- Test-DbaDbDataGeneratorConfig
    |       +-- Get-Content | ConvertFrom-Json
    |
    +-- Connect-DbaInstance (MinimumVersion 9)
    |
    +-- Get-DbaDatabase
    |
    +-- foreach テーブル
    |       +-- テーブル存在確認
    |       |
    |       +-- ユニークインデックス処理
    |       |       +-- foreach ユニークインデックス
    |       |       |       +-- Get-DbaRandomizedValue
    |       |       |       +-- 重複チェック・再生成
    |       |       +-- uniqueValues配列構築
    |       |
    |       +-- TRUNCATE TABLE (TruncateTable時)
    |       |
    |       +-- IDENTITY現在値取得
    |       +-- SET IDENTITY_INSERT ON
    |       |
    |       +-- INSERT文構築
    |       |       +-- foreach 行
    |       |       |       +-- foreach カラム
    |       |       |       |       +-- Get-DbaRandomizedValue
    |       |       |       +-- VALUES句構築
    |       |
    |       +-- トランザクション実行
    |       |       +-- BeginTransaction
    |       |       +-- ExecuteNonQuery
    |       |       +-- Commit
    |       |
    |       +-- SET IDENTITY_INSERT OFF
    |       +-- 結果出力
    |
    +-- SqlConnection.Close()
```

### データフロー図

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

FilePath (JSON/URL) --->  構成ファイル読み込み
                          Invoke-RestMethod または
                          Get-Content | ConvertFrom-Json
                                |
                                v
                   Test-DbaDbDataGeneratorConfig
                   (構成検証)
                                |
                                v
SqlInstance       ------>  Connect-DbaInstance
SqlCredential              (MinimumVersion 9)
                                |
                                v
Database          ------>  Get-DbaDatabase
                                |
                                v
Table/Column      ------>  テーブル/カラム選択
ExcludeTable/             (フィルタリング)
ExcludeColumn                   |
                                v
                   ユニークインデックス処理
                   (HasUniqueIndex時)
                                |
                                v
                   TruncateTable (指定時)
                                |
                                v
                   IDENTITY値取得
                   SET IDENTITY_INSERT ON
                                |
                                v
Locale            ------>  Get-DbaRandomizedValue
CharacterString            (フェイクデータ生成)
MaxValue                        |
                                v
                   INSERT文構築
                   (tableobject.Rows行分)
                                |
                                v
                   トランザクション実行
                   SqlCommand.ExecuteNonQuery
                                |
                                v
                   SET IDENTITY_INSERT OFF
                                |
                                v
                   PSCustomObject  ----->  出力
                   (ComputerName, Schema,
                    Table, Columns, Rows,
                    Elapsed, Status="Done")
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbDataGenerator.ps1 | `public/Invoke-DbaDbDataGenerator.ps1` | ソース | データ生成実行コマンド |
| Test-DbaDbDataGeneratorConfig.ps1 | `public/Test-DbaDbDataGeneratorConfig.ps1` | ソース | 構成ファイル検証 |
| Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | ソース | ランダム値生成 |
| Get-DbaRandomizedType.ps1 | `public/Get-DbaRandomizedType.ps1` | ソース | マスキングタイプ取得 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
