# 画面設計書 22-バックアップ履歴

## 概要

本ドキュメントは、dbatoolsモジュールの「バックアップ履歴」機能群に関する画面設計書です。SQL ServerのMSDBデータベースに保存されたバックアップ履歴情報を取得し、コンプライアンス監査、障害復旧計画、バックアップ戦略の分析に活用するためのコマンド群を提供します。

### 本画面の処理概要

**業務上の目的・背景**：
データベース管理者（DBA）は、バックアップポリシーの遵守状況を監視し、障害発生時の復旧計画を策定する必要があります。MSDBのバックアップテーブルを直接クエリすることは煩雑であり、ストライプバックアップの集約やLSNチェーンの理解が必要です。本機能群は、バックアップ履歴の取得を簡素化し、最新のバックアップ状況を迅速に把握できるようにします。また、可用性グループ環境では各レプリカのMSDBにバックアップ履歴が分散するため、統合的な履歴取得機能も提供します。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドレットを直接呼び出します：
- `Get-DbaDbBackupHistory` - データベースバックアップ履歴の取得
- `Get-DbaLastBackup` - 最終バックアップ日時の取得
- `Get-DbaAgBackupHistory` - 可用性グループバックアップ履歴の取得

**主要な操作・処理内容**：
1. MSDBバックアップテーブルからバックアップ履歴情報を取得（Get-DbaDbBackupHistory）
2. 各データベースの最終バックアップ状況を要約表示（Get-DbaLastBackup）
3. 可用性グループ全レプリカのバックアップ履歴を集約（Get-DbaAgBackupHistory）

**画面遷移**：
- 入力: SQLインスタンス接続、データベース名、日付範囲等のフィルタ条件
- 出力: BackupHistoryオブジェクト（Restore-DbaDatabase、Select-DbaBackupInformation等へパイプライン入力可能）

**権限による表示制御**：
- SQL Serverインスタンスへの接続権限が必要
- MSDBデータベースへの読み取り権限が必要
- 可用性グループの場合、各レプリカへの接続権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 37 | Get-DbaDbBackupHistory | 主機能 | データベースバックアップ履歴の取得 |
| 39 | Get-DbaLastBackup | 補助機能 | 最終バックアップ日時の取得 |
| 34 | Get-DbaAgBackupHistory | 補助機能 | 可用性グループバックアップ履歴の取得 |

## 画面種別

コマンドラインインターフェース（CLI）- パイプライン処理対応

## URL/ルーティング

PowerShellコマンドレット形式:
- `Get-DbaDbBackupHistory`
- `Get-DbaLastBackup`
- `Get-DbaAgBackupHistory`

## 入出力項目

### Get-DbaDbBackupHistory

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | No | 対象データベース名 |
| ExcludeDatabase | object[] | No | 除外データベース名 |
| IncludeCopyOnly | Switch | No | コピーオンリーバックアップを含める |
| Force | Switch | No | 全カラムを返す |
| Since | psobject | No | 指定日時以降のバックアップのみ |
| RecoveryFork | string | No | 特定のリカバリフォークGUID |
| Last | Switch | No | 最新の完全バックアップチェーンを返す |
| LastFull | Switch | No | 最新のフルバックアップのみ |
| LastDiff | Switch | No | 最新の差分バックアップのみ |
| LastLog | Switch | No | 最新のログバックアップのみ |
| DeviceType | string[] | No | デバイスタイプでフィルタ |
| Raw | Switch | No | ストライプバックアップを個別に返す |
| Type | string[] | No | バックアップタイプでフィルタ |
| LastLsn | bigint | No | 指定LSN以降のバックアップのみ |
| IncludeMirror | Switch | No | ミラーバックアップを含める |
| IgnoreDiffBackup | Switch | No | 差分バックアップを除外 |
| LsnSort | string | No | LSNソートカラム指定 |

### Get-DbaLastBackup

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | No | 対象データベース名 |
| ExcludeDatabase | object[] | No | 除外データベース名 |

