# 機能設計書 471-Set-DbaResourceGovernor

## 概要

本ドキュメントは、SQL Server Resource Governorのインスタンスレベル設定を構成するPowerShellコマンド「Set-DbaResourceGovernor」の機能設計書である。

### 本機能の処理概要

Set-DbaResourceGovernorは、SQL Serverインスタンス上のResource Governorを構成し、ワークロードのリソース割り当てを制御するための機能である。Resource Governorの有効化/無効化と、分類関数（Classifier Function）の設定を行う。

**業務上の目的・背景**：企業環境において、異なるアプリケーションやユーザーグループが同一のSQL Serverインスタンスを共有する場合、リソース競合が発生する可能性がある。Resource Governorを使用することで、CPU、メモリ、I/Oリソースの割り当てを制御し、重要なワークロードに対するサービスレベルを保証できる。特に、レポート処理やETLジョブがトランザクション処理に影響を与えることを防止するために必要である。

**機能の利用シーン**：
- 本番環境でResource Governorを初めて有効化する場合
- リソース管理ポリシーの変更に伴い、分類関数を更新する場合
- メンテナンス作業のためにResource Governorを一時的に無効化する場合
- 複数インスタンスに対して一括でResource Governor設定を適用する場合

**主要な処理内容**：
1. SQL Serverインスタンスへの接続確立
2. 現在のResource Governor状態（有効/無効）の取得
3. 指定されたパラメータに基づくResource Governorの有効化または無効化
4. 分類関数の設定または削除（NULLを指定した場合）
5. 変更のコミットとResource Governorの再構成
6. 更新後のResource Governor設定情報の出力

**関連システム・外部連携**：masterデータベース内のユーザー定義関数（分類関数）との連携が必要。分類関数はセッションプロパティに基づいてワークロードグループを決定する。

**権限による制御**：CONTROL SERVER権限またはsysadmin固定サーバーロールのメンバーシップが必要。Resource Governorの構成変更はALTER RESOURCE GOVERNOR権限を要する。

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可能 |
| SqlCredential | PSCredential | No | SQL Server接続用の資格情報 | Credentialエイリアスあり |
| Enabled | switch | No | Resource Governorを有効化する | Disabledと排他 |
| Disabled | switch | No | Resource Governorを無効化する | Enabledと排他 |
| ClassifierFunction | string | No | 分類関数の名前。NULLで削除 | masterデータベースに存在する必要あり |
| WhatIf | switch | No | 実行内容のプレビュー | - |
| Confirm | switch | No | 実行前の確認プロンプト | - |
| EnableException | switch | No | 例外をスローするかどうか | - |

### 入力データソース

- パイプライン経由のSqlInstanceパラメータ
- SQL Server接続情報（Windows認証またはSQL認証）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverが稼働するコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Enabled | bool | Resource Governorの有効/無効状態 |
| ClassifierFunction | string | 設定されている分類関数名 |
| RecoveryPriority | string | リカバリ優先度設定 |
| State | string | Resource Governorの状態 |

### 出力先

パイプライン出力（Microsoft.SqlServer.Management.Smo.ResourceGovernor オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証とインスタンス接続
   └─ Connect-DbaInstanceでSQL Server接続を確立
2. 現在のResource Governor状態取得
   └─ $server.ResourceGovernor.Enabledと.ClassifierFunctionを取得
3. 有効化/無効化処理
   └─ Enabledスイッチで$true、Disabledスイッチで$falseを設定
4. 分類関数の設定（指定された場合）
   └─ NULLの場合は関数をクリア、それ以外はGet-DbaDbUdfで関数を検証して設定
5. 変更のコミット
   └─ $server.ResourceGovernor.Alter()で変更を適用
6. 状態の更新
   └─ $server.ResourceGovernor.Refresh()で最新状態を取得
7. 結果出力
   └─ Get-DbaResourceGovernorで更新後の設定を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQL Serverインスタンスに接続]
    B --> C{接続成功?}
    C -->|No| D[エラー処理して次のインスタンスへ]
    C -->|Yes| E[現在のResource Governor状態を取得]
    E --> F{Enabled指定?}
    F -->|Yes| G[ResourceGovernor.Enabled = true]
    F -->|No| H{Disabled指定?}
    H -->|Yes| I[ResourceGovernor.Enabled = false]
    H -->|No| J[状態変更なし]
    G --> K{ClassifierFunction指定?}
    I --> K
    J --> K
    K -->|Yes| L{NULL指定?}
    L -->|Yes| M[ClassifierFunction = NULL]
    L -->|No| N[masterから関数を取得]
    N --> O{関数存在?}
    O -->|Yes| P[ClassifierFunctionを設定]
    O -->|No| Q[エラー: 関数が存在しない]
    K -->|No| R[関数設定なし]
    M --> S[Alter/Refreshを実行]
    P --> S
    R --> S
    S --> T[Get-DbaResourceGovernorで結果出力]
    T --> U[終了]
    Q --> D
    D --> U
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 分類関数存在確認 | 指定された分類関数はmasterデータベースに存在する必要がある | ClassifierFunctionパラメータが指定された場合 |
| BR-002 | NULL指定時の動作 | ClassifierFunctionにNULLを指定すると、既存の分類関数設定が削除される | ClassifierFunction = "NULL" |
| BR-003 | 排他制御 | EnabledとDisabledスイッチは同時に指定できない | パラメータ検証時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 分類関数検証 | master.sys.objects | SELECT | 分類関数の存在確認 |
| Resource Governor構成 | sys.resource_governor_configuration | UPDATE | ALTER RESOURCE GOVERNORにより更新 |

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

#### sys.resource_governor_configuration

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | is_enabled | 0または1 | SMO経由で更新 |
| UPDATE | classifier_function_id | 関数IDまたはNULL | SMO経由で更新 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverに接続できない | Stop-Functionで処理を中断し次のインスタンスへ |
| ObjectNotFound | オブジェクト未検出 | 指定された分類関数が存在しない | エラーメッセージを表示し処理をスキップ |
| AlterError | 変更エラー | Resource Governorの変更に失敗 | Stop-Functionで処理を中断 |

### リトライ仕様

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

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

SMOのAlter()メソッドによる暗黙的なトランザクション管理。個別のトランザクション制御は行われない。

## パフォーマンス要件

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

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

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

## 備考

- SQL Server 2008以降でResource Governorがサポートされている
- 分類関数はサーバー再起動後も永続化される
- Resource Governorの変更はALTER RESOURCE GOVERNOR RECONFIGUREで即座に反映される

---

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

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

### 推奨読解順序

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

SMOのResourceGovernorオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaResourceGovernor.ps1 | `public/Set-DbaResourceGovernor.ps1` | 109-110行目でResourceGovernorオブジェクトのプロパティ取得方法を確認 |

**読解のコツ**: SMOのResourceGovernorオブジェクトは$server.ResourceGovernorでアクセスし、Enabled、ClassifierFunctionプロパティを持つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaResourceGovernor.ps1 | `public/Set-DbaResourceGovernor.ps1` | 91-100行目のパラメータ定義、101行目のprocessブロック開始 |

**主要処理フロー**:
1. **102-107行目**: foreachでインスタンスをループし、Connect-DbaInstanceで接続
2. **109-110行目**: 現在のResource Governor状態を変数に格納
3. **113-129行目**: Enabled/Disabledスイッチによる状態変更
4. **132-145行目**: ClassifierFunctionの設定処理
5. **148-151行目**: Alter()とRefresh()による変更適用
6. **153行目**: Get-DbaResourceGovernorで結果出力

#### Step 3: 分類関数の検証ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaResourceGovernor.ps1 | `public/Set-DbaResourceGovernor.ps1` | 134-143行目の分類関数検証ロジック |

**主要処理フロー**:
- **134行目**: NULL指定の場合はそのまま設定
- **137行目**: Get-DbaDbUdfでmasterデータベースから関数を取得
- **138-141行目**: 関数が存在する場合は設定、存在しない場合はエラー

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

```
Set-DbaResourceGovernor
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ Get-DbaDbUdf（分類関数指定時）
    │      └─ masterデータベースからUDFを取得
    │
    └─ Get-DbaResourceGovernor
           └─ 最終的なResource Governor状態を取得して出力
```

### データフロー図

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

SqlInstance      ───▶ Connect-DbaInstance ───▶ $server
Enabled/Disabled ───▶ ResourceGovernor設定 ───▶ Alter()
ClassifierFunction ──▶ Get-DbaDbUdf検証 ───▶ ClassifierFunction設定
                                              │
                                              ▼
                                       Get-DbaResourceGovernor
                                              │
                                              ▼
                                    [ResourceGovernorオブジェクト]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaResourceGovernor.ps1 | `public/Set-DbaResourceGovernor.ps1` | ソース | メイン処理ロジック |
| Get-DbaResourceGovernor.ps1 | `public/Get-DbaResourceGovernor.ps1` | ソース | 結果出力用コマンド |
| Get-DbaDbUdf.ps1 | `public/Get-DbaDbUdf.ps1` | ソース | 分類関数の検証用コマンド |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続用コマンド |
| Set-DbaResourceGovernor.Tests.ps1 | `tests/Set-DbaResourceGovernor.Tests.ps1` | テスト | 単体テスト |
