# 機能設計書 250-Test-DbaMaxDop

## 概要

本ドキュメントは、CPUコア数とNUMAトポロジーに基づく推奨値に対してSQL ServerのMAXDOP構成をテストする機能 `Test-DbaMaxDop` の設計仕様を記載する。

### 本機能の処理概要

この機能は、SQL ServerのMax Degree of Parallelism（MAXDOP）設定を分析し、サーバーのハードウェア構成に基づくMicrosoft推奨値と比較する。CPUコア数、NUMAトポロジー、SQL Serverバージョンを調べて、最適なMAXDOP設定を計算する。

**業務上の目的・背景**：MAXDOPが誤設定されていると、クエリパフォーマンスの低下、過度の並列処理オーバーヘッド、CXPACKETウェイトの原因となる。本機能は、単一/複数NUMA構成を自動検出し、バージョン固有の計算ルールを適用して、最適な設定を推奨する。

**機能の利用シーン**：
- SQL Server初期構成時のMAXDOP設定検証
- パフォーマンスチューニング時の構成監査
- 複数サーバーでの設定標準化
- SQL Server 2016以降のデータベース単位MAXDOP監査

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続（SQL Server 2005以上）
2. NUMAノード数とCPUコア数を取得
3. Microsoft推奨値に基づくMAXDOP計算
4. 現在の設定と推奨値を比較
5. SQL Server 2016以降はデータベース単位のMAXDOPも確認

**関連システム・外部連携**：sys.dm_os_memory_clerks、sys.dm_os_schedulersシステムビュー。

**権限による制御**：sysadminアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 107 | MaxDOP設定 | 補助機能 | MaxDOPのテスト |

## 機能種別

診断処理 / 構成監査処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | ターゲットSQL Serverインスタンス | SQL Server 2005以上 |
| SqlCredential | PSCredential | No | 代替資格情報 | 有効なPowerShell資格情報 |
| EnableException | switch | No | 例外のスロー有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（computer\instance形式） |
| Database | string | データベース名（インスタンスレベルはN/A） |
| DatabaseMaxDop | string/int | データベース単位のMAXDOP設定（インスタンスレベルはN/A） |
| CurrentInstanceMaxDop | int | 現在のインスタンスレベルMAXDOP設定 |
| RecommendedMaxDop | int | Microsoft推奨のMAXDOP値 |
| NumaNodes | int | NUMAノード数 |
| NumberOfCores | int | 論理プロセッサコア数 |
| Notes | string | 構成に関するガイダンスノート |

### 出力先

- PowerShellパイプライン出力（PSCustomObject）
- デフォルト表示ではNumaNodesとNumberOfCoresは除外

## 処理フロー

### 処理シーケンス

