# 機能設計書 466-New-DbaRgResourcePool

## 概要

本ドキュメントは、SQL Server Resource Governorのリソースプールを新規作成するNew-DbaRgResourcePool機能の設計を記述する。

### 本機能の処理概要

New-DbaRgResourcePoolは、SQL Server Resource Governorに新しいリソースプールを作成する機能である。CPU、メモリ、I/Oリソースの制限を定義し、SQL Serverワークロード用の内部プールと外部プロセス（R/Pythonサービス）用の外部プールの両方をサポートする。

**業務上の目的・背景**：リソースプールはResource Governorの基盤となる構成要素であり、異なるワークロードに対してリソースの境界を定義する。この機能を使用することで、DBAは特定のワークロード向けにCPU、メモリ、IOPSの最小値と最大値を設定し、アプリケーション間のリソース競合を防止できる。これにより、クリティカルなアプリケーションに必要なリソースを保証しつつ、他のワークロードがサーバー全体のリソースを独占することを防ぐことができる。

**機能の利用シーン**：
- マルチテナント環境でのリソース分離設定
- 報告ワークロードとOLTPワークロードの分離
- バッチ処理用のリソース制限設定
- Machine Learning Servicesの外部プロセス用リソース制御

**主要な処理内容**：
1. 対象SQL Serverインスタンスに接続
2. 既存プールの確認（-Force指定時は削除）
3. 新しいリソースプールオブジェクトを作成
4. SMOのCreate()メソッドでプールを作成
5. Resource Governorを再構成して変更を適用
6. Set-DbaRgResourcePoolでプロパティを設定

**関連システム・外部連携**：Set-DbaRgResourcePoolを内部的に呼び出してプロパティを設定する。SMOを使用してResource Governorを操作する。

**権限による制御**：CONTROL SERVER権限またはsysadminロールが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 113 | リソースプール | 主機能 | リソースプールの作成 |

## 機能種別

INSERT / 新規作成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | ValueFromPipeline |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| ResourcePool | String[] | No | 作成するリソースプール名 | - |
| Type | String | No | プールタイプ | ValidateSet: Internal, External。デフォルト: Internal |
| MinimumCpuPercentage | Int | No | 最小CPUパーセンテージ | ValidateRange(0, 100)。デフォルト: 0 |
| MaximumCpuPercentage | Int | No | 最大CPUパーセンテージ | ValidateRange(1, 100)。デフォルト: 100 |
| CapCpuPercentage | Int | No | CPU上限パーセンテージ | ValidateRange(1, 100)。デフォルト: 100。SQL2012+ |
| MinimumMemoryPercentage | Int | No | 最小メモリパーセンテージ | ValidateRange(0, 100)。デフォルト: 0 |
| MaximumMemoryPercentage | Int | No | 最大メモリパーセンテージ | ValidateRange(1, 100)。デフォルト: 100 |
| MinimumIOPSPerVolume | Int | No | ボリュームあたりの最小IOPS | ValidateRange(0, 2147483647)。デフォルト: 0 |
| MaximumIOPSPerVolume | Int | No | ボリュームあたりの最大IOPS | ValidateRange(0, 2147483647)。デフォルト: 0 |
| MaximumProcesses | Int | No | 外部プールの最大プロセス数 | Externalプール用 |
| SkipReconfigure | switch | No | 再構成をスキップ | - |
| Force | switch | No | 既存プールを削除して再作成 | - |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- パラメータ入力（コマンドライン）
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名 |
| Id | Int32 | リソースプールの一意識別子 |
| Name | String | リソースプール名 |
| CapCpuPercentage | Int32 | CPU上限パーセンテージ |
| IsSystemObject | Boolean | システム定義プールかどうか |
| MaximumCpuPercentage | Int32 | 最大CPUパーセンテージ |
| MaximumIopsPerVolume | Int32 | ボリュームあたりの最大IOPS |
| MaximumMemoryPercentage | Int32 | 最大メモリパーセンテージ |
| MinimumCpuPercentage | Int32 | 最小CPUパーセンテージ |
| MinimumIopsPerVolume | Int32 | ボリュームあたりの最小IOPS |
| MinimumMemoryPercentage | Int32 | 最小メモリパーセンテージ |
| WorkloadGroups | WorkloadGroupCollection | 関連ワークロードグループ |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 各SqlInstanceに対して繰り返し処理
   └─ Connect-DbaInstanceで接続
2. 各ResourcePool名に対して繰り返し処理
3. 既存プールの確認
   ├─ 存在 + Force: 既存プールを削除
   └─ 存在 + not Force: エラー終了
4. 新しいプールオブジェクトを作成
   ├─ External: New-Object ExternalResourcePool
   └─ Internal: New-Object ResourcePool
5. SMOのCreate()メソッドでプールを作成
6. Resource Governorの再構成
   ├─ SkipReconfigure: 警告を出力してスキップ
   └─ 通常: $server.ResourceGovernor.Alter()
7. Set-DbaRgResourcePoolでプロパティを設定
8. Get-DbaRgResourcePoolで作成結果を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SqlInstanceループ開始]
    B --> C[Connect-DbaInstance]
    C --> D[ResourcePoolループ開始]
    D --> E[既存プール確認]
    E --> F{プール存在?}
    F -->|Yes| G{Force指定?}
    G -->|Yes| H[既存プール削除]
    G -->|No| I[Stop-Function: 既存エラー]
    F -->|No| J[新規プール作成]
    H --> J
    I --> D
    J --> K{Type?}
    K -->|External| L[New-Object ExternalResourcePool]
    K -->|Internal| M[New-Object ResourcePool]
    L --> N[Create実行]
    M --> N
    N --> O{SkipReconfigure?}
    O -->|Yes| P[警告出力]
    O -->|No| Q[ResourceGovernor.Alter]
    P --> R[Set-DbaRgResourcePool]
    Q --> R
    R --> S[Get-DbaRgResourcePool出力]
    S --> D
    D --> B
    B --> T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | プール名一意性 | リソースプール名はResource Governor内で一意 | 常に適用 |
