# 機能設計書 37-Get-DbaDbBackupHistory

## 概要

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

### 本機能の処理概要

Get-DbaDbBackupHistoryは、MSDBデータベースのバックアップテーブル（backupset、backupmediafamily、backupmediaset）をクエリし、ファイルパス、サイズ、圧縮率、LSNシーケンスなどの詳細なバックアップ履歴情報を抽出します。コンプライアンス監査、ディザスタリカバリ計画、バックアップ問題のトラブルシューティングに不可欠です。

**業務上の目的・背景**：システムテーブルを手動でクエリすることなく、バックアップ履歴情報を効率的に取得する必要があります。この機能により、ストライプバックアップセットの自動グループ化、コピーオンリーバックアップの除外（デフォルト）、ポイントインタイムリカバリに必要な最新バックアップチェーンの取得など、実用的な出力を提供します。

**機能の利用シーン**：
- コンプライアンス監査用のバックアップ履歴レポート作成
- ディザスタリカバリ計画のための最新バックアップ確認
- バックアップ戦略のトラブルシューティング
- 複数インスタンスにわたるバックアップ状況の一括確認

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続
2. バージョン別のクエリ構築（暗号化、圧縮対応）
3. MSDBバックアップテーブルへのクエリ実行
4. ストライプバックアップのグループ化
5. BackupHistoryオブジェクトの構築と出力

**関連システム・外部連携**：
- Get-DbaAgBackupHistory（AGバックアップ履歴の基盤）
- Select-DbaBackupInformation（バックアップ選択）
- Restore-DbaDatabase（リストア実行先）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | バックアップ履歴 | 主機能 | データベースバックアップ履歴の取得 |

## 機能種別

データ取得処理 / 集約クエリ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | SQL Serverインスタンス（複数可） | パイプライン入力対応 |
| SqlCredential | PSCredential | No | 接続資格情報 | - |
| Database | object[] | No | 対象データベース | ワイルドカード対応 |
| ExcludeDatabase | object[] | No | 除外データベース | - |
| IncludeCopyOnly | switch | No | コピーオンリーバックアップを含む | - |
| Force | switch | No | 全カラムを返す | - |
| Since | psobject | No | 指定日時以降のバックアップ | DateTime/TimeSpan |
| RecoveryFork | string | No | リカバリフォークGUID | GUID形式 |
| Last | switch | No | 最新の完全バックアップチェーン | - |
| LastFull | switch | No | 最新のフルバックアップ | - |
| LastDiff | switch | No | 最新の差分バックアップ | - |
| LastLog | switch | No | 最新のログバックアップ | - |
| DeviceType | string[] | No | デバイスタイプフィルタ | - |
| Raw | switch | No | 個別ファイル詳細を返す | - |
| Type | string[] | No | バックアップタイプフィルタ | Full/Log/Differential等 |
| LastLsn | bigint | No | 指定LSN以降のバックアップ | - |
| IncludeMirror | switch | No | ミラーバックアップを含む | - |
| AgCheck | switch | No | 非推奨（Get-DbaAgBackupHistory使用） | - |
| IgnoreDiffBackup | switch | No | 差分バックアップを除外 | - |
| LsnSort | string | No | ソート基準LSN | FirstLsn/DatabaseBackupLsn/LastLsn |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- msdb.dbo.backupset
- msdb.dbo.backupmediafamily
- msdb.dbo.backupmediaset
- msdb.dbo.backupfile

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホスト名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| 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 | bigint | 最初のLSN |
| DatabaseBackupLsn | bigint | データベースバックアップLSN |
| CheckpointLsn | bigint | チェックポイントLSN |
| LastLsn | bigint | 最後のLSN |
| SoftwareVersionMajor | int | SQL Serverメジャーバージョン |
| IsCopyOnly | bool | コピーオンリーフラグ |
| LastRecoveryForkGuid | guid | リカバリフォークGUID |
| RecoveryModel | string | リカバリモデル |
| EncryptorThumbprint | string | 暗号化証明書サムプリント |
| EncryptorType | string | 暗号化タイプ |
| KeyAlgorithm | string | キーアルゴリズム |

### 出力先

- PowerShellパイプライン（Dataplat.Dbatools.Database.BackupHistory または DataRow）

## 処理フロー

### 処理シーケンス

