# 機能設計書 459-Copy-DbaResourceGovernor

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`Copy-DbaResourceGovernor`関数の機能設計を定義する。この関数はSQL ServerのResource Governor構成（リソースプール、ワークロードグループ、分類関数）をソースインスタンスからターゲットインスタンスにコピーする。

### 本機能の処理概要

**業務上の目的・背景**：Resource Governorは、SQL Server Enterprise Editionで利用できるワークロード管理機能であり、CPU、メモリ、I/Oリソースの割り当てを制御する。本関数は、複雑なResource Governor構成を複数のサーバー間で一貫して展開することを可能にし、新サーバーのセットアップやDR環境の構築を効率化する。

**機能の利用シーン**：
- 新しいサーバーへのResource Governor構成の展開時
- DR環境へのワークロード管理設定のレプリケーション時
- サーバーマイグレーション時の構成移行時
- 標準化されたResource Governor構成の複数サーバーへの適用時

**主要な処理内容**：
1. ソースサーバーからの分類関数の取得とコピー
2. リソースプールのコピー（内部/デフォルトプールを除く）
3. 各リソースプールに関連付けられたワークロードグループのコピー
4. Resource Governorの再構成（ALTER RESOURCE GOVERNOR RECONFIGURE）
5. ソースのResource Governor有効/無効状態の反映

**関連システム・外部連携**：SQL Server Resource Governor、sys.dm_resource_governor_configuration、master.dbo.UserDefinedFunctions

**権限による制御**：ソースおよびターゲットサーバーでsysadmin権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | SQL Server Management Studio - Resource Governor | 参照画面 | Resource Governor構成管理に相当 |

## 機能種別

マイグレーション / 構成コピー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | ソースSQL Serverインスタンス | 最小バージョン10（SQL 2008） |
| SourceSqlCredential | PSCredential | No | ソース接続用資格情報 | 有効な認証情報 |
| Destination | DbaInstanceParameter[] | Yes | ターゲットSQL Serverインスタンス | 複数インスタンス対応 |
| DestinationSqlCredential | PSCredential | No | ターゲット接続用資格情報 | 有効な認証情報 |
| ResourcePool | Object[] | No | コピーするリソースプール名 | タブ補完対応 |
| ExcludeResourcePool | Object[] | No | 除外するリソースプール名 | タブ補完対応 |
| Force | Switch | No | 既存オブジェクトを上書き | なし |
| EnableException | Switch | No | 例外を有効化 | なし |

### 入力データソース

- パラメータ入力
- ソースサーバーのResource Governor構成

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作実行日時 |
| SourceServer | String | ソースサーバー名 |
| DestinationServer | String | ターゲットサーバー名 |
| Name | String | オブジェクト名 |
| Type | String | オブジェクトタイプ（Resource Governor Settings/Pool/Workgroup） |
| Status | String | 操作結果（Successful/Skipped/Failed） |
| Notes | String | 補足情報 |

### 出力先

パイプラインにMigrationObjectタイプのカスタムオブジェクトを出力

## 処理フロー

### 処理シーケンス

```
1. ソースサーバー接続
   └─ Connect-DbaInstance（最小バージョン10）
2. 分類関数の取得
   └─ Get-DbaRgClassifierFunctionでソースの分類関数取得
3. 各ターゲットサーバーに対する処理（foreach）
   ├─ ターゲット接続（最小バージョン10）
   ├─ Enterprise Edition確認
   ├─ 分類関数のコピー
   │   ├─ ターゲットに分類関数なし: 新規作成
   │   ├─ ターゲットに分類関数あり && Force: 削除して再作成
   │   └─ ターゲットに分類関数あり && !Force: スキップ
   ├─ リソースプールのコピー
   │   ├─ internal/defaultプールを除外
   │   ├─ 既存プール && Force: ワークロードグループ削除 → プール削除 → 再作成
   │   └─ 既存プール && !Force: スキップ
   └─ Resource Governor再構成
       ├─ ソースが無効: ALTER RESOURCE GOVERNOR DISABLE
       └─ ソースが有効: ALTER RESOURCE GOVERNOR RECONFIGURE
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance ソース]
    B --> C[Get-DbaRgClassifierFunction]
    C --> D[foreach Destination]
    D --> E[Connect-DbaInstance ターゲット]
    E --> F{Enterprise Edition?}
    F -->|No| G[警告表示]
    F -->|Yes| H{分類関数処理}
    G --> H
    H --> I{ソースに分類関数?}
    I -->|No| J[スキップ]
    I -->|Yes| K{ターゲットに分類関数?}
    K -->|No| L[関数作成・マッピング]
    K -->|Yes| M{Force?}
    M -->|No| N[スキップ]
    M -->|Yes| O[関数削除・再作成]
    J --> P[リソースプール処理]
    L --> P
    N --> P
    O --> P
    P --> Q[foreach pool]
    Q --> R{ターゲットに存在?}
    R -->|No| S[プール作成]
    R -->|Yes| T{Force?}
    T -->|No| U[スキップ]
    T -->|Yes| V[ワークロードグループ削除]
    V --> W[プール削除]
    W --> S
    S --> X[foreach workloadGroup]
    X --> Y[ワークロードグループ作成]
    Y --> Z[RECONFIGURE]
    Z --> AA[次のワークロードグループ]
    AA --> X
    X -->|完了| AB[次のプール]
    U --> AB
    AB --> Q
    Q -->|完了| AC[最終RECONFIGURE]
    AC --> AD{ソースRG有効?}
    AD -->|No| AE[DISABLE]
    AD -->|Yes| AF[RECONFIGURE]
    AE --> AG[次のターゲット]
    AF --> AG
    AG --> D
    D -->|完了| AH[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Enterprise Edition限定 | Resource GovernorはEnterprise/Datacenter/Developer Editionでのみ有効 | 常時適用 |
| BR-002 | システムプール除外 | internal/defaultリソースプールは自動的に除外 | 常時適用 |
| BR-003 | Force上書き | -Force指定時は既存オブジェクトを削除して再作成 | Force=true |
| BR-004 | ワークロードグループ連動削除 | プール削除前に関連するワークロードグループを先に削除 | Force=true |
| BR-005 | 状態同期 | ソースのResource Governor有効/無効状態をターゲットに反映 | 常時適用 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 分類関数作成 | master.sys.objects | INSERT | ユーザー定義関数の作成 |
| プール作成 | sys.resource_governor_resource_pools | INSERT | リソースプールの作成 |
| ワークロードグループ作成 | sys.resource_governor_workload_groups | INSERT | ワークロードグループの作成 |
| 構成変更 | sys.dm_resource_governor_configuration | UPDATE | Resource Governor構成の適用 |

### テーブル別操作詳細

#### sys.resource_governor_resource_pools

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | ソースプール名 | リソースプール名 |
| INSERT | min_cpu_percent | ソース値 | 最小CPU% |
| INSERT | max_cpu_percent | ソース値 | 最大CPU% |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | ConnectionError | ソース/ターゲット接続失敗 | 接続情報確認 |
| N/A | Edition制限 | Enterprise Edition以外 | 警告表示のみ（続行） |
| N/A | プール削除失敗 | ワークロードグループ削除エラー | Force時のエラー処理 |

### リトライ仕様

本関数にリトライ機能は実装されていない。

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

各オブジェクトの作成は個別トランザクションで実行。エラー発生時は途中状態で停止し、以前の変更は維持される。

## パフォーマンス要件

Resource Governor構成のコピーは通常数秒で完了。多数のワークロードグループがある場合は処理時間が増加。

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

- ソースおよびターゲットサーバーでsysadmin権限が必要
- SqlCredentialはSecureStringとして処理
- ConfirmImpact = 'Medium'により、重要な操作時に確認

## 備考

- 250行目に$poolではなく$pools（タイポ）の可能性
- 分類関数のSET QUOTED_IDENTIFIER/SET ANSI_NULLSステートメントは除外
- Resource Governor RECONFIGUREは各操作後に実行
- ソースがResource Governor無効の場合、ターゲットも無効に設定

---

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

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

### 推奨読解順序

#### Step 1: 関数構造とパラメータを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaResourceGovernor.ps1 | `public/Copy-DbaResourceGovernor.ps1` | param()ブロック（99-111行目） |

**読解のコツ**: ResourcePool/ExcludeResourcePoolはタブ補完対応。Force指定でConfirmPreference = 'none'に設定。

#### Step 2: 分類関数コピー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaResourceGovernor.ps1 | `public/Copy-DbaResourceGovernor.ps1` | 分類関数処理（152-243行目） |

**主要処理フロー**:
1. **159行目**: ソースに分類関数がない場合はスキップ
2. **166-172行目**: ターゲットに分類関数がない場合の新規作成
3. **192-230行目**: Force指定時の削除・再作成処理

#### Step 3: リソースプールコピー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaResourceGovernor.ps1 | `public/Copy-DbaResourceGovernor.ps1` | プール処理（246-355行目） |

**主要処理フロー**:
- **247-253行目**: プールフィルタリング（internal/default除外）
- **269-276行目**: 既存プールスキップ処理
- **278-303行目**: Force時のプール削除処理
- **308-344行目**: プール作成とワークロードグループコピー

#### Step 4: 最終構成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Copy-DbaResourceGovernor.ps1 | `public/Copy-DbaResourceGovernor.ps1` | 最終処理（357-392行目） |

**主要処理フロー**:
- **364-366行目**: ソースが無効の場合はDISABLE
- **373-374行目**: ソースが有効の場合はRECONFIGURE

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

```
Copy-DbaResourceGovernor
    │
    ├─ Connect-DbaInstance (ソース)
    │      └─ MinimumVersion 10
    │
    ├─ Get-DbaRgClassifierFunction
    │
    └─ foreach (Destination)
           │
           ├─ Connect-DbaInstance (ターゲット)
           │
           ├─ 分類関数処理
           │      ├─ Drop existing function
           │      ├─ Create function from script
           │      ├─ ALTER RESOURCE GOVERNOR WITH (CLASSIFIER_FUNCTION = ...)
           │      └─ ALTER RESOURCE GOVERNOR RECONFIGURE
           │
           ├─ foreach (pool)
           │      │
           │      ├─ Force時: Drop workload groups
           │      ├─ Force時: Drop pool
           │      ├─ Create pool from script
           │      │
           │      └─ foreach (workloadGroup)
           │             ├─ Create workgroup from script
           │             └─ ALTER RESOURCE GOVERNOR RECONFIGURE
           │
           └─ 最終RECONFIGURE/DISABLE
