# 機能設計書 38-Get-DbaDbRestoreHistory

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Get-DbaDbRestoreHistory`コマンドレットに関する機能設計書です。このコマンドは、MSDBデータベースからデータベースリストア履歴を取得し、コンプライアンスレポートとリカバリ分析に活用します。

### 本機能の処理概要

Get-DbaDbRestoreHistoryは、MSDBデータベースのrestorehistoryとbackupsetテーブルをクエリし、SQL Serverインスタンスで実行された全てのデータベースリストア操作の詳細情報を取得します。誰がリストアを実行したか、いつ実行されたか、どのタイプのリストアが実行されたか、ソースと宛先のファイルパスなど包括的な情報を返します。

**業務上の目的・背景**：コンプライアンス監査のためのリストア活動追跡、データベース最終リストア日時の確認によるトラブルシューティング、予期しない変更の調査のための最近のリストア操作特定など、リストア履歴情報は重要な監査・分析データです。

**機能の利用シーン**：
- コンプライアンス監査用のリストア履歴レポート作成
- データベースの最終リストア日時確認
- 予期しないデータベース変更の原因調査
- ディザスタリカバリ検証のためのリストア履歴分析

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続
2. restorehistoryとbackupsetテーブルへのJOINクエリ実行
3. リストアタイプ、日時、ソース/宛先ファイル情報の取得
4. フィルタリングとソートによる結果整形

**関連システム・外部連携**：
- msdb.dbo.restorehistory
- msdb.dbo.backupset
- msdb.dbo.backupmediafamily
- msdb.dbo.restorefile

**権限による制御**：msdbへの読み取りアクセス権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 該当する画面マッピングなし |

## 機能種別

データ取得処理 / 監査クエリ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | SQL Serverインスタンス（複数可） | パイプライン入力対応 |
| SqlCredential | PSCredential | No | 接続資格情報 | - |
| Database | object[] | No | 対象データベース | ワイルドカード対応 |
| ExcludeDatabase | object[] | No | 除外データベース | - |
| Since | datetime | No | 指定日時以降のリストア | - |
| Force | switch | No | 非推奨（機能なし） | - |
| Last | switch | No | 各DBの最新リストアのみ | - |
| RestoreType | string | No | リストアタイプフィルタ | Database/File/Filegroup/Differential/Log/Verifyonly/Revert |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- msdb.dbo.restorehistory
- msdb.dbo.backupset
- msdb.dbo.backupmediafamily
- msdb.dbo.restorefile

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホスト名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| Database | string | リストア先データベース名 |
| Username | string | リストア実行ユーザー |
| RestoreType | string | リストアタイプ |
| Date | datetime | リストア実行日時 |
| From | string | ソースファイルパス（カンマ区切り） |
| To | string | 宛先ファイルパス（カンマ区切り） |
| first_lsn | bigint | 最初のLSN |
| last_lsn | bigint | 最後のLSN |
| checkpoint_lsn | bigint | チェックポイントLSN |
| database_backup_lsn | bigint | データベースバックアップLSN |
| BackupFinishDate | datetime | バックアップ完了日時 |

### 出力先

- PowerShellパイプライン（System.Data.DataRow）
- Select-DefaultViewで一部プロパティを非表示

## 処理フロー

### 処理シーケンス

```
1. process ブロック（各SqlInstanceに対して）
   └─ Connect-DbaInstance（MinimumVersion 9）

2. クエリ構築
   ├─ Force: SELECT *（全カラム）
   └─ 通常: 特定カラム選択
       └─ RestoreType変換（D/F/G/I/L/V/R）
       └─ From（FOR XML PATH）: 物理デバイス名一覧
       └─ To（FOR XML PATH）: 宛先ファイル名一覧

3. WHERE句構築
   └─ ExcludeDatabase: NOT IN
   └─ Database: IN
   └─ Since: restore_date >=
   └─ Last: MAX(restore_history_id)
   └─ RestoreType: CASE文によるコード変換

4. クエリ実行
   └─ ExecuteWithResults

5. 結果処理
   └─ Last: データベース別に最新選択
   └─ Select-DefaultView（LSN等を非表示）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[foreach SqlInstance]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function]
    E --> B
    D -->|Yes| F{Force?}
    F -->|Yes| G[SELECT * クエリ]
    F -->|No| H[カラム指定クエリ]
    G --> I[WHERE句構築]
    H --> I
    I --> J[ExecuteWithResults]
    J --> K{Last?}
    K -->|Yes| L[DB別最新選択]
    K -->|No| M[Select-DefaultView]
    L --> M
    M --> B
    B --> N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 最小バージョン | SQL Server 2005以上が必要 | 接続時 |