```
1. begin ブロック
   └─ デバイスタイプマッピング構築
   └─ バックアップタイプマッピング構築
   └─ LsnSort変換

2. process ブロック（各SqlInstanceに対して）
   └─ AgCheck非推奨チェック
   └─ Since型チェック（DateTime/TimeSpan）
   └─ Connect-DbaInstance（MinimumVersion 9）

3. バージョン別カラム設定
   └─ SQL 2014+: 暗号化カラム追加
   └─ SQL 2008-2012: 圧縮カラムのみ
   └─ SQL 2005: 基本カラムのみ

4. クエリ構築
   ├─ Last: 再帰的にFull→Diff→Log取得
   ├─ LastFull/Diff/Log: RANKによる最新取得
   └─ 通常: フィルタ付きSELECT

5. 結果処理
   ├─ Raw: そのまま出力
   └─ グループ化:
       └─ BackupSetIdでGroup-Object
       └─ FileList取得（#BackupSetIds一時テーブル使用）
       └─ BackupHistoryオブジェクト構築
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[デバイス/タイプマッピング構築]
    B --> C[foreach SqlInstance]
    C --> D{AgCheck?}
    D -->|Yes| E[Stop-Function: 非推奨]
    D -->|No| F[Connect-DbaInstance]
    F --> G[バージョン別カラム設定]
    G --> H{Last?}
    H -->|Yes| I[Full→Diff→Log再帰取得]
    H -->|No| J{LastFull/Diff/Log?}
    J -->|Yes| K[RANKクエリ構築]
    J -->|No| L[通常クエリ構築]
    I --> M[クエリ実行]
    K --> M
    L --> M
    M --> N{Raw?}
    N -->|Yes| O[DataRow出力]
    N -->|No| P[BackupSetIdグループ化]
    P --> Q[FileList取得]
    Q --> R[BackupHistory構築]
    R --> S[出力]
    O --> S
    S --> C
    C --> T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 最小バージョン | SQL Server 2005以上が必要 | 接続時 |
| BR-02 | コピーオンリー除外 | デフォルトでコピーオンリーバックアップを除外 | IncludeCopyOnly未指定時 |
| BR-03 | ストライプグループ化 | 同一BackupSetIdのファイルをグループ化 | Raw未指定時 |
| BR-04 | リカバリフォーク処理 | 複数フォーク存在時は最新を使用 | Last系使用時 |
| BR-05 | LSNソート | last_lsnでデフォルトソート | - |

### 計算ロジック

圧縮率計算：
```
CompressionRatio = TotalSize / CompressedBackupSize
```

Duration計算：
```
Duration = New-TimeSpan -Seconds (End - Start).TotalSeconds
```

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

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

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

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

#### msdb.dbo.backupset

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | database_name, backup_start_date, backup_finish_date等 | database_name, type, is_copy_only等でフィルタ | JOINで使用 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | インスタンス接続失敗 | 接続情報確認 |
| - | InvalidSince | Since型不正 | DateTime/TimeSpan使用 |
| - | Deprecated | AgCheck使用 | Get-DbaAgBackupHistory使用 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- LSNでのRANKによる最新取得で効率的なクエリ
- FileList取得で一時テーブル使用により効率化
- 大量履歴の場合はSinceやDatabaseフィルタ推奨

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

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

## 備考

- 参照: http://www.sqlhub.com/2011/07/find-your-backup-history-in-sql-server.html
- DST問題を考慮してlast_lsnでソート

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | パラメータ定義（224-253行目）、DefaultとNoLastの2つのParameterSet |

**読解のコツ**: `ParameterSetName`で"Default"と"NoLast"があり、Forceは"NoLast"のみで使用可能。

#### Step 2: begin ブロックのマッピング構築を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | beginブロック（255-296行目）でのデバイス/バックアップタイプマッピング |

**主要処理フロー**:
1. **259-268行目**: deviceTypeMapping（デバイスタイプ名→数値）
2. **277-285行目**: backupTypeMapping（タイプ名→コード）
3. **291-295行目**: LsnSort変換

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | processブロック（298-817行目）でのバージョン別クエリとBackupHistory構築 |

**主要処理フロー**:
- **318-345行目**: バージョン別バックアップカラム設定
- **365-438行目**: Lastモードの再帰的取得
- **440-613行目**: LastFull/Diff/LogのRANKクエリ
- **615-722行目**: 通常クエリ構築
- **728-814行目**: グループ化とBackupHistory構築

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

```
Get-DbaDbBackupHistory
    │
    ├─ begin ブロック
    │      │
    │      ├─ deviceTypeMapping 構築
    │      ├─ backupTypeMapping 構築
    │      └─ LsnSort 変換
    │
    └─ process ブロック (foreach $instance)
           │
           ├─ Connect-DbaInstance (MinimumVersion 9)
           │
           ├─ バージョン別カラム設定
           │      ├─ SQL 2014+: 暗号化対応
           │      ├─ SQL 2008-2012: 圧縮対応
           │      └─ SQL 2005: 基本
           │
           ├─ クエリ構築
           │      ├─ Last: 再帰的Full→Diff→Log
           │      ├─ LastFull/Diff/Log: RANK使用
           │      └─ 通常: フィルタ付きSELECT
           │
           ├─ ExecuteWithResults
           │
           └─ 結果処理
                  ├─ Raw: DataRow出力
                  └─ グループ化:
                         ├─ Group-Object BackupSetId
                         ├─ FileList取得 (#BackupSetIds)
                         └─ BackupHistory構築
```

### データフロー図

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

$SqlInstance ──────────▶ Connect-DbaInstance ─────────▶ $server
                                 │
$Database ─────────────▶ クエリ構築 ──────────────────▶ $sql
$ExcludeDatabase                 │
$Since                           │
$DeviceType                      │
$Type                            │
                                 │
$sql ──────────────────▶ ExecuteWithResults ─────────▶ $results
                                 │
$results ──────────────▶ グループ化 ─────────────────▶ $groupedResults
                                 │
$groupedResults ───────▶ FileList取得 ───────────────▶ $fileListHash
                                 │
                         BackupHistory構築
                                 │
                                 └─────────────────────▶ BackupHistory[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | メイン関数実装 |
| Get-DbaAgBackupHistory.ps1 | `public/Get-DbaAgBackupHistory.ps1` | ソース | AG履歴（本関数を使用） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
