# 機能設計書 472-Set-DbaRgResourcePool

## 概要

本ドキュメントは、SQL Server Resource Governorのリソースプール設定を変更するPowerShellコマンド「Set-DbaRgResourcePool」の機能設計書である。

### 本機能の処理概要

Set-DbaRgResourcePoolは、既存のResource Governorリソースプールに対してCPU、メモリ、IOPSの制限値を変更する機能である。内部プール（SQL Serverクエリ用）と外部プール（R Services、Python等の外部プロセス用）の両方をサポートする。

**業務上の目的・背景**：サーバーのワークロードパターンを分析した後、または容量変更に対応するために、リソースプールの設定を調整する必要がある。例えば、ピーク時間帯に重要なアプリケーションに対してCPU使用率の保証を高めたり、レポート処理のI/O制限を緩和したりする場合に使用する。Resource Governorによるリソース管理は、マルチテナント環境やミッションクリティカルなワークロードの分離に不可欠である。

**機能の利用シーン**：
- 本番環境でリソースプールのCPU/メモリ/IOPS制限を調整する場合
- 開発プールと本番プールのリソース配分比率を変更する場合
- 外部リソースプール（Machine Learning Services）の設定を更新する場合
- 複数のリソースプールを一括で設定変更する場合

**主要な処理内容**：
1. SQL Serverインスタンスへの接続またはパイプライン入力の処理
2. 指定されたリソースプールの取得（Internal/Externalタイプの判定）
3. 各リソース制限パラメータの設定（CPU、メモリ、IOPS）
4. Alter()メソッドによるプール設定の適用
5. Resource Governorの再構成（SkipReconfigureでスキップ可能）
6. 更新後のリソースプール情報の出力

**関連システム・外部連携**：Resource Governorシステム全体との連携。ワークロードグループはリソースプールに依存するため、プール設定の変更はそのプールに属するすべてのワークロードグループに影響する。

**権限による制御**：ALTER RESOURCE GOVERNOR権限またはCONTROL SERVER権限が必要。sysadmin固定サーバーロールのメンバーも操作可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | SQL Server Management Studio - Resource Governor | 参照画面 | リソースプール設定の確認 |

## 機能種別

設定変更処理 / SMOオブジェクト操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | パイプライン入力可能 |
| SqlCredential | PSCredential | No | SQL Server接続用の資格情報 | - |
| ResourcePool | string[] | No | 変更対象のリソースプール名 | InputObjectと排他 |
| Type | string | No | プールタイプ（Internal/External） | ValidateSet: Internal, External。デフォルト: Internal |
| MinimumCpuPercentage | int | No | 最小CPU保証率（0-100） | ValidateRange(0, 100) |
| MaximumCpuPercentage | int | No | 最大CPU使用率（1-100） | ValidateRange(1, 100) |
| CapCpuPercentage | int | No | CPU使用率のハードキャップ（1-100） | ValidateRange(1, 100)。SQL Server 2012以降 |
| MinimumMemoryPercentage | int | No | 最小メモリ保証率（0-100） | ValidateRange(0, 100) |
| MaximumMemoryPercentage | int | No | 最大メモリ使用率（1-100） | ValidateRange(1, 100) |
| MinimumIOPSPerVolume | int | No | 最小IOPS保証（ボリュームあたり） | ValidateRange(0, 2147483647) |
| MaximumIOPSPerVolume | int | No | 最大IOPS制限（ボリュームあたり） | ValidateRange(0, 2147483647) |
| MaximumProcesses | int | No | 外部プロセスの最大数（External用） | Externalタイプのみ |
| SkipReconfigure | switch | No | 自動再構成をスキップ | - |
| InputObject | object[] | No | Get-DbaRgResourcePoolからのパイプ入力 | - |
| WhatIf | switch | No | 実行内容のプレビュー | - |
| Confirm | switch | No | 実行前の確認プロンプト | - |
| EnableException | switch | No | 例外をスローするかどうか | - |

### 入力データソース

