# 画面設計書 113-リソースプール

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Server Resource Governorリソースプール管理機能の設計仕様を記述する。

### 本画面の処理概要

本機能群は、Resource Governorのリソースプールの作成・取得・設定・削除を行う。リソースプールは、CPU、メモリ、I/Oリソースの物理的な境界を定義し、異なるワークロードに対してリソースを分離・保証する。

**業務上の目的・背景**：マルチテナント環境やOLTP/OLAP混在環境において、ワークロード間でリソースを適切に分離することで、重要なアプリケーションのパフォーマンスを保証し、リソース競合による予期しない性能劣化を防ぐ。内部プール（SQL Serverワークロード用）と外部プール（R/Python/MLサービス用）の両方を管理できる。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドレットを実行する。
- `Get-DbaRgResourcePool` - リソースプールの取得
- `New-DbaRgResourcePool` - リソースプールの作成
- `Set-DbaRgResourcePool` - リソースプールの設定変更
- `Remove-DbaRgResourcePool` - リソースプールの削除

**主要な操作・処理内容**：
1. 既存リソースプールの一覧取得と構成確認
2. カスタムリソースプールの新規作成
3. CPU/メモリ/IOPSの最小・最大制限の設定
4. CPUキャップ（絶対上限）の設定
5. リソースプールの削除

**画面遷移**：本機能はコマンドラインインターフェースであり、画面遷移は存在しない。Get-DbaRgResourcePoolの出力はパイプラインでSet-DbaRgResourcePool、Remove-DbaRgResourcePool、Get-DbaRgWorkloadGroupに渡すことができる。

**権限による表示制御**：参照にはVIEW SERVER STATE権限、変更にはCONTROL SERVER権限またはsysadminロールが必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 463 | Get-DbaRgResourcePool | 主機能 | リソースプールの取得 |
| 466 | New-DbaRgResourcePool | 主機能 | リソースプールの作成 |
| 469 | Remove-DbaRgResourcePool | 主機能 | リソースプールの削除 |
| 472 | Set-DbaRgResourcePool | 補助機能 | リソースプールの設定変更 |

## 画面種別

CLIコマンド群（リソースプール管理）

## URL/ルーティング

```powershell
# リソースプール取得
Get-DbaRgResourcePool -SqlInstance <インスタンス名> [-Type Internal|External]

# リソースプール作成
New-DbaRgResourcePool -SqlInstance <インスタンス名> -ResourcePool <プール名> [-MinimumCpuPercentage <0-100>] [-MaximumCpuPercentage <1-100>] [-CapCpuPercentage <1-100>] [-MinimumMemoryPercentage <0-100>] [-MaximumMemoryPercentage <1-100>] [-MinimumIOPSPerVolume <値>] [-MaximumIOPSPerVolume <値>]

# リソースプール設定
Set-DbaRgResourcePool -SqlInstance <インスタンス名> -ResourcePool <プール名> [-MinimumCpuPercentage <0-100>] ...

# リソースプール削除
Remove-DbaRgResourcePool -SqlInstance <インスタンス名> -ResourcePool <プール名> [-Type Internal|External]
```

## 入出力項目

### Get-DbaRgResourcePool パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | No | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 認証資格情報 |
| Type | string | No | Internal | Internal（内部）またはExternal（外部） |
| InputObject | ResourceGovernor[] | No | - | パイプライン入力 |
| EnableException | switch | No | $false | 例外をスローする |

### New-DbaRgResourcePool パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 認証資格情報 |
| ResourcePool | string[] | Yes | - | リソースプール名 |
| Type | string | No | Internal | Internal/External |
| MinimumCpuPercentage | int | No | 0 | 最小CPU% (0-100) |
| MaximumCpuPercentage | int | No | 100 | 最大CPU% (1-100) |
| CapCpuPercentage | int | No | 100 | CPUキャップ% (1-100) |
| MinimumMemoryPercentage | int | No | 0 | 最小メモリ% (0-100) |
| MaximumMemoryPercentage | int | No | 100 | 最大メモリ% (1-100) |
| MinimumIOPSPerVolume | int | No | 0 | 最小IOPS/ボリューム |
| MaximumIOPSPerVolume | int | No | 0 | 最大IOPS/ボリューム (0=無制限) |
| MaximumProcesses | int | No | - | 最大プロセス数（External用） |
| SkipReconfigure | switch | No | $false | 再構成をスキップ |
| Force | switch | No | $false | 既存プールを削除して再作成 |
| WhatIf | switch | No | - | 実行内容をシミュレート |
| Confirm | switch | No | - | 確認プロンプトを表示 |
| EnableException | switch | No | $false | 例外をスローする |