| BR-002 | Force動作 | -Force指定時は既存プールを削除して再作成 | 既存プール存在時 |
| BR-003 | SkipReconfigure警告 | 再構成をスキップすると新プールは即座に有効にならない | SkipReconfigure指定時 |
| BR-004 | プールタイプ分離 | Internal/Externalは異なるSMOクラスで管理 | 常に適用 |
| BR-005 | ShouldProcess対応 | -WhatIfと-Confirmをサポート | 常に適用 |

### 計算ロジック

該当なし（構成作成機能のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プール作成 | sys.resource_governor_resource_pools | INSERT | 新規リソースプールの登録 |
| プール削除 | sys.resource_governor_resource_pools | DELETE | Force指定時の既存プール削除 |
| 再構成 | - | ALTER | Resource Governor再構成 |

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

SMOのCreate()、Drop()、Alter()メソッドが内部的にT-SQLを生成・実行する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | 資格情報とネットワーク接続を確認 |
| ResourceExists | 既存エラー | プールが既に存在し-Force未指定 | -Forceを指定するか別名を使用 |
| - | 削除失敗 | Force指定時の既存プール削除失敗 | プールに関連付けられたワークロードグループを確認 |
| - | 作成失敗 | Create()実行時のエラー | エラーメッセージを確認 |

### リトライ仕様

リトライ処理は実装されていない。

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

SMOのCreate()による単一操作。明示的なトランザクション管理は実装されていないが、Resource Governorの再構成が失敗した場合、プール作成は有効にならない。

## パフォーマンス要件

- メタデータ操作のため、軽量な処理
- Resource Governor再構成に数秒かかる場合がある

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

- CONTROL SERVER権限またはsysadminロールが必要
- ShouldProcessによる確認機能を提供
- SqlCredentialパラメータによる安全な認証情報の受け渡し

## 備考

- Resource GovernorはSQL Server 2008 Enterprise Edition以降で利用可能
- External Resource PoolはSQL Server 2016以降のMachine Learning Services向け
- CapCpuPercentageはSQL Server 2012以降で利用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaRgResourcePool.ps1 | `public/New-DbaRgResourcePool.ps1` | .OUTPUTSセクション（88-110行目）で出力オブジェクトの構造を確認 |

**読解のコツ**: Type=Internal時はResourcePool、Type=External時はExternalResourcePoolを作成。両者は異なるSMOクラス。

#### Step 2: パラメータ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaRgResourcePool.ps1 | `public/New-DbaRgResourcePool.ps1` | paramブロック（126-157行目）でパラメータ定義を確認 |

**読解のコツ**: ParameterSetName="Internal"/"External"でパラメータセットが分離されている。ValidateRangeで値の範囲を制限。

#### Step 3: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaRgResourcePool.ps1 | `public/New-DbaRgResourcePool.ps1` | processブロック（158-231行目）がメイン処理 |

**主要処理フロー**:
1. **159-164行目**: SqlInstanceループ開始、Connect-DbaInstanceで接続
2. **166-181行目**: 既存プール確認、Force指定時は削除
3. **184-214行目**: プール作成（External/Internal分岐）
4. **186-196行目**: External用splat設定、New-Object ExternalResourcePool、Create()
5. **198-213行目**: Internal用splat設定、New-Object ResourcePool、Create()
6. **216-221行目**: Resource Governor再構成（SkipReconfigureチェック）
7. **223行目**: Set-DbaRgResourcePoolでプロパティ設定
8. **228行目**: Get-DbaRgResourcePoolで結果出力

#### Step 4: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaRgResourcePool.ps1 | `public/Set-DbaRgResourcePool.ps1` | プロパティ設定処理 |
| 4-2 | Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | 結果取得処理 |

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

```
New-DbaRgResourcePool
    │
    ├─ Connect-DbaInstance
    │
    ├─ Get-DbaRgResourcePool (既存確認)
    │
    ├─ $existingResourcePool.Drop() (Force時)
    │
    ├─ New-Object ResourcePool/ExternalResourcePool
    │
    ├─ $newResourcePool.Create()
    │
    ├─ $server.ResourceGovernor.Alter() (再構成)
    │
    ├─ Set-DbaRgResourcePool (プロパティ設定)
    │
    └─ Get-DbaRgResourcePool (結果出力)
```

### データフロー図

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

SqlInstance ─────────▶ Connect-DbaInstance
                              │
                              ▼
ResourcePool名 ────────▶ 既存プール確認
                              │
               ┌──────────────┴──────────────┐
               ▼                              ▼
        既存あり+Force              既存なし/削除済み
               │                              │
               ▼                              │
         Drop()                               │
               │                              │
               └──────────────┬───────────────┘
                              ▼
                    New-Object + Create()
                              │
                              ▼
                   ResourceGovernor.Alter()
                              │
                              ▼
                    Set-DbaRgResourcePool
                              │
                              ▼
                   Get-DbaRgResourcePool ────▶ ResourcePool Object
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaRgResourcePool.ps1 | `public/New-DbaRgResourcePool.ps1` | ソース | 本機能のメイン実装 |
| Set-DbaRgResourcePool.ps1 | `public/Set-DbaRgResourcePool.ps1` | ソース | プロパティ設定 |
| Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | ソース | 結果取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラーハンドリング |
