# 機能設計書 227-Set-DbaMaxDop

## 概要

本ドキュメントは、SQL Serverの最大並列度（MaxDOP: Maximum Degree of Parallelism）をインスタンスレベルまたはデータベースレベルで設定するdbatools PowerShellコマンドレット「Set-DbaMaxDop」の機能設計書である。

### 本機能の処理概要

Set-DbaMaxDopは、SQL Serverがパラレルクエリ実行時に使用するプロセッサ数の上限を設定するコマンドレットである。明示的な値を指定しない場合は、Test-DbaMaxDopからの推奨値を自動適用する。SQL Server 2016以降では、データベース固有のMaxDOP設定もサポートする。

**業務上の目的・背景**：MaxDOPは、SQL Serverのパフォーマンスに大きな影響を与える重要な設定である。不適切なMaxDOP値は、OLTPワークロードでの過度な並列処理によるオーバーヘッドや、データウェアハウスワークロードでの並列処理不足を引き起こす可能性がある。この機能により、ハードウェア構成に基づいた推奨値の自動適用や、特定の要件に応じたカスタム値の設定が可能になる。

**機能の利用シーン**：
- 新規SQL Serverインスタンスの初期設定
- ハードウェア変更後のMaxDOP再調整
- OLTPとデータウェアハウスの混在環境での最適化
- SQL Server 2016以降でのデータベース別最適化

**主要な処理内容**：
1. Test-DbaMaxDopによる推奨値の取得（未指定時）
2. sysadmin権限の確認
3. バージョンに応じたインスタンス/データベースレベル設定
4. SMOによる設定変更の適用
5. 変更結果の出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を介してSQL Serverと連携する。

**権限による制御**：sysadmin固定サーバーロールが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン | 主画面 | PowerShellコンソールからの直接実行 |

## 機能種別

サーバー/データベース設定変更（UPDATE操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 認証用資格情報 | - |
| Database | object[] | No | データベース別MaxDOP対象DB | SQL Server 2016以降 |
| ExcludeDatabase | object[] | No | 除外データベース | SQL Server 2016以降 |
| MaxDop | int | No | 設定するMaxDOP値 | デフォルト: -1（推奨値使用） |
| InputObject | PSCustomObject | No | Test-DbaMaxDopからの入力 | パイプライン |
| AllDatabases | switch | No | 全データベース対象 | SQL Server 2016以降 |
| EnableException | switch | No | 例外有効化フラグ | - |

### 入力データソース

- PowerShellコマンドライン入力
- Test-DbaMaxDopからのパイプライン入力

## 出力仕様

### 出力データ（インスタンスレベル）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| PreviousInstanceMaxDopValue | int | 変更前のMaxDOP値 |
| CurrentInstanceMaxDop | int | 設定後のMaxDOP値 |

### 出力データ（データベースレベル）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| InstanceName | string | SQL Serverインスタンス名 |
| Database | string | データベース名 |
| PreviousDatabaseMaxDopValue | int | 変更前のMaxDOP値 |
| CurrentDatabaseMaxDopValue | int | 設定後のMaxDOP値 |

### 出力先

PowerShellパイプライン（標準出力）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ Database/AllDatabases/ExcludeDatabaseの排他チェック

2. Test-DbaMaxDop実行（InputObject未指定時）
   └─ 推奨MaxDOP値の取得

3. 各インスタンスに対する処理ループ
   └─ Connect-DbaInstanceで接続
   └─ sysadmin権限確認

4. バージョンチェック
   └─ SQL Server 2016以降: データベースレベル設定可能
   └─ SQL Server 2016未満: インスタンスレベルのみ

5. 対象フィルタリング
   └─ Database/ExcludeDatabase/AllDatabasesに基づく

6. MaxDOP設定
   └─ インスタンス: $server.Configuration.MaxDegreeOfParallelism
   └─ データベース: $server.Databases[].MaxDop

7. 変更の適用
   └─ インスタンス: $server.Configuration.Alter()
   └─ データベース: $server.Databases[].Alter()

8. 結果の出力
   └─ レベルに応じた出力オブジェクト生成
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ検証]
    B --> C{排他パラメータOK?}
    C -->|No| D[エラー終了]
    C -->|Yes| E{InputObject指定?}
    E -->|No| F[Test-DbaMaxDop実行]
    E -->|Yes| G[InputObject使用]
    F --> G
    G --> H[各インスタンスループ]
    H --> I{sysadmin権限?}
    I -->|No| J[スキップ]
    I -->|Yes| K{バージョン >= 2016?}
    K -->|Yes| L{DB指定パラメータ?}
    K -->|No| M{DB指定あり?}
    L -->|Yes| N[データベースレベル設定]
    L -->|No| O[インスタンスレベル設定]
    M -->|Yes| P[警告:非対応]
    M -->|No| O
    N --> Q[DB.Alter実行]
    O --> R[Config.Alter実行]
    Q --> S[結果出力]
    R --> S
    P --> S
    S --> T{次のインスタンス?}
    J --> T
    T -->|Yes| H
    T -->|No| U[終了]
    D --> U
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パラメータ排他 | Database, AllDatabases, ExcludeDatabaseは相互排他 | パラメータ検証時 |
| BR-002 | sysadmin必須 | sysadmin権限がない場合はスキップ | 常時 |
| BR-003 | バージョン制限 | データベースレベルMaxDOPはSQL Server 2016以降のみ | VersionMajor >= 13 |
| BR-004 | 推奨値自動適用 | MaxDop未指定時はTest-DbaMaxDopの推奨値を使用 | MaxDop = -1 |
| BR-005 | 変更不要スキップ | 現在値と推奨値が同じ場合は変更しない | UseRecommended時 |

### 計算ロジック

MaxDop = -1 の場合、Test-DbaMaxDopからの推奨値（RecommendedMaxDop）を使用。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| インスタンスMaxDOP | sys.configurations | UPDATE | sp_configure 'max degree of parallelism' |
| データベースMaxDOP | sys.database_scoped_configurations | UPDATE | ALTER DATABASE SCOPED CONFIGURATION |

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

#### sys.configurations（インスタンスレベル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | value / value_in_use | MaxDOP値 | configuration_id = 1539（max degree of parallelism） |

#### sys.database_scoped_configurations（データベースレベル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | value | MaxDOP値 | name = 'MAXDOP' |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidArgument | 排他パラメータの同時指定 | 1つのみ指定 |
| - | PermissionDenied | sysadmin権限なし | sysadmin権限で再実行 |
| - | VersionNotSupported | SQL Server 2016未満でDB指定 | パラメータを除外 |
| - | AlterFailed | 設定変更失敗 | 権限と設定を確認 |

### リトライ仕様

リトライ処理は実装されていない。エラー発生時はStop-Functionで処理を停止し、-Continueにより次の対象に進む。

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

- インスタンスレベル: Configuration.Alter()で即時コミット
- データベースレベル: 各データベースのAlter()で個別にコミット

## パフォーマンス要件

特に定義されていない。設定変更は軽量な操作である。

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

- sysadmin固定サーバーロールが必要
- データベースレベル設定にはdb_owner権限でも可能な場合がある

## 備考

- インスタンスレベルの変更は即座に有効（RECONFIGURE相当）
- Test-DbaMaxDopと連携して推奨値を適用可能
- WhatIfとConfirmパラメータをサポート

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造とTest-DbaMaxDopからの入力を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaMaxDop.ps1 | `public/Set-DbaMaxDop.ps1` | 出力オブジェクトの構造（66-87行目の.OUTPUTSセクション） |

**読解のコツ**: インスタンスレベルとデータベースレベルで異なる出力形式を持つ点に注目。

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

beginとprocessブロック内のメイン処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaMaxDop.ps1 | `public/Set-DbaMaxDop.ps1` | beginブロック（128-132行目） |
| 2-2 | Set-DbaMaxDop.ps1 | `public/Set-DbaMaxDop.ps1` | processブロック（134-282行目） |

**主要処理フロー**:
1. **129-131行目**: MaxDop = -1でUseRecommendedフラグ設定
2. **135-138行目**: パラメータ排他チェック
3. **147-151行目**: Test-DbaMaxDop呼び出し（InputObject未指定時）
4. **166-168行目**: sysadmin権限チェック
5. **170-197行目**: バージョン別対象フィルタリング

#### Step 3: MaxDOP設定ロジックを理解する

インスタンスレベルとデータベースレベルの設定処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaMaxDop.ps1 | `public/Set-DbaMaxDop.ps1` | 設定処理（199-280行目） |

**主要処理フロー**:
- **227-228行目**: インスタンスレベル設定 - $server.Configuration.MaxDegreeOfParallelism
- **219-224行目**: データベースレベル設定 - $server.Databases[].MaxDop
- **246-252行目**: Alter()実行とShouldProcess

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

```
Set-DbaMaxDop
    │
    ├─ Test-DbaMaxDop (InputObject未指定時)
    │      └─ 推奨MaxDOP値の取得
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server SMO接続
    │
    ├─ Test-SqlSa
    │      └─ sysadmin権限確認
    │
    ├─ インスタンスレベル設定
    │      ├─ $server.Configuration.MaxDegreeOfParallelism.ConfigValue
    │      └─ $server.Configuration.Alter()
    │
    └─ データベースレベル設定 (SQL 2016+)
           ├─ $server.Databases[].MaxDop
           └─ $server.Databases[].Alter()
```

### データフロー図

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

SqlInstance ─────────┐
MaxDop ──────────────┼──▶ Test-DbaMaxDop ──▶ 推奨値取得
Database/AllDatabases┤   (MaxDop=-1の場合)
InputObject ─────────┘         │
                               ▼
                        Connect-DbaInstance
                               │
                               ▼
                        sysadmin権限チェック
                               │
                               ▼
                        バージョンチェック
                               │
                    ┌──────────┴──────────┐
                    ▼                      ▼
            インスタンスレベル      データベースレベル
            (Configuration.Alter)   (Database.Alter)
                    │                      │
                    ▼                      ▼
            PSCustomObject          PSCustomObject
            (Instance形式)          (Database形式)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaMaxDop.ps1 | `public/Set-DbaMaxDop.ps1` | ソース | メインコマンドレット実装 |
| Test-DbaMaxDop.ps1 | `public/Test-DbaMaxDop.ps1` | ソース | MaxDOP推奨値計算（入力元） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