- パイプライン経由のResourcePoolオブジェクト（Get-DbaRgResourcePoolから）
- SqlInstanceとResourcePoolパラメータの組み合わせ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverが稼働するコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Id | int | リソースプールの一意識別子 |
| Name | string | リソースプール名 |
| CapCpuPercentage | int | CPU使用率キャップ（SQL Server 2012以降） |
| IsSystemObject | bool | システムリソースプールかどうか |
| MaximumCpuPercentage | int | 最大CPU使用率 |
| MaximumIopsPerVolume | int | 最大IOPS（ボリュームあたり） |
| MaximumMemoryPercentage | int | 最大メモリ使用率 |
| MinimumCpuPercentage | int | 最小CPU保証率 |
| MinimumIopsPerVolume | int | 最小IOPS（ボリュームあたり） |
| MinimumMemoryPercentage | int | 最小メモリ保証率 |
| WorkloadGroups | collection | 関連するワークロードグループ |

### 出力先

パイプライン出力（Microsoft.SqlServer.Management.Smo.ResourcePool または ExternalResourcePool オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   └─ InputObjectまたはResourcePool、SqlInstanceの指定を確認
2. プールタイプの自動判定（InputObject使用時）
   └─ ResourcePool型→Internal、ExternalResourcePool型→External
3. インスタンス接続とプール取得
   └─ 各インスタンスからResourcePoolまたはExternalResourcePoolを取得
4. プール設定の変更
   └─ 各パラメータが指定されている場合のみ対応するプロパティを更新
5. CapCpuPercentageのバージョンチェック
   └─ SQL Server 2012以降でのみ設定可能
6. プール変更の適用
   └─ $resPool.Alter()で変更を適用
7. Resource Governor再構成
   └─ SkipReconfigureでない場合は$server.ResourceGovernor.Alter()を実行
8. 結果出力
   └─ NotePropertyを追加して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObject指定?}
    B -->|No| C{ResourcePool/SqlInstance指定?}
    C -->|No| D[エラー: パラメータ不足]
    C -->|Yes| E[Connect-DbaInstanceで接続]
    B -->|Yes| F[プールタイプを自動判定]
    E --> G[ResourcePoolを取得]
    F --> H[InputObjectを使用]
    G --> I[foreach resPool]
    H --> I
    I --> J{Internalタイプ?}
    J -->|Yes| K[CPU/Memory/IOPS設定]
    J -->|No| L[CPU/Memory/Processes設定]
    K --> M{CapCpuPercentage指定?}
    M -->|Yes| N{SQL 2012以降?}
    N -->|Yes| O[CapCpuPercentageを設定]
    N -->|No| P[警告: バージョン不足]
    M -->|No| Q[Alter実行]
    L --> Q
    O --> Q
    P --> Q
    Q --> R{SkipReconfigure?}
    R -->|Yes| S[警告: 手動再構成必要]
    R -->|No| T[ResourceGovernor.Alter実行]
    S --> U[NoteProperty追加と出力]
    T --> U
    U --> V[次のプールへ]
    V --> I
    D --> W[終了]
    V --> W
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 必須パラメータ | InputObjectまたはResourcePool+SqlInstanceの組み合わせが必要 | 常時 |
| BR-002 | バージョン制限 | CapCpuPercentageはSQL Server 2012以降でのみ有効 | CapCpuPercentageパラメータ指定時 |
| BR-003 | タイプ別パラメータ | MaximumProcessesはExternalタイプでのみ有効 | Externalタイプ使用時 |
| BR-004 | 再構成警告 | SkipReconfigure使用時は手動での再構成が必要 | SkipReconfigure指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プール設定変更 | sys.resource_governor_resource_pools | UPDATE | ALTER RESOURCE POOLにより更新 |
| 再構成 | sys.resource_governor_configuration | UPDATE | ALTER RESOURCE GOVERNORにより更新 |

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

#### sys.resource_governor_resource_pools

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | min_cpu_percent | 0-100 | SMO経由で更新 |
| UPDATE | max_cpu_percent | 1-100 | SMO経由で更新 |
| UPDATE | cap_cpu_percent | 1-100 | SQL Server 2012以降 |
| UPDATE | min_memory_percent | 0-100 | SMO経由で更新 |
| UPDATE | max_memory_percent | 1-100 | SMO経由で更新 |
| UPDATE | min_iops_per_volume | 0-2147483647 | SMO経由で更新 |
| UPDATE | max_iops_per_volume | 0-2147483647 | SMO経由で更新 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ParameterError | パラメータエラー | ResourcePoolもInputObjectも指定されていない | Stop-Functionでエラーメッセージを表示 |
| ConnectionError | 接続エラー | SQL Serverに接続できない | Stop-Functionで処理を中断し次のインスタンスへ |
| AlterError | 変更エラー | プール設定の変更に失敗 | Stop-Functionで処理を中断 |
| ReconfigureError | 再構成エラー | Resource Governorの再構成に失敗 | Stop-Functionで処理を中断 |

