# 画面設計書 106-MaxMemory設定

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverの最大メモリ設定管理機能（Get-DbaMaxMemory、Set-DbaMaxMemory、Test-DbaMaxMemory）の設計仕様を記載する。

### 本画面の処理概要

SQL Serverの「Max Server Memory」設定を取得・テスト・変更するためのコマンドラインインターフェースを提供する。メモリ設定はSQL Serverのパフォーマンスとシステム安定性に直接影響するため、適切な値の設定が重要である。

**業務上の目的・背景**：SQL Serverは既定でシステム上のすべての利用可能なメモリを使用しようとするため、OSやその他のアプリケーションにメモリ不足を引き起こす可能性がある。Max Server Memoryの適切な設定により、SQL ServerとOS間のメモリ競合を防止し、システム全体の安定性を確保できる。本機能により、複数インスタンス環境でのメモリ割り当ての監査・最適化が効率化される。

**画面へのアクセス方法**：PowerShellコンソールから `Get-DbaMaxMemory`、`Test-DbaMaxMemory`、または `Set-DbaMaxMemory` コマンドを実行する。

**主要な操作・処理内容**：
1. 現在設定の取得（Get-DbaMaxMemory）：Max Server Memoryと物理メモリの比較
2. 推奨値のテスト（Test-DbaMaxMemory）：Jonathan Kehayias式アルゴリズムによる推奨値計算
3. 設定の変更（Set-DbaMaxMemory）：推奨値または指定値でMax Server Memoryを設定

**画面遷移**：Test-DbaMaxMemoryで推奨値を確認し、Set-DbaMaxMemoryでパイプラインまたは直接指定で設定を適用する流れ。

**権限による表示制御**：Get-DbaMaxMemoryとTest-DbaMaxMemoryは通常の接続権限で実行可能。Set-DbaMaxMemoryはsysadmin権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 408 | Get-DbaMaxMemory | 主機能 | 最大メモリの取得 |
| 416 | Set-DbaMaxMemory | 主機能 | 最大メモリの設定 |
| 417 | Test-DbaMaxMemory | 補助機能 | 最大メモリのテスト |

## 画面種別

コマンドラインインターフェース（取得・テスト・設定）

## URL/ルーティング

PowerShellコマンド実行

## 入出力項目

### Get-DbaMaxMemory パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 必須 | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | 任意 | SQL認証情報 |
| EnableException | Switch | 任意 | 例外を有効にする |

### Test-DbaMaxMemory パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 必須 | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | 任意 | SQL認証情報 |
| Credential | PSCredential | 任意 | Windows認証情報 |
| EnableException | Switch | 任意 | 例外を有効にする |

### Set-DbaMaxMemory パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 任意 | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | 任意 | SQL認証情報 |
| Max | int | 任意 | 明示的なMax Server Memory値（MB） |
| InputObject | PSCustomObject[] | 任意 | Test-DbaMaxMemoryからのパイプ入力 |
| EnableException | Switch | 任意 | 例外を有効にする |

## 表示項目

### Get-DbaMaxMemory 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Total | int | 物理メモリ合計（MB） |
| MaxValue | int | 現在のMax Server Memory設定（MB） |
| Server | SMO Server | SMO Serverオブジェクト |

### Test-DbaMaxMemory 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| InstanceCount | int | 検出されたSQLインスタンス数 |
| Total | int | 物理メモリ合計（MB） |
| MaxValue | int | 現在のMax Server Memory設定（MB） |
| RecommendedValue | int | 推奨Max Server Memory値（MB） |
| Server | SMO Server | SMO Serverオブジェクト |

### Set-DbaMaxMemory 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Total | int | 物理メモリ合計（MB） |
| MaxValue | int | 新しいMax Server Memory設定（MB） |
| PreviousMaxValue | int | 変更前のMax Server Memory設定（MB） |

## イベント仕様