```
1. beginブロックでガイダンスメッセージ定義
2. processブロックで各インスタンス処理
   └─ Connect-DbaInstance（MinimumVersion 9）で接続
   └─ 現在のMAXDOP設定取得
   └─ NUMAノード数取得（sys.dm_os_memory_clerks）
   └─ CPUコア数取得（sys.dm_os_schedulers）
   └─ 推奨MAXDOP計算
   └─ インスタンスレベル結果出力
3. SQL Server 2016以降はデータベース単位確認
   └─ 各ユーザーデータベースのMAXDOP取得
   └─ データベース単位結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ガイダンスメッセージ定義]
    B --> C{各インスタンスをループ}
    C --> D[Connect-DbaInstance MinimumVersion 9]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function]
    F --> C
    E -->|Yes| G[現在のMAXDOP取得]
    G --> H[NUMAノード数取得]
    H --> I[CPUコア数取得]
    I --> J{単一NUMA?}
    J -->|Yes| K{コア < 8?}
    K -->|Yes| L[推奨 = コア数]
    K -->|No| M[推奨 = 8]
    J -->|No| N{SQL 2016以降?}
    N -->|Yes| O{コア/NUMA < 16?}
    O -->|Yes| P[推奨 = コア/NUMA]
    O -->|No| Q[推奨 = 16]
    N -->|No| R{コア/NUMA < 8?}
    R -->|Yes| S[推奨 = コア/NUMA]
    R -->|No| T[推奨 = 8]
    L --> U[ノート設定]
    M --> U
    P --> U
    Q --> U
    S --> U
    T --> U
    U --> V[インスタンス結果出力]
    V --> W{SQL 2016以降?}
    W -->|Yes| X{各DBをループ}
    W -->|No| C
    X --> Y{アクセス可能?}
    Y -->|No| X
    Y -->|Yes| Z[DB MAXDOP取得]
    Z --> AA[DB結果出力]
    AA --> X
    X -->|完了| C
    C -->|完了| AB[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-250-1 | 単一NUMAルール | コア < 8 → MAXDOP = コア数、コア >= 8 → MAXDOP = 8 | NumaNodes = 1 |
| BR-250-2 | 複数NUMAルール（SQL 2016以降） | コア/NUMA < 16 → MAXDOP = コア/NUMA、コア/NUMA >= 16 → MAXDOP = 16 | NumaNodes > 1 かつ VersionMajor >= 13 |
| BR-250-3 | 複数NUMAルール（旧バージョン） | コア/NUMA < 8 → MAXDOP = コア/NUMA、コア/NUMA >= 8 → MAXDOP = 8 | NumaNodes > 1 かつ VersionMajor < 13 |
| BR-250-4 | データベースMAXDOP | SQL 2016以降はデータベース単位のMAXDOPを確認 | VersionMajor >= 13 |

### ガイダンスノート

| 状況 | ノート |
|------|--------|
| MAXDOP = 0 | デフォルト設定。推奨値の使用を検討してください。 |
| MAXDOP = 1 | SharePoint、Dynamics NAV、SAP、BizTalkなどのアプリケーションはMAXDOP = 1が必要。変更前に確認してください。 |
| MAXDOP < 推奨値 | 低い値は意図的に設定された可能性があります。変更前に確認してください。 |
| MAXDOP > 推奨値 | 高い値は意図的に設定された可能性があります。変更前に確認してください。 |
| MAXDOP = 推奨値 | 構成は推奨通りです。 |
| DB MAXDOP = 0 | インスタンスレベルのMAXDOP値を使用します。 |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| NUMAノード数取得 | sys.dm_os_memory_clerks | SELECT | メモリノードからNUMAノード数を算出 |
| CPUコア数取得 | sys.dm_os_schedulers | SELECT | 可視オンラインスケジューラ数を取得 |
| MAXDOP取得 | sp_configure | SELECT | インスタンスレベルのMAXDOP設定 |
| DB MAXDOP取得 | $database.MaxDop | SELECT | データベース単位のMAXDOP設定 |

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

#### sys.dm_os_memory_clerks

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | COUNT(DISTINCT memory_node_id) | memory_node_id != 64 | NUMAノード数算出 |

#### sys.dm_os_schedulers

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | COUNT(scheduler_id) | status = 'VISIBLE ONLINE' | CPUコア数算出 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンスへの接続失敗 | Stop-Functionで処理継続 |
| NumaError | クエリエラー | NUMAノード数取得失敗 | Stop-Functionで処理継続 |
| CoreError | クエリエラー | CPUコア数取得失敗 | Stop-Functionで処理継続 |

### リトライ仕様

リトライ処理なし。各インスタンスに対してContinueでループを継続。

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- DMVへの軽量クエリ
- SQL Server 2016以降はデータベース数に応じて処理時間が増加

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

- SQL Server認証、Windows認証、Active Directory認証をサポート
- sysadminアクセス権限が必要
- MFAサポートが必要な場合はConnect-DbaInstanceの事前使用を推奨

## 備考

- Microsoft公式ガイダンス: KB 2806535
- Sakthivel Chidambaram氏のMAXDOP Calculator手法を参考
- SQL Server 2005以上が必要（MinimumVersion 9）

---

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

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

### 推奨読解順序

#### Step 1: コマンド構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaMaxDop.ps1 | `public/Test-DbaMaxDop.ps1` | パラメータ定義、コメントベースヘルプ |

**読解のコツ**: MAXDOP計算ロジックの条件分岐に注目。

#### Step 2: beginブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaMaxDop.ps1 | `public/Test-DbaMaxDop.ps1` | ガイダンスノートの定義 |

**主要処理フロー**:
1. **95-99行目**: 各種ガイダンスノートの定義

#### Step 3: processブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaMaxDop.ps1 | `public/Test-DbaMaxDop.ps1` | MAXDOP計算と結果出力 |

**主要処理フロー**:
1. **107-111行目**: インスタンスへの接続
2. **113-114行目**: 現在のMAXDOP取得
3. **116-122行目**: NUMAノード数取得
4. **124-130行目**: CPUコア数取得
5. **132-163行目**: 推奨MAXDOP計算ロジック
6. **165-183行目**: ノート設定ロジック
7. **185-197行目**: インスタンスレベル結果出力
8. **199-230行目**: データベース単位MAXDOP確認（SQL 2016以降）

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

```
Test-DbaMaxDop
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server SMO接続（MinimumVersion 9）
    │
    ├─ $server.Configuration.MaxDegreeOfParallelism
    │      └─ インスタンスMAXDOP取得
    │
    ├─ $server.ConnectionContext.ExecuteScalar
    │      ├─ sys.dm_os_memory_clerks（NUMA）
    │      └─ sys.dm_os_schedulers（コア）
    │
    ├─ $server.Databases
    │      └─ データベースリスト取得
    │
    └─ Select-DefaultView
           └─ 出力プロパティフィルタリング
```

### データフロー図

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

SqlInstance    ───▶ Connect-DbaInstance ───▶ $server
                           │
                           ├─ MAXDOP取得 ───▶ $maxDop
                           ├─ NUMA取得 ───▶ $NumaNodes
                           └─ コア取得 ───▶ $numberOfCores
                           │
                           ▼
                    推奨MAXDOP計算 ───▶ $recommendedMaxDop
                           │
                           ▼
                    ノート設定 ───▶ $notes
                           │
                           ▼
                    インスタンス結果出力 ───▶ PSCustomObject
                           │
                           ▼
                    DB単位確認（2016以降） ───▶ PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaMaxDop.ps1 | `public/Test-DbaMaxDop.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Set-DbaMaxDop.ps1 | `public/Set-DbaMaxDop.ps1` | ソース | MAXDOP設定変更（関連） |