### リトライ仕様

リトライ処理は実装されていない。エラー発生時は次のプールの処理に移行する。

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

SMOのAlter()メソッドによる暗黙的なトランザクション管理。プール変更とResource Governor再構成は別々のAlter()呼び出しで実行される。

## パフォーマンス要件

特になし。通常は数秒以内に完了する軽量な操作。

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

- ALTER RESOURCE GOVERNOR権限またはCONTROL SERVER権限が必要
- SQL認証使用時は資格情報がSecureStringとして管理される
- WhatIfパラメータによる事前確認が可能

## 備考

- SQL Server 2008でResource Governorが導入され、2012でCapCpuPercentageが追加された
- ExternalResourcePoolはSQL Server 2016以降のMachine Learning Servicesで使用
- SkipReconfigureを使用した場合、変更は次回の手動再構成またはサーバー再起動まで反映されない

---

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

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

### 推奨読解順序

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

SMOのResourcePoolおよびExternalResourcePoolオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaRgResourcePool.ps1 | `public/Set-DbaRgResourcePool.ps1` | 193-197行目でプールタイプの自動判定ロジックを確認 |

**読解のコツ**: ResourcePoolは$server.ResourceGovernor.ResourcePoolsで、ExternalResourcePoolは$server.ResourceGovernor.ExternalResourcePoolsでアクセスする。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaRgResourcePool.ps1 | `public/Set-DbaRgResourcePool.ps1` | 140-180行目のパラメータ定義を確認 |

**主要処理フロー**:
1. **182-190行目**: 入力検証（InputObjectまたはResourcePool/SqlInstanceの確認）
2. **192-198行目**: InputObject使用時のタイプ自動判定
3. **200-211行目**: インスタンス接続とプール取得
4. **213-251行目**: プロパティ設定（Internal/Externalで分岐）
5. **254-260行目**: Alter()でプール変更を適用
6. **263-271行目**: SkipReconfigureの判定とResource Governor再構成
7. **273-276行目**: NotePropertyを追加して出力

#### Step 3: Internal/External分岐を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaRgResourcePool.ps1 | `public/Set-DbaRgResourcePool.ps1` | 215-251行目のタイプ別設定ロジック |

**主要処理フロー**:
- **215-224行目**: Externalタイプの場合（CPU、Memory、Processes）
- **225-250行目**: Internalタイプの場合（CPU、Memory、IOPS、Cap）
- **244-249行目**: CapCpuPercentageのバージョンチェック（Version.Major >= 11）

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

```
Set-DbaRgResourcePool
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ $server.ResourceGovernor.ResourcePools（Internalタイプ）
    │      └─ リソースプールコレクションを取得
    │
    ├─ $server.ResourceGovernor.ExternalResourcePools（Externalタイプ）
    │      └─ 外部リソースプールコレクションを取得
    │
    ├─ $resPool.Alter()
    │      └─ プール設定の適用
    │
    └─ $server.ResourceGovernor.Alter()
           └─ Resource Governor再構成
```

### データフロー図

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

SqlInstance          ───▶ Connect-DbaInstance ───▶ $server
ResourcePool         ───▶ プール取得 ───▶ $resPool
Type (Internal/External) ───▶ 取得対象の決定
                                    │
MinimumCpuPercentage ───▶ プロパティ設定 ───▶ $resPool.Alter()
MaximumCpuPercentage                        │
CapCpuPercentage                            ▼
MinimumMemoryPercentage ───▶       ResourceGovernor.Alter()
MaximumMemoryPercentage                     │
MinimumIOPSPerVolume                        ▼
MaximumIOPSPerVolume           [ResourcePoolオブジェクト]
MaximumProcesses
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaRgResourcePool.ps1 | `public/Set-DbaRgResourcePool.ps1` | ソース | メイン処理ロジック |
| Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | ソース | プール取得用コマンド（パイプライン入力元） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続用コマンド |