| BR-02 | RestoreType変換 | D=Database, F=File, G=Filegroup, I=Differential, L=Log, V=Verifyonly, R=Revert | クエリ時 |
| BR-03 | Lastフィルタ | restore_history_idの最大値でDB別に最新取得 | Last指定時 |
| BR-04 | From/To集約 | FOR XML PATHでカンマ区切りリスト生成 | 常時 |

### 計算ロジック

RestoreType変換：
```sql
CASE
    WHEN restore_type = 'D' THEN 'Database'
    WHEN restore_type = 'F' THEN 'File'
    WHEN restore_type = 'G' THEN 'Filegroup'
    WHEN restore_type = 'I' THEN 'Differential'
    WHEN restore_type = 'L' THEN 'Log'
    WHEN restore_type = 'V' THEN 'Verifyonly'
    WHEN restore_type = 'R' THEN 'Revert'
END
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| リストア履歴取得 | msdb.dbo.restorehistory | SELECT | リストア履歴情報 |
| バックアップ情報取得 | msdb.dbo.backupset | SELECT | バックアップセット情報 |
| メディア情報取得 | msdb.dbo.backupmediafamily | SELECT | ソースファイル情報 |
| ファイル情報取得 | msdb.dbo.restorefile | SELECT | 宛先ファイル情報 |

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

#### msdb.dbo.restorehistory

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | destination_database_name, user_name, restore_type, restore_date等 | backup_set_idでbackupsetとJOIN | メインテーブル |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | インスタンス接続失敗 | 接続情報確認 |

### リトライ仕様

リトライ機能は実装されていません。

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

読み取り専用操作のためトランザクションは使用しません。

## パフォーマンス要件

- FOR XML PATHによる文字列集約でパフォーマンス最適化
- 大量履歴の場合はSinceやDatabaseフィルタ推奨

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

- msdbへの読み取り権限が必要
- SqlCredentialで認証情報を安全に渡す

## 備考

- 参照: https://www.mssqltips.com/sqlservertip/1724/when-was-the-last-time-your-sql-server-database-was-restored/
- 参照: https://sqlstudies.com/2016/07/27/when-was-this-database-restored/
- Forceパラメータは非推奨で機能しない

---

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

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

### 推奨読解順序

#### Step 1: パラメータ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbRestoreHistory.ps1 | `public/Get-DbaDbRestoreHistory.ps1` | パラメータ定義（121-134行目）、ValidateSetに注目 |

**読解のコツ**: `RestoreType`のValidateSetで許可される値が定義されている。

#### Step 2: process ブロックのクエリ構築を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbRestoreHistory.ps1 | `public/Get-DbaDbRestoreHistory.ps1` | processブロック（136-255行目）でのクエリ構築と結果処理 |

**主要処理フロー**:
1. **139-143行目**: Connect-DbaInstance（MinimumVersion 9）
2. **148-186行目**: SELECT句構築（Force分岐、RestoreType変換、FOR XML PATH）
3. **188-189行目**: FROM句（restorehistory JOIN backupset）
4. **191-230行目**: WHERE句構築（各フィルタ条件）
5. **241-249行目**: Last処理（DB別最新選択）
6. **250行目**: Select-DefaultView

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

```
Get-DbaDbRestoreHistory
    │
    └─ process ブロック (foreach $instance)
           │
           ├─ Connect-DbaInstance (MinimumVersion 9)
           │
           ├─ クエリ構築
           │      │
           │      ├─ SELECT句
           │      │      ├─ Force: SELECT *
           │      │      └─ 通常: 特定カラム + FOR XML PATH
           │      │
           │      ├─ FROM句
           │      │      └─ restorehistory JOIN backupset
           │      │
           │      └─ WHERE句
           │             ├─ ExcludeDatabase
           │             ├─ Database
           │             ├─ Since
           │             ├─ Last
           │             └─ RestoreType
           │
           ├─ ExecuteWithResults
           │
           └─ 結果処理
                  ├─ Last: Group + Sort + Select -First 1
                  └─ Select-DefaultView (LSN等非表示)
```

### データフロー図

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

$SqlInstance ──────────▶ Connect-DbaInstance ─────────▶ $server
                                 │
$Database ─────────────▶ WHERE句構築 ────────────────▶ $wherearray
$ExcludeDatabase                 │
$Since                           │
$RestoreType                     │
                                 │
$sql ──────────────────▶ ExecuteWithResults ─────────▶ $results
                                 │
$Last ─────────────────▶ Group + Sort ───────────────▶ フィルタ後
                                 │
                         Select-DefaultView
                                 │
                                 └─────────────────────▶ DataRow[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbRestoreHistory.ps1 | `public/Get-DbaDbRestoreHistory.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Select-DefaultView.ps1 | `internal/functions/Select-DefaultView.ps1` | ソース | 出力整形 |