### Get-DbaAgBackupHistory

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQLインスタンスまたはリスナー |
| SqlCredential | PSCredential | No | 代替認証情報 |
| AvailabilityGroup | string | Yes | 可用性グループ名 |
| Database | string[] | No | 対象データベース名 |
| ExcludeDatabase | string[] | No | 除外データベース名 |
| IncludeCopyOnly | Switch | No | コピーオンリーバックアップを含める |
| Force | Switch | No | 全カラムを返す |
| Since | DateTime | No | 指定日時以降のバックアップのみ |
| RecoveryFork | string | No | 特定のリカバリフォークGUID |
| Last | Switch | No | 最新の完全バックアップチェーンを返す |
| LastFull | Switch | No | 最新のフルバックアップのみ |
| LastDiff | Switch | No | 最新の差分バックアップのみ |
| LastLog | Switch | No | 最新のログバックアップのみ |
| DeviceType | string[] | No | デバイスタイプでフィルタ |
| Raw | Switch | No | ストライプバックアップを個別に返す |
| Type | string[] | No | バックアップタイプでフィルタ |
| LastLsn | bigint | No | 指定LSN以降のバックアップのみ |
| IncludeMirror | Switch | No | ミラーバックアップを含める |
| LsnSort | string | No | LSNソートカラム指定 |

## 表示項目

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| AvailabilityGroupName | string | 可用性グループ名（該当する場合） |
| Database | string | データベース名 |
| DatabaseId | int | データベースID |
| UserName | string | バックアップ実行ユーザー |
| Start | DateTime | バックアップ開始時刻 |
| End | DateTime | バックアップ終了時刻 |
| Duration | TimeSpan | バックアップ所要時間 |
| Path | string[] | バックアップファイルパス |
| TotalSize | long | バックアップの合計サイズ（バイト） |
| CompressedBackupSize | long | 圧縮後のサイズ（バイト） |
| CompressionRatio | double | 圧縮率 |
| Type | string | バックアップ種別 |
| BackupSetId | int | バックアップセットID |
| DeviceType | string | デバイスタイプ |
| Software | string | バックアップソフトウェア名 |
| FullName | string[] | バックアップファイルのフルパス |
| FileList | object[] | ファイル詳細 |
| Position | int | メディアセット内の位置 |
| FirstLsn | string | 最初のLSN |
| DatabaseBackupLsn | string | データベースバックアップLSN |
| CheckpointLsn | string | チェックポイントLSN |
| LastLsn | string | 最後のLSN |
| SoftwareVersionMajor | int | SQL Serverメジャーバージョン |
| IsCopyOnly | bool | コピーオンリーバックアップかどうか |
| LastRecoveryForkGuid | Guid | リカバリフォークGUID |
| RecoveryModel | string | リカバリモデル |
| EncryptorThumbprint | string | 暗号化証明書のサムプリント |
| EncryptorType | string | 暗号化タイプ |
| KeyAlgorithm | string | キーアルゴリズム |

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| Database | string | データベース名 |
| RecoveryModel | string | リカバリモデル |
| LastFullBackup | DbaDateTime | 最終フルバックアップ日時 |
| LastDiffBackup | DbaDateTime | 最終差分バックアップ日時 |
| LastLogBackup | DbaDateTime | 最終ログバックアップ日時 |
| SinceFull | DbaTimeSpan | フルバックアップからの経過時間 |
| SinceDiff | DbaTimeSpan | 差分バックアップからの経過時間 |
| SinceLog | DbaTimeSpan | ログバックアップからの経過時間 |
| LastFullBackupIsCopyOnly | bool | 最終フルがコピーオンリーか |
| LastDiffBackupIsCopyOnly | bool | 最終差分がコピーオンリーか |
| LastLogBackupIsCopyOnly | bool | 最終ログがコピーオンリーか |
| DatabaseCreated | DateTime | データベース作成日時 |
| DaysSinceDbCreated | int | データベース作成からの日数 |
| Status | string | バックアップ状況ステータス |

## イベント仕様

### 1-バックアップ履歴取得（Get-DbaDbBackupHistory）

1. SQLインスタンスへの接続
2. バージョンに応じたクエリ構築（SQL 2014+で暗号化情報追加）
3. MSDBバックアップテーブルへのクエリ実行
4. バックアップセットIDでグループ化
5. ストライプバックアップの集約（Raw未指定時）
6. FileList情報の取得
7. BackupHistoryオブジェクト生成

### 2-最終バックアップ取得（Get-DbaLastBackup）