## 表示項目

### Get-DbaRgResourcePool 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Id | int | リソースプールID |
| Name | string | リソースプール名 |
| CapCpuPercentage | int | CPUキャップ% |
| IsSystemObject | bool | システムオブジェクトフラグ |
| MaximumCpuPercentage | int | 最大CPU% |
| MaximumIopsPerVolume | int | 最大IOPS/ボリューム |
| MaximumMemoryPercentage | int | 最大メモリ% |
| MinimumCpuPercentage | int | 最小CPU% |
| MinimumIopsPerVolume | int | 最小IOPS/ボリューム |
| MinimumMemoryPercentage | int | 最小メモリ% |
| WorkloadGroups | collection | ワークロードグループコレクション |

## イベント仕様

### 1-Get-DbaRgResourcePool実行

1. SqlInstanceが指定された場合、Get-DbaResourceGovernorを呼び出し
2. InputObjectまたは取得したResourceGovernorから:
   - Type=External: ExternalResourcePoolsを取得
   - Type=Internal: ResourcePoolsを取得
3. ComputerName、InstanceName、SqlInstanceをNotePropertyとして追加
4. Select-DefaultViewで出力整形

### 2-New-DbaRgResourcePool実行

1. Connect-DbaInstanceでSQL Serverに接続
2. 既存プールの存在確認（Get-DbaRgResourcePool）
3. 既存の場合:
   - Forceあり: 既存プールを削除
   - Forceなし: エラー出力してスキップ
4. SMOで新しいリソースプールオブジェクトを作成:
   - Internal: Microsoft.SqlServer.Management.Smo.ResourcePool
   - External: Microsoft.SqlServer.Management.Smo.ExternalResourcePool
5. $newResourcePool.Create()で作成
6. SkipReconfigureでない場合、$server.ResourceGovernor.Alter()
7. Set-DbaRgResourcePoolで各プロパティを設定
8. Get-DbaRgResourcePoolで結果を出力

### 3-Set-DbaRgResourcePool実行

1. ResourcePoolまたはInputObjectからプールを取得
2. パラメータに応じてプロパティを更新:
   - MinimumCpuPercentage
   - MaximumCpuPercentage
   - CapCpuPercentage (SQL Server 2012以降)
   - MinimumMemoryPercentage
   - MaximumMemoryPercentage
   - MinimumIOPSPerVolume
   - MaximumIOPSPerVolume
   - MaximumProcesses (External用)
3. $resPool.Alter()で変更適用
4. SkipReconfigureでない場合、$server.ResourceGovernor.Alter()

### 4-Remove-DbaRgResourcePool実行

1. ResourcePoolまたはInputObjectからプールを取得
2. $resPool.Drop()でプール削除
3. SkipReconfigureでない場合、$server.ResourceGovernor.Alter()

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

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

| 操作（イベント） | 対象オブジェクト | 操作種別 | 概要 |
|----------------|-----------------|---------|------|
| New Pool | sys.dm_resource_governor_resource_pools | INSERT | プール作成 |
| Set Pool | sys.dm_resource_governor_resource_pools | UPDATE | プール設定変更 |
| Remove Pool | sys.dm_resource_governor_resource_pools | DELETE | プール削除 |
| Reconfigure | Resource Governor | EXECUTE | 設定適用 |

### SQL操作詳細

| 操作 | 実行方法 | 備考 |
|-----|---------|------|
| プール作成 | SMO: ResourcePool.Create() | CREATE RESOURCE POOL相当 |
| プール変更 | SMO: ResourcePool.Alter() | ALTER RESOURCE POOL相当 |
| プール削除 | SMO: ResourcePool.Drop() | DROP RESOURCE POOL相当 |
| 再構成 | SMO: ResourceGovernor.Alter() | ALTER RESOURCE GOVERNOR RECONFIGURE相当 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 発生条件 |
|---------------|---------------|---------|
| エラー | Resource Pool '{name}' already exists | Forceなしで既存プール |
| 警告 | Not reconfiguring the Resource Governor after creating a new pool may create problems | SkipReconfigure使用時 |
| 警告 | Resource pool changes will not take effect until it is reconfigured | SkipReconfigure使用時 |
| 警告 | SQL Server version 2012+ required to specify a CPU percentage cap | CapCpuPercentageがSQL Server 2008/2008R2で使用された場合 |
| エラー | Could not remove existing resource pool | 削除失敗 |
| エラー | You must pipe in a resource pool or specify a ResourcePool | パラメータ不足 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| プール既存（Force=false） | Stop-Functionでエラー出力、return |
| プール削除失敗 | Stop-Functionでエラー出力、Continue |
| プール作成失敗 | Stop-Functionでエラー出力、Continue |
| CapCpuPercentage（SQL 2008/R2） | 警告メッセージ出力、設定スキップ |
| パラメータ不足 | Stop-Functionでエラー出力、return |