```

### データフロー図

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

Source ──────────────────────▶ Connect-DbaInstance ──────────────────▶ ソース接続
                                   │
                             Get-DbaRgClassifierFunction ────────────▶ 分類関数情報
                                   │
Destination ─────────────────▶ Connect-DbaInstance ──────────────────▶ ターゲット接続
                                   │
ResourcePool/Exclude ────────▶ プールフィルタリング ─────────────────▶ 対象プール特定
                                   │
Force ───────────────────────▶ 既存オブジェクト削除 ─────────────────▶ クリーンアップ
                                   │
                             Script() + Query() ─────────────────────▶ オブジェクト作成
                                   │
                             ALTER RESOURCE GOVERNOR ────────────────▶ 構成適用
                                   │
                                   └──────────────────────────────────▶ MigrationObject
                                                                        (Status, Notes)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaResourceGovernor.ps1 | `public/Copy-DbaResourceGovernor.ps1` | ソース | メイン関数定義 |
| Get-DbaRgClassifierFunction.ps1 | `public/Get-DbaRgClassifierFunction.ps1` | ソース | 分類関数取得 |
| Get-DbaResourceGovernor.ps1 | `public/Get-DbaResourceGovernor.ps1` | ソース | Resource Governor情報取得 |
| Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | ソース | リソースプール取得 |
| Get-DbaRgWorkloadGroup.ps1 | `public/Get-DbaRgWorkloadGroup.ps1` | ソース | ワークロードグループ取得 |