### 1-Get-DbaMaxMemory実行

1. Connect-DbaInstanceで接続
2. $server.PhysicalMemoryで物理メモリ取得
3. 1024の剰余補正（アンダーレポート対応）
4. $server.Configuration.MaxServerMemory.ConfigValueで現在値取得
5. PSCustomObjectとして出力

### 2-Test-DbaMaxMemory実行

1. Get-DbaMaxMemoryで基本情報取得
2. Get-DbaServiceでSQLインスタンス数をカウント
3. SSAS/SSRS/SSIS検出時は警告出力
4. Jonathan Kehayiasアルゴリズムで推奨値計算：
   - 4GB以上：4GB単位で1GB予約、16GB超は8GB単位
   - 4GB未満：物理メモリの50%
5. インスタンス数で除算
6. PSCustomObjectとして出力

### 3-Set-DbaMaxMemory実行

1. InputObject未指定時はTest-DbaMaxMemoryを実行
2. Max未指定時はRecommendedValueを使用（UseRecommended）
3. $server.Configuration.MaxServerMemory.ConfigValueを更新
4. $server.Configuration.Alter()で設定を永続化
5. PreviousMaxValueを含むPSCustomObjectを出力

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaMaxMemory | - | SMO読取 | 設定値の読み取り |
| Test-DbaMaxMemory | - | SMO読取 | 設定値の読み取り |
| Set-DbaMaxMemory | sys.configurations | UPDATE | Max Server Memory設定の更新 |

### テーブル別更新項目詳細

#### sp_configure経由（Set-DbaMaxMemory）

| 操作 | 項目 | 更新値・取得条件 | 備考 |
|-----|-----|-----------------|------|
| UPDATE | max server memory (MB) | 指定値または推奨値 | 即時反映（再起動不要） |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|--------------|----------|
| MSG001 | 警告 | "The memory calculation may be inaccurate as the following SQL components have also been detected: $($otherConsumers.ServiceType -join(','))" | SSAS/SSRS/SSIS検出時 |
| MSG002 | 警告 | "Couldn't get accurate SQL Server instance count on $instance. Defaulting to 1." | インスタンス数取得失敗時 |
| MSG003 | 警告 | "Can't determine instance count from Linux or Mac. Defaulting to 1." | Linux/Mac環境の場合 |
| MSG004 | エラー | "Failed to apply configuration change for $server" | 設定変更失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラー出力し、Continueで次のインスタンスへ |
| サービス情報取得失敗 | 警告出力し、インスタンス数を1として継続 |
| 設定変更失敗 | Stop-Functionでエラー出力し、Continueで次のインスタンスへ |

## 備考

- 設定変更は即時反映（SQL Server再起動不要）
- 推奨値計算はJonathan Kehayiasの公式に基づく（http://bit.ly/sqlmemcalc）
- 複数インスタンス環境では推奨値をインスタンス数で除算
- 物理メモリのアンダーレポート（1MB未満の端数）を補正
- デフォルト値2147483647は「無制限」を意味し、要設定の指標

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaMaxMemory.ps1 | `public/Get-DbaMaxMemory.ps1` | 出力オブジェクトの構造（行94-101）を確認 |
| 1-2 | Test-DbaMaxMemory.ps1 | `public/Test-DbaMaxMemory.ps1` | 出力オブジェクトの構造（行147-156）を確認 |

**読解のコツ**: Get-DbaMaxMemoryの結果がTest-DbaMaxMemoryで使用される関係を理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaMaxMemory.ps1 | `public/Get-DbaMaxMemory.ps1` | param()ブロック（行72-77）でパラメータ定義を確認 |
| 2-2 | Test-DbaMaxMemory.ps1 | `public/Test-DbaMaxMemory.ps1` | param()ブロック（行71-78）でパラメータ定義を確認 |
| 2-3 | Set-DbaMaxMemory.ps1 | `public/Set-DbaMaxMemory.ps1` | param()ブロック（行92-99）でパラメータ定義を確認 |