1. SQLインスタンスへの接続
2. データベース一覧の取得（tempdb除外）
3. 各バックアップタイプの最終履歴を取得:
   - Get-DbaDbBackupHistory -LastFull
   - Get-DbaDbBackupHistory -LastDiff
   - Get-DbaDbBackupHistory -LastLog
4. 経過時間の計算
5. ステータス判定（OK/警告）

### 3-AGバックアップ履歴取得（Get-DbaAgBackupHistory）

1. SQLインスタンスへの接続
2. 可用性グループの確認
3. レプリカ一覧の取得（リスナー経由の場合）
4. 各レプリカでGet-DbaDbBackupHistory実行
5. AvailabilityGroupNameプロパティの設定
6. Last/LastFull/LastDiff/LastLogによるフィルタリング

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaDbBackupHistory | msdb.dbo.backupset | SELECT | バックアップセット情報の読み取り |
| Get-DbaDbBackupHistory | msdb.dbo.backupmediafamily | SELECT | メディアファミリー情報の読み取り |
| Get-DbaDbBackupHistory | msdb.dbo.backupmediaset | SELECT | メディアセット情報の読み取り |
| Get-DbaDbBackupHistory | msdb.dbo.backupfile | SELECT | バックアップファイル情報の読み取り |
| Get-DbaDbBackupHistory | sys.databases | SELECT | データベースID取得 |
| Get-DbaLastBackup | （上記と同様） | SELECT | Get-DbaDbBackupHistoryを内部で使用 |
| Get-DbaAgBackupHistory | （上記と同様） | SELECT | Get-DbaDbBackupHistoryを内部で使用 |

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

本機能群はデータベースの更新を行わず、MSDBバックアップテーブルの読み取りのみを行います。

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|-----|---------|------|
| Warning | "Found backups from multiple recovery forks for $database" | 複数リカバリフォークが検出された場合 |
| Warning | "Parameter AGCheck is deprecated" | 非推奨パラメータ使用時 |
| Verbose | "Processing $db" | 各データベース処理開始時 |
| Verbose | "No Full Backup found for database" | フルバックアップが見つからない場合 |
| Verbose | "Valid Differential backup" | 有効な差分バックアップ検出時 |
| Verbose | "Defaulting to last Recovery Fork" | デフォルトリカバリフォーク使用時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQLインスタンス接続失敗 | Stop-Functionでエラー出力、処理継続 |
| SQL Server 2005未満 | MinimumVersion 9 チェックで接続拒否 |
| Since パラメータ形式エラー | TimeSpanまたはDateTime以外はエラー |
| 可用性グループ未検出 | Stop-Functionで警告、スキップ |
| 指定AGが存在しない | Stop-Functionで警告、スキップ |

## 備考

- Get-DbaDbBackupHistoryのLastパラメータは、リストア可能な完全バックアップチェーン（フル+差分+ログ）を返します
- 複数リカバリフォークが存在する場合、警告が出力されます。RecoveryForkパラメータで特定のフォークを指定できます
- コピーオンリーバックアップはデフォルトで除外されます（IncludeCopyOnlyで含める）
- SQL Server 2014以降では暗号化情報（EncryptorThumbprint等）も取得されます
- Get-DbaAgBackupHistoryはAGのリスナーを渡すと自動的に全レプリカを検出します

---

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

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

### 推奨読解順序

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

バックアップ履歴の中心となるデータ構造はBackupHistoryオブジェクトです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | BackupHistory.cs | `bin/projects/dbatools/dbatools/Database/BackupHistory.cs` | BackupHistoryクラスの構造を理解 |

**読解のコツ**: MSDBのbackupsetテーブルの構造とBackupHistoryオブジェクトのマッピングを意識してください。

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

Get-DbaDbBackupHistoryが主要なエントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | パラメータセット、SQLクエリ構築、結果処理 |

**主要処理フロー**:
1. **行255-296**: begin ブロック - デバイスタイプ・バックアップタイプマッピング
2. **行298-309**: パラメータ検証、Since処理
3. **行311-317**: SQLインスタンス接続
4. **行318-345**: バージョンに応じたカラム選択
5. **行365-438**: -Last パラメータ処理（再帰的にLastFull/LastDiff/ログを取得）
6. **行440-612**: -LastFull/-LastDiff/-LastLog パラメータ処理
7. **行615-722**: 通常のバックアップ履歴クエリ
8. **行728-815**: 結果のグループ化とBackupHistoryオブジェクト生成