## 備考

- CapCpuPercentageはSQL Server 2012以降でのみ使用可能（バージョン11以上）
- システムプール（internal, default）は変更・削除不可
- MinimumIOPSPerVolume、MaximumIOPSPerVolumeは0で無制限
- External typeはR/Python/Machine Learningサービス用
- 作成後のReconfigure省略は問題を引き起こす可能性があるため警告を出力
- Forceオプションは既存プール削除後に新規作成（ワークロードグループも削除される）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | 出力プロパティ（行33-60）を確認 |

**読解のコツ**: Microsoft.SqlServer.Management.Smo.ResourcePool（内部）またはExternalResourcePool（外部）がベース。

#### Step 2: 取得処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | 行103-127: Type分岐処理 |

**主要処理フロー**:
1. **行104-105**: SqlInstance指定時、Get-DbaResourceGovernorを呼び出し
2. **行109-116**: Type=Externalの処理
3. **行117-124**: Type=Internalの処理

#### Step 3: 作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaRgResourcePool.ps1 | `public/New-DbaRgResourcePool.ps1` | 行158-231: 作成処理 |

**主要処理フロー**:
1. **行167-181**: 既存プール確認とForce処理
2. **行184-214**: SMOオブジェクト作成とプロパティ設定
3. **行216-221**: Reconfigure処理
4. **行223**: Set-DbaRgResourcePoolで詳細設定

#### Step 4: 設定処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaRgResourcePool.ps1 | `public/Set-DbaRgResourcePool.ps1` | 行213-277: 設定変更処理 |

**主要処理フロー**:
1. **行215-225**: Type判定（Internal/External）
2. **行226-250**: プロパティ設定（$PSBoundParameters.Keys確認）
3. **行254-260**: Alter()実行
4. **行263-271**: Reconfigure処理

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

```
Get-DbaRgResourcePool
    │
    +-- Get-DbaResourceGovernor
    │       └─ ResourceGovernorオブジェクト取得
    │
    └── Select-DefaultView
            └─ 出力プロパティ選択

New-DbaRgResourcePool
    │
    +-- Connect-DbaInstance
    │
    +-- Get-DbaRgResourcePool
    │       └─ 既存プール確認
    │
    +-- New-Object ResourcePool / ExternalResourcePool
    │       └─ SMOオブジェクト作成
    │
    +-- ResourcePool.Create()
    │
    +-- ResourceGovernor.Alter()
    │       └─ Reconfigure
    │
    +-- Set-DbaRgResourcePool
    │       └─ プロパティ設定
    │
    └── Get-DbaRgResourcePool
            └─ 結果出力

Set-DbaRgResourcePool
    │
    +-- Connect-DbaInstance
    │
    +-- ResourcePool.Alter()
    │       └─ プロパティ変更適用
    │
    └── ResourceGovernor.Alter()
            └─ Reconfigure

Remove-DbaRgResourcePool
    │
    +-- Connect-DbaInstance
    │
    +-- ResourcePool.Drop()
    │       └─ プール削除
    │
    └── ResourceGovernor.Alter()
            └─ Reconfigure
```

### データフロー図

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

SqlInstance ──────────────> Get-DbaResourceGovernor ───────────>
Type ─────────────────────> ResourcePools/ExternalResourcePools > ResourcePool[]

ResourcePool名 ───────────> New-Object ResourcePool ───────────>
CPU/Memory/IOPS設定 ──────> Create() ─────────────────────────>
                            Set-DbaRgResourcePool ────────────> ResourcePool
                            Alter() ──────────────────────────>

InputObject ──────────────> プロパティ更新 ───────────────────>
設定パラメータ ───────────> Alter() ──────────────────────────> ResourcePool
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | ソース | リソースプール取得 |
| New-DbaRgResourcePool.ps1 | `public/New-DbaRgResourcePool.ps1` | ソース | リソースプール作成 |
| Set-DbaRgResourcePool.ps1 | `public/Set-DbaRgResourcePool.ps1` | ソース | リソースプール設定 |
| Remove-DbaRgResourcePool.ps1 | `public/Remove-DbaRgResourcePool.ps1` | ソース | リソースプール削除 |
| Get-DbaResourceGovernor.ps1 | `public/Get-DbaResourceGovernor.ps1` | ソース | ResourceGovernor取得（依存） |
