# 機能設計書 416-Set-DbaMaxMemory

## 概要

本ドキュメントは、計算された推奨値または明示的な値を使用してSQL Serverの「Max Server Memory」設定を構成する`Set-DbaMaxMemory`機能の設計を定義する。

### 本機能の処理概要

本機能は、SQL Serverがシステムで使用可能なすべてのメモリを消費することを防ぐために「Max Server Memory」構成を変更する。この設定は、SQL Serverがバッファプールおよびその他のメモリコンシューマーに割り当てることができるメモリ量を制御し、オペレーティングシステムやその他のアプリケーションに十分なメモリを残す。

**業務上の目的・背景**：SQL Serverのデフォルト設定ではMax Server Memoryは2147483647 MBという事実上の無制限値に設定されている。これはSQL Serverが利用可能なすべてのメモリを消費し、OSやその他のアプリケーションにメモリ圧迫を引き起こす可能性がある。Jonathan Kehayias氏の計算式に基づいた推奨値を使用することで、適切なメモリ設定を行うことができる。

**機能の利用シーン**：
- 新規SQL Serverインスタンスの初期設定
- メモリ設定の標準化
- 仮想マシンのメモリ変更後の再設定
- 複数インスタンス環境のメモリ配分調整

**主要な処理内容**：
1. Test-DbaMaxMemoryを使用して現在のメモリ設定と推奨値を取得
2. 明示的なMax値または推奨値を使用して設定を更新
3. SMO経由でConfiguration.MaxServerMemory.ConfigValueを変更
4. Configuration.Alter()で設定を適用

**関連システム・外部連携**：
- Test-DbaMaxMemory（推奨値計算）
- SQL Server sp_configure（Max Server Memory設定）

**権限による制御**：sysadmin権限またはALTER SETTINGS権限が必要

## 関連画面

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

## 機能種別

設定変更処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証資格情報 | Windows/SQL認証対応 |
| Max | int | No | 明示的な最大メモリ値（MB） | 0の場合は推奨値を使用 |
| InputObject | PSCustomObject[] | No | Test-DbaMaxMemoryからのパイプライン入力 | ValueFromPipeline |
| EnableException | switch | No | 例外の詳細表示有効化 | - |

### 入力データソース

- パラメータ入力: SqlInstance、Max
- パイプライン入力: Test-DbaMaxMemoryの出力オブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Total | int | サーバーの合計メモリ（MB） |
| MaxValue | int | 新しいMax Server Memory設定（MB） |
| PreviousMaxValue | int | 変更前のMax Server Memory設定（MB） |

### 出力先

PowerShellパイプライン(PSCustomObject)

## 処理フロー

### 処理シーケンス