#### Step 3: 最終バックアップ取得処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaLastBackup.ps1 | `public/Get-DbaLastBackup.ps1` | Get-DbaDbBackupHistoryの呼び出しとサマリー生成 |

**主要処理フロー**:
- **行108-116**: begin ブロック - ヘルパー関数定義
- **行117-133**: データベース一覧取得
- **行135-137**: 各タイプの最終バックアップ取得
- **行138-180**: 各データベースの処理とステータス判定
- **行182-203**: 結果オブジェクト生成

#### Step 4: AGバックアップ履歴取得処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAgBackupHistory.ps1 | `public/Get-DbaAgBackupHistory.ps1` | 複数レプリカからの履歴集約 |

**主要処理フロー**:
- **行221-247**: process ブロック - サーバーリスト構築
- **行250-264**: end ブロック - レプリカ検出
- **行268-278**: Get-DbaDbBackupHistory呼び出しと結果集約
- **行280-301**: Last/LastFull等のフィルタリング

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

```
Get-DbaDbBackupHistory
    |
    +-- Connect-DbaInstance (接続)
    |
    +-- [自己再帰呼び出し: -Last 時]
    |       +-- Get-DbaDbBackupHistory -LastFull
    |       +-- Get-DbaDbBackupHistory -LastDiff
    |       +-- Get-DbaDbBackupHistory (ログ取得)
    |
    +-- $server.ConnectionContext.ExecuteWithResults() (SQLクエリ実行)
    |
    +-- $server.Query() (FileList取得)

Get-DbaLastBackup
    |
    +-- Connect-DbaInstance (接続)
    |
    +-- Get-DbaDbBackupHistory -LastFull -IncludeCopyOnly -Raw
    +-- Get-DbaDbBackupHistory -LastDiff -IncludeCopyOnly -Raw
    +-- Get-DbaDbBackupHistory -LastLog -IncludeCopyOnly -Raw

Get-DbaAgBackupHistory
    |
    +-- Connect-DbaInstance (各レプリカへ)
    |
    +-- Get-DbaAgDatabase (AGデータベース取得)
    |
    +-- Get-DbaDbBackupHistory (各レプリカで実行)
    |
    +-- Select-DbaBackupInformation (-Last時)
```

### データフロー図

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

SQLインスタンス
      |
      v
+-------------------+
| Get-DbaDbBackup   |
| History           |
+-------------------+
      |
      +-- MSDB backupset -----> クエリ実行
      +-- MSDB backupmediafamily
      +-- MSDB backupmediaset
      +-- MSDB backupfile -----> FileList取得
      |
      v
BackupHistory[] ----------------> Restore-DbaDatabase
                                  Select-DbaBackupInformation
                                  Get-DbaLastBackup (内部使用)

SQLインスタンス(s)
      |
      v
+-------------------+
| Get-DbaLastBackup |
+-------------------+
      |
      +-- Get-DbaDbBackupHistory (内部呼び出し)
      |
      v
LastBackup サマリーオブジェクト

AGリスナー/レプリカ
      |
      v
+-------------------+
| Get-DbaAgBackup   |
| History           |
+-------------------+
      |
      +-- 各レプリカで Get-DbaDbBackupHistory
      |
      v
BackupHistory[] (全レプリカ統合)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得の主機能 |
| Get-DbaLastBackup.ps1 | `public/Get-DbaLastBackup.ps1` | ソース | 最終バックアップ状況サマリー |
| Get-DbaAgBackupHistory.ps1 | `public/Get-DbaAgBackupHistory.ps1` | ソース | AGバックアップ履歴統合取得 |
| Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | ソース | AGバックアップ履歴のLastフィルタリングで使用 |
| Get-DbaAgDatabase.ps1 | `public/Get-DbaAgDatabase.ps1` | ソース | AGデータベース一覧取得 |
| BackupHistory.cs | `bin/projects/dbatools/dbatools/Database/BackupHistory.cs` | ソース | BackupHistoryクラス定義 |
