# 画面設計書 63-リストア履歴

## 概要

本ドキュメントは、dbatools PowerShell モジュールにおけるデータベースリストア履歴の取得機能の設計仕様を定義する。MSDB データベースから過去のリストア操作履歴を取得し、コンプライアンス報告やリカバリ分析に使用する。

### 本画面の処理概要

本機能は、SQL Server の MSDB データベース内の restorehistory および backupset テーブルをクエリし、データベースリストア操作の詳細な履歴情報を取得する。リストアを実行したユーザー、実行日時、リストアタイプ、ソースとターゲットのファイルパスなどの情報を包括的に提供する。

**業務上の目的・背景**：DBA はコンプライアンス監査のためにリストア活動を追跡したり、データベースの問題をトラブルシューティングする際に最後のリストア時期を特定したり、予期しない変更を調査するために最近のリストア操作を特定する必要がある。本機能は、MSDB システムテーブルを手動でクエリしたり、複雑な SQL JOIN を記述する必要性を排除し、複数インスタンスにわたるリストア履歴情報を効率的に収集できる。

**画面へのアクセス方法**：PowerShell コンソールから `Get-DbaDbRestoreHistory` コマンドを直接呼び出す。パイプラインで SqlInstance を渡すことも可能。

**主要な操作・処理内容**：
1. `Get-DbaDbRestoreHistory` - 指定インスタンスのリストア履歴を取得
2. Database パラメータで特定データベースにフィルタリング
3. Since パラメータで特定日時以降のリストアのみ取得
4. Last パラメータで各データベースの最新リストアのみ取得
5. RestoreType パラメータでリストアタイプ（Database, Log, Differential 等）でフィルタリング

**画面遷移**：
- Get-DbaRegServer → Get-DbaDbRestoreHistory のパイプライン連携で Central Management Server 登録サーバー全体の履歴取得
- Get-DbaDbRestoreHistory → Format-Table で表形式出力

**権限による表示制御**：sysadmin 権限が必要。SQL Server 2005 以上が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Get-DbaDbRestoreHistory | 主機能 | リストア履歴の取得 |
| - | Remove-DbaDbBackupRestoreHistory | 補助機能 | バックアップ・リストア履歴の削除 |

## 画面種別

CLI（コマンドラインインターフェース）/ 一覧出力

## URL/ルーティング

PowerShell コマンドレットとして呼び出し。URL は存在しない。

```powershell
Get-DbaDbRestoreHistory -SqlInstance <インスタンス名>
Get-DbaDbRestoreHistory -SqlInstance <インスタンス名> -Database <DB名> -Since '2024-01-01'
```

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| 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 | 例外処理を有効化 |

## 表示項目

### Get-DbaDbRestoreHistory 出力（デフォルト表示）

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | サーバーコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | リストア先データベース名 |
| Username | string | リストア実行ユーザー |
| RestoreType | string | リストアタイプ（Database/File/Filegroup/Differential/Log/Verifyonly/Revert） |
| Date | datetime | リストア完了日時 |
| From | string | バックアップソース物理デバイス名（カンマ区切り） |
| To | string | リストア先物理ファイルパス（カンマ区切り） |

### 追加プロパティ（Select-Object * で表示）

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| first_lsn | decimal | バックアップの最初の LSN |
| last_lsn | decimal | バックアップの最後の LSN |
| checkpoint_lsn | decimal | チェックポイント LSN |
| database_backup_lsn | decimal | データベースバックアップの LSN |
| BackupFinishDate | datetime | バックアップ完了日時 |

## イベント仕様

### 1-Get-DbaDbRestoreHistory 実行

1. SqlInstance に Connect-DbaInstance で接続（MinimumVersion 9）
2. SELECT クエリを構築
3. restorehistory と backupset テーブルを JOIN
4. WHERE 句を動的構築（Database, ExcludeDatabase, Since, Last, RestoreType）
5. ExecuteWithResults でクエリ実行
6. Last 指定時は Group-Object + Sort-Object で最新のみ抽出
7. Select-DefaultView で表示列を制限して出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaDbRestoreHistory | msdb.dbo.restorehistory, msdb.dbo.backupset, msdb.dbo.backupmediafamily, msdb.dbo.restorefile | SELECT | リストア履歴情報読み取り |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| - | エラー | "Failure" | 接続エラー |

## 例外処理

| 例外条件 | ハンドリング | ユーザーへのフィードバック |
|---------|-------------|-------------------------|
| 接続エラー | Stop-Function -Continue | "Failure" と ConnectionError カテゴリ |
| SQL Server 2000 | Connect-DbaInstance で MinimumVersion エラー | バージョンエラー |

## 備考

- SQL Server 2005 以上が必要（MinimumVersion 9）
- Force パラメータは非推奨
- RestoreType の内部コード: D=Database, F=File, G=Filegroup, I=Differential, L=Log, V=Verifyonly, R=Revert

---

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

### 推奨読解順序

#### Step 1: クエリ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbRestoreHistory.ps1 | `public/Get-DbaDbRestoreHistory.ps1` | 行 153-185: SELECT 句の構造と列定義 |

**主要処理フロー**:
- **行 160-169**: RestoreType の CASE 変換（D→Database 等）
- **行 171-178**: FOR XML PATH による From/To のカンマ区切り集約

#### Step 2: フィルタリングロジック

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbRestoreHistory.ps1 | `public/Get-DbaDbRestoreHistory.ps1` | 行 191-230: WHERE 句の動的構築 |

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

```
Get-DbaDbRestoreHistory
    |
    +-- Connect-DbaInstance (MinimumVersion 9)
    |
    +-- SQL クエリ構築
    |       |
    |       +-- SELECT 句
    |       +-- FROM msdb.dbo.restorehistory JOIN backupset
    |       +-- WHERE 句（動的）
    |
    +-- ExecuteWithResults
    |
    +-- (Last 時) Group-Object → Sort-Object
    |
    +-- Select-DefaultView
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbRestoreHistory.ps1 | `public/Get-DbaDbRestoreHistory.ps1` | ソース | リストア履歴取得 |