```
1. beginブロック: 使用モード判定
   └─ Max=0の場合は$UseRecommended=$true

2. processブロック: 設定変更処理
   └─ 2.1 SqlInstance指定時はTest-DbaMaxMemoryを実行してInputObjectに追加
   └─ 2.2 各結果オブジェクトをループ
   └─ 2.3 PreviousMaxValueプロパティを追加
   └─ 2.4 UseRecommended時は推奨値、それ以外はMax値を設定
   └─ 2.5 ShouldProcessで確認後、Configuration.Alter()で適用
   └─ 2.6 結果を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Max=0?}
    B -->|Yes| C[UseRecommended=true]
    B -->|No| D[UseRecommended=false]
    C --> E{SqlInstance指定?}
    D --> E
    E -->|Yes| F[Test-DbaMaxMemory実行]
    F --> G[InputObjectに追加]
    E -->|No| G
    G --> H{各InputObjectをループ}
    H --> I[PreviousMaxValue追加]
    I --> J{UseRecommended?}
    J -->|Yes| K[推奨値を設定]
    J -->|No| L[Max値を設定]
    K --> M[ConfigValue更新]
    L --> M
    M --> N{ShouldProcess確認}
    N -->|No| O[スキップ]
    N -->|Yes| P[Configuration.Alter]
    P --> Q{成功?}
    Q -->|No| R[Stop-Function/Continue]
    Q -->|Yes| S[MaxValue更新]
    S --> T[Select-DefaultView出力]
    T --> H
    H -->|完了| U[終了]
    R --> H
    O --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 推奨値使用 | Max=0または未指定時はTest-DbaMaxMemoryの推奨値を使用 | Max未指定時 |
| BR-002 | 明示値優先 | Max値指定時は推奨値を無視して明示値を使用 | Max指定時 |
| BR-003 | 確認プロンプト | ConfirmImpactがMediumのためShouldProcessで確認 | 常時 |
| BR-004 | 変更前値保存 | PreviousMaxValueに変更前の値を保存 | 常時 |

### 計算ロジック

推奨値の計算はTest-DbaMaxMemory内で実行される（Jonathan Kehayias氏の計算式）。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| メモリ設定変更 | sp_configure | UPDATE | Max Server Memory設定の更新 |

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

#### sp_configure (Max Server Memory)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | max server memory | 推奨値またはMax値 | SMO経由で更新 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConfigError | 設定適用エラー | Configuration.Alter()失敗 | Stop-FunctionでContinue |
| ModifyError | 変更エラー | ConfigValue設定失敗 | Stop-FunctionでContinue |

### リトライ仕様

リトライ処理なし（単一試行）

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

sp_configureの変更は即時反映（RECONFIGURE WITH OVERRIDE不要 - SMOが自動処理）

## パフォーマンス要件

- 設定変更は即時完了
- 複数インスタンスへの一括適用時は順次処理

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

- sysadmin権限またはALTER SETTINGS権限が必要
- SQL認証/Windows認証/Azure AD認証に対応
- 資格情報はPSCredentialで安全に渡される
- ShouldProcessで変更前に確認

## 備考

- Jonathan Kehayias氏の記事: http://bit.ly/sqlmemcalc
- Chrissy LeMaire氏(@cl)による開発
- Test-DbaMaxMemoryと連携して動作

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaMaxMemory.ps1 | `public/Set-DbaMaxMemory.ps1` | 出力オブジェクトの構造（139行目） |
| 1-2 | Test-DbaMaxMemory.ps1 | `public/Test-DbaMaxMemory.ps1` | InputObjectの構造（147-156行目） |

**読解のコツ**: InputObjectはTest-DbaMaxMemoryの出力オブジェクトで、Serverプロパティに接続済みSMOオブジェクトを含む

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaMaxMemory.ps1 | `public/Set-DbaMaxMemory.ps1` | パラメータ定義（91-99行目） |

**主要処理フロー**:
1. **91行目**: SupportsShouldProcess, ConfirmImpact='Medium'
2. **93行目**: SqlInstanceパラメータ（オプション）
3. **95行目**: Maxパラメータ（明示値）
4. **96-97行目**: InputObjectパラメータ（パイプライン入力）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaMaxMemory.ps1 | `public/Set-DbaMaxMemory.ps1` | beginブロック（100-104行目） |
| 3-2 | Set-DbaMaxMemory.ps1 | `public/Set-DbaMaxMemory.ps1` | processブロック（105-145行目） |

**主要処理フロー**:
- **101-103行目**: Max=0の場合UseRecommended=true
- **106-108行目**: SqlInstance指定時はTest-DbaMaxMemory実行
- **110-112行目**: foreach ($result in $InputObject)ループ開始
- **112行目**: PreviousMaxValue追加
- **115-128行目**: UseRecommendedに応じた設定値決定
- **130行目**: ShouldProcess確認
- **131-136行目**: Configuration.Alter()実行
- **138行目**: MaxValue更新
- **139行目**: Select-DefaultView出力

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

```
Set-DbaMaxMemory
    │
    ├─ beginブロック
    │      └─ UseRecommended判定
    │
    ├─ Test-DbaMaxMemory（SqlInstance指定時）
    │      ├─ Connect-DbaInstance
    │      ├─ Get-DbaMaxMemory
    │      ├─ Get-DbaService
    │      └─ 推奨値計算
    │
    ├─ Configuration設定
    │      ├─ MaxServerMemory.ConfigValue
    │      └─ Configuration.Alter()
    │
    └─ Select-DefaultView
           └─ 出力プロパティの選択
```

### データフロー図

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

SqlInstance ──────▶ Test-DbaMaxMemory ──────┐
                          │                 │
Max ──────────────▶ UseRecommended判定       │
                          │                 │
InputObject ─────────────────────────────────┤
(パイプライン)                               │
                                             ▼
                          ┌─────────────────────────────┐
                          │ foreach ($result in $Input) │
                          │                             │
                          │ PreviousMaxValue追加        │
                          │         ↓                   │
                          │ ConfigValue設定             │
                          │         ↓                   │
                          │ ShouldProcess確認           │
                          │         ↓                   │
                          │ Configuration.Alter()       │
                          └─────────────────────────────┘
                                             │
                                             ▼
                          Select-DefaultView ──────▶ パイプライン出力
                          (ComputerName, InstanceName,
                           SqlInstance, Total,
                           MaxValue, PreviousMaxValue)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaMaxMemory.ps1 | `public/Set-DbaMaxMemory.ps1` | ソース | メイン関数実装 |
| Test-DbaMaxMemory.ps1 | `public/Test-DbaMaxMemory.ps1` | ソース | 推奨値計算 |
| Get-DbaMaxMemory.ps1 | `public/Get-DbaMaxMemory.ps1` | ソース | 現在値取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
