# 機能設計書 118-Get-DbaDump

## 概要

本ドキュメントは、SQL Serverのメモリダンプファイル情報を取得するための機能設計書である。sys.dm_server_memory_dumps DMVを使用して、クラッシュダンプの詳細情報を取得する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverがクラッシュ、アサーション失敗、またはその他の重大なエラーに遭遇した場合、メモリダンプファイル（.mdmp）が生成される。これらのダンプファイルは、Microsoft Supportとの連携やサーバー安定性問題の調査において重要である。本機能は、ダンプファイルの生成日時、サイズ、ファイルパスを迅速に確認し、トラブルシューティングを支援する。

**機能の利用シーン**：
- SQL Server安定性問題の調査
- Microsoft Supportへの問い合わせ準備
- ダンプファイルのクリーンアップ計画
- 定期的なサーバーヘルスチェック
- クラッシュ履歴の監査

**主要な処理内容**：
1. 対象SQL Serverインスタンスへ接続（SQL Server 2008 R2以降が必要）
2. sys.dm_server_memory_dumps DMVからダンプファイル情報を取得
3. ファイル名、作成日時、サイズをPSCustomObjectとして返却

**関連システム・外部連携**：sys.dm_server_memory_dumps DMVを使用。

**権限による制御**：VIEW SERVER STATE権限が必要（DMVアクセスのため）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | PowerShellコマンドラインインターフェースのみ |

## 機能種別

データ参照 / 診断情報取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス（パイプライン可） | 接続可能なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なWindows/SQL認証資格情報 |
| EnableException | switch | No | 例外を発生させるかどうか | - |

### 入力データソース

- SqlInstanceパラメータ: ユーザー入力またはパイプライン（必須）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverサービス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（DomainInstanceName） |
| FileName | string | メモリダンプファイルのパスとファイル名（.mdmp） |
| CreationTime | datetime | メモリダンプの作成日時 |
| Size | dbasize | メモリダンプファイルのサイズ（人間可読形式） |

### 出力先

- PowerShellパイプライン（標準出力）
- PSCustomObject として返却

## 処理フロー

### 処理シーケンス

```
1. beginブロック: SQLクエリの定義
   └─ SELECT filename, creation_time, size_in_bytes FROM sys.dm_server_memory_dumps
2. processブロック開始
   └─ 各SqlInstanceについてループ処理
      ├─ 2.1 Connect-DbaInstance で接続
      ├─ 2.2 バージョンチェック（SQL 2008 R2以上）
      ├─ 2.3 DMVクエリ実行
      └─ 2.4 各結果をPSCustomObjectとして出力
3. エラー処理
   └─ 接続失敗/クエリエラー時は Stop-Function で次のインスタンスへ
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ定義]
    B --> C{SqlInstanceをループ}
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function]
    F --> C
    E -->|Yes| G{SQL 2008 R2以上?}
    G -->|No| H[Stop-Function: バージョンエラー]
    H --> C
    G -->|Yes| I[DMVクエリ実行]
    I --> J{クエリ成功?}
    J -->|No| K[Stop-Function]
    K --> C
    J -->|Yes| L{結果をループ}
    L --> M[PSCustomObject出力]
    M --> L
    L --> C
    C --> N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小バージョン | SQL Server 2008 R2 (v10.50) 以降が必要 | 常時 |
| BR-002 | サイズ変換 | size_in_bytesをdbasize型に変換 | 常時 |

### 計算ロジック

- **Size**: size_in_bytes を [dbasize] にキャストして人間可読形式に変換

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ダンプ情報取得 | sys.dm_server_memory_dumps | SELECT | メモリダンプ情報を取得 |

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

#### sys.dm_server_memory_dumps

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | filename | 全件 | ダンプファイルパス |
| SELECT | creation_time | 全件 | 作成日時 |
| SELECT | size_in_bytes | 全件 | ファイルサイズ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | Stop-Function でエラー出力、次のインスタンスへ |
| - | VersionError | SQL Server 2008 R2未満 | Stop-Function でスキップ |
| - | QueryError | DMVクエリ実行失敗 | Stop-Function でエラー出力、次のインスタンスへ |

### リトライ仕様

リトライ処理は実装されていない。接続エラー時は当該インスタンスをスキップして次を処理。

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

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

## パフォーマンス要件

- sys.dm_server_memory_dumps は小さなDMVであり高速
- ダンプファイル数は通常少数のため、結果セットも小さい

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

- VIEW SERVER STATE権限が必要
- ダンプファイルパスからサーバー構成が推測可能
- ダンプファイル自体には機密データが含まれる可能性（本機能では読み取らない）

## 備考

- sys.dm_server_memory_dumps DMV は SQL Server 2008 R2 で導入
- ダンプファイルの実際の解析には別途ツール（Debug Diagnostic Tool等）が必要
- ダンプファイルは通常、SQL Serverエラーログディレクトリに保存される

---

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

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

### 推奨読解順序

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

本機能ではシンプルなPSCustomObjectを出力する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDump.ps1 | `public/Get-DbaDump.ps1` | 出力プロパティ（84-91行目） |

**読解のコツ**: dbasize型によりSizeプロパティは人間可読形式で表示される。

#### Step 2: バージョンチェックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDump.ps1 | `public/Get-DbaDump.ps1` | バージョン判定（78-79行目） |

**主要処理フロー**:
- **78行目**: `$server.versionMajor -lt 11 -and (-not ($server.versionMajor -eq 10 -and $server.versionMinor -eq 50))`
- SQL Server 2012 (v11) 未満 かつ SQL Server 2008 R2 (v10.50) でない場合にエラー

#### Step 3: クエリと結果処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDump.ps1 | `public/Get-DbaDump.ps1` | beginブロック（67行目）とprocessブロック（82-92行目） |

**主要処理フロー**:
- **67行目**: SQLクエリ定義
- **83行目**: $server.Query($sql) でクエリ実行
- **90行目**: [dbasize]$result.size_in_bytes でサイズ変換

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

```
Get-DbaDump
    │
    ├─ beginブロック
    │      └─ $sql クエリ定義
    │
    └─ processブロック
           │
           ├─ Connect-DbaInstance
           │
           ├─ バージョンチェック (v10.50以上)
           │
           └─ $server.Query($sql)
                  │
                  └─ sys.dm_server_memory_dumps
                         │
                         └─ PSCustomObject 構築
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───▶ $server
                            │
                            ▼
                     バージョンチェック
                     (SQL 2008 R2以上?)
                            │
                            ▼
                     $server.Query()
                            │
                            ▼
                     sys.dm_server_memory_dumps
                            │
                            ▼
                     foreach ($result in $results)
                            │
                            ▼
                     [dbasize] サイズ変換
                            │
                            ▼
                     PSCustomObject ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDump.ps1 | `public/Get-DbaDump.ps1` | ソース | メイン関数の実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続機能 |
| dbasize.ps1 | `private/classes/dbasize.ps1` | ソース | dbasize型の定義 |