**主要処理フロー**:
1. **行87**: $server.PhysicalMemoryで物理メモリ取得
2. **行90-92**: 1024の剰余補正
3. **行99**: MaxServerMemory.ConfigValueで現在値取得

#### Step 3: 推奨値計算ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaMaxMemory.ps1 | `public/Test-DbaMaxMemory.ps1` | Jonathan Kehayiasアルゴリズム（行124-145） |

**主要処理フロー**:
- **行89**: Get-DbaMaxMemoryで基本情報取得
- **行96-102**: Get-DbaServiceでSQLインスタンス数カウント
- **行109-111**: SSAS/SSRS/SSIS検出時の警告
- **行124-143**: 推奨値計算（4GB単位でreserve計算）
- **行145**: インスタンス数で除算

#### Step 4: 設定変更ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaMaxMemory.ps1 | `public/Set-DbaMaxMemory.ps1` | 設定変更ロジック（行105-144） |

**主要処理フロー**:
- **行101-103**: Max未指定時はUseRecommended
- **行106-108**: InputObject未指定時はTest-DbaMaxMemory実行
- **行115-127**: RecommendedValueまたはMaxで設定
- **行132**: $server.Configuration.Alter()で永続化

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

```
Get-DbaMaxMemory
    |
    +-- Connect-DbaInstance
    |
    +-- $server.PhysicalMemory
    |      +-- 1024の剰余補正
    |
    +-- $server.Configuration.MaxServerMemory.ConfigValue
    |
    +-- PSCustomObject出力

Test-DbaMaxMemory
    |
    +-- Connect-DbaInstance
    |
    +-- Get-DbaMaxMemory
    |      +-- Total (物理メモリ)
    |      +-- MaxValue (現在値)
    |
    +-- Get-DbaService
    |      +-- InstanceCount (SQLエンジン数)
    |      +-- SSAS/SSRS/SSIS検出
    |
    +-- 推奨値計算（Jonathan Kehayiasアルゴリズム）
    |      +-- 4GB単位でreserve加算
    |      +-- 16GB超は8GB単位
    |      +-- インスタンス数で除算
    |
    +-- PSCustomObject出力

Set-DbaMaxMemory
    |
    +-- (InputObject未指定時)
    |      +-- Test-DbaMaxMemory
    |
    +-- PreviousMaxValue保存
    |
    +-- 設定値決定
    |      +-- UseRecommended -> RecommendedValue
    |      +-- Max指定 -> 指定値
    |
    +-- $server.Configuration.MaxServerMemory.ConfigValue = 値
    |
    +-- $server.Configuration.Alter()
    |
    +-- PSCustomObject出力
```

### データフロー図

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

SqlInstance ──────▶ Connect-DbaInstance ──────▶ SMO Server Object
                           |
                           v
                    $server.PhysicalMemory
                           |
                           v
                    アンダーレポート補正
                           |
                           v
                    MaxServerMemory.ConfigValue
                           |
                           v
                    PSCustomObject ──────▶ Total, MaxValue

                    (Test-DbaMaxMemory)
                           |
                           v
                    Get-DbaService
                           |
                           v
                    InstanceCount取得
                           |
                           v
                    推奨値計算 ──────▶ RecommendedValue

                    (Set-DbaMaxMemory)
                           |
                           v
                    Configuration.Alter() ──────▶ MaxValue, PreviousMaxValue
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaMaxMemory.ps1 | `public/Get-DbaMaxMemory.ps1` | ソース | 最大メモリ取得 |
| Set-DbaMaxMemory.ps1 | `public/Set-DbaMaxMemory.ps1` | ソース | 最大メモリ設定 |
| Test-DbaMaxMemory.ps1 | `public/Test-DbaMaxMemory.ps1` | ソース | 最大メモリテスト |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | SQLサービス情報取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
