# 機能設計書 34-Get-DbaAgBackupHistory

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Get-DbaAgBackupHistory`コマンドレットに関する機能設計書です。このコマンドは、SQL Server可用性グループの全レプリカからmsdbのバックアップ履歴を取得し、統合されたビューを提供します。

### 本機能の処理概要

Get-DbaAgBackupHistoryは、可用性グループ（AG）内の全レプリカに対してmsdbバックアップ履歴テーブルをクエリし、結果を統合ビューとして集約します。リスナーまたは個別レプリカを指定することで、バックアップがどのレプリカから実行されてもローカルmsdbにのみ記録されるという課題を解決します。

**業務上の目的・背景**：可用性グループ環境では、バックアップは任意のレプリカから実行可能ですが、バックアップ履歴は実行したレプリカのmsdbにのみ記録されます。このため、コンプライアンスレポートやリカバリ計画において、複数レプリカからバックアップ履歴を収集する必要があります。この機能により、DBAは分散したバックアップ履歴を一元的に把握できます。

**機能の利用シーン**：
- 可用性グループのバックアップコンプライアンス監査
- ディザスタリカバリ計画のためのバックアップ状況確認
- バックアップ戦略のトラブルシューティング
- 全レプリカにわたるバックアップタイムラインの分析

**主要な処理内容**：
1. 指定されたインスタンス（リスナーまたはレプリカ）への接続
2. 可用性グループの存在確認とレプリカ一覧の取得
3. 各レプリカに対するGet-DbaDbBackupHistoryの呼び出し
4. 結果にAvailabilityGroupNameを付加して統合
5. Last/LastFull/LastDiff/LastLogフィルタリングの適用

**関連システム・外部連携**：
- Get-DbaDbBackupHistory（バックアップ履歴取得の基盤機能）
- Get-DbaAgDatabase（AGデータベース一覧取得）
- Select-DbaBackupInformation（バックアップ選択）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | バックアップ履歴 | 補助機能 | 可用性グループバックアップ履歴の取得 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | SQL Serverインスタンス（リスナーまたはレプリカ配列） | パイプライン入力対応 |
| SqlCredential | PSCredential | No | 接続資格情報 | - |
| AvailabilityGroup | string | Yes | 可用性グループ名 | インスタンスに存在すること |
| Database | string[] | No | 対象データベース | - |
| ExcludeDatabase | string[] | No | 除外データベース | - |
| IncludeCopyOnly | switch | No | コピーオンリーバックアップを含む | - |
| Force | switch | No | 詳細情報を返す | - |
| Since | DateTime | No | 指定日時以降のバックアップ | デフォルト: 1970-01-01 |
| 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 | ミラーバックアップを含む | - |
| LsnSort | string | No | ソート基準LSN | FirstLsn/DatabaseBackupLsn/LastLsn |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- msdb.dbo.backupset
- msdb.dbo.backupmediafamily
- msdb.dbo.backupmediaset
- 各レプリカのAvailabilityGroups情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | SQL Serverインスタンス名 |
| Database | string | データベース名 |
| Type | string | バックアップタイプ |
| TotalSize | long | バックアップサイズ |
| DeviceType | string | デバイスタイプ |
| Start | DateTime | バックアップ開始日時 |
| Duration | TimeSpan | バックアップ所要時間 |
| End | DateTime | バックアップ終了日時 |
| AvailabilityGroupName | string | 可用性グループ名（追加） |
| FirstLsn | bigint | 最初のLSN |
| LastLsn | bigint | 最後のLSN |
| FullName | string[] | バックアップファイルパス |

### 出力先

- PowerShellパイプライン（Dataplat.Dbatools.Database.BackupHistory）

## 処理フロー

### 処理シーケンス

```
1. begin ブロック
   └─ サーバーリスト初期化

2. process ブロック（各SqlInstanceに対して）
   └─ Connect-DbaInstanceでSQL Server 2005以上に接続
   └─ 可用性グループ存在チェック
   └─ 指定AGがインスタンスに存在するか確認
   └─ サーバーリストに追加

3. end ブロック
   └─ サーバーリストが空の場合は終了
   └─ サーバーが1つの場合（リスナー想定）:
      └─ レプリカ名一覧を取得してサーバーリストに設定
   └─ Database未指定時はAGデータベース一覧を取得
   └─ Get-DbaDbBackupHistoryを全レプリカに対して実行
   └─ 各結果にAvailabilityGroupName設定
   └─ Last/LastFull/LastDiff/LastLogフィルタリング
   └─ 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[foreach SqlInstance]
    B --> C[Connect-DbaInstance]
    C --> D{AG存在?}
    D -->|No| E[Stop-Function: AGなし]
    D -->|Yes| F{指定AG存在?}
    F -->|No| G[Stop-Function: 指定AGなし]
    F -->|Yes| H[サーバーリスト追加]
    H --> B
    B --> I{サーバーリスト空?}
    I -->|Yes| J[終了]
    I -->|No| K{サーバー数=1?}
    K -->|Yes| L[レプリカ一覧取得]
    L --> M[サーバーリスト更新]
    K -->|No| M
    M --> N{Database指定?}
    N -->|No| O[AGデータベース一覧取得]
    N -->|Yes| P[Get-DbaDbBackupHistory実行]
    O --> P
    P --> Q[AvailabilityGroupName設定]
    Q --> R{Lastフィルタ?}
    R -->|Last| S[Select-DbaBackupInformation]
    R -->|LastFull/Diff/Log| T[DB別ソート＆最新選択]
    R -->|No| U[結果出力]
    S --> U
    T --> U
    U --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 最小バージョン | SQL Server 2005以上が必要 | 接続時 |
| BR-02 | リスナー自動展開 | 1インスタンスの場合はリスナーとして全レプリカ取得 | end処理時 |
| BR-03 | AGデータベース自動取得 | Database未指定時は指定AGの全データベースを対象 | end処理時 |
| BR-04 | Lastフィルタ | -LastはSelect-DbaBackupInformationで処理 | フィルタ時 |
| BR-05 | 結果統合 | 各レプリカの結果を統合しAvailabilityGroupNameを付加 | 結果処理時 |

### 計算ロジック

Lastフィルタリング：
- Last: Select-DbaBackupInformationで最小リストア可能チェーン
- LastFull/Diff/Log: データベース別にLsnSortでソートし最新1件を選択

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

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

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

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

内部でGet-DbaDbBackupHistoryを呼び出すため、詳細はそちらを参照。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | インスタンス接続失敗 | 接続情報確認 |
| - | NoAG | インスタンスにAGなし | AG対応インスタンス指定 |
| - | AGNotFound | 指定AGが存在しない | 正しいAG名指定 |
| - | NoResults | 結果なし | フィルタ条件確認 |

### リトライ仕様

リトライ機能は実装されていません。各インスタンスに対して-Continueでエラー継続。

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

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

## パフォーマンス要件

各レプリカに対して個別にクエリを実行するため、レプリカ数に比例した処理時間が必要です。

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

- 各レプリカのmsdbへの読み取り権限が必要
- SqlCredentialで認証情報を安全に渡す
- AG構成情報へのアクセス権限も必要

## 備考

- 参照: http://www.sqlhub.com/2011/07/find-your-backup-history-in-sql-server.html
- 内部でGet-DbaDbBackupHistoryを使用しているため、そちらの機能も継承

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgBackupHistory.ps1 | `public/Get-DbaAgBackupHistory.ps1` | パラメータ定義（190-219行目）、特にParameterSetName |

**読解のコツ**: `ParameterSetName`で`Default`と`NoLast`の2つのパラメータセットが定義されている。

#### Step 2: begin ブロックの初期化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgBackupHistory.ps1 | `public/Get-DbaAgBackupHistory.ps1` | beginブロック（221-225行目）でのサーバーリスト初期化 |

**主要処理フロー**:
1. **222-223行目**: パラメータセットとバインドパラメータのログ出力
2. **224行目**: 空のサーバーリスト初期化

#### Step 3: process ブロックでのインスタンス収集を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgBackupHistory.ps1 | `public/Get-DbaAgBackupHistory.ps1` | processブロック（227-248行目）でのインスタンス接続とAG確認 |

**主要処理フロー**:
- **229-232行目**: Connect-DbaInstance（MinimumVersion 9 = SQL 2005以上）
- **235-238行目**: AGなしインスタンスのスキップ
- **240-243行目**: 指定AGなしインスタンスのスキップ
- **245-246行目**: サーバーリストへの追加

#### Step 4: end ブロックの結果集約を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAgBackupHistory.ps1 | `public/Get-DbaAgBackupHistory.ps1` | endブロック（250-302行目）での結果集約とフィルタリング |

**主要処理フロー**:
- **251-254行目**: サーバーリスト空チェック
- **256-264行目**: リスナーの場合のレプリカ一覧取得
- **268-271行目**: Database未指定時のAGデータベース取得
- **275行目**: Get-DbaDbBackupHistoryの呼び出し
- **276-278行目**: AvailabilityGroupName設定
- **280-301行目**: Last/LastFull/LastDiff/LastLogフィルタリング

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

```
Get-DbaAgBackupHistory
    │
    ├─ begin ブロック
    │      └─ $serverList 初期化
    │
    ├─ process ブロック (foreach $instance)
    │      │
    │      ├─ Connect-DbaInstance (MinimumVersion 9)
    │      │
    │      ├─ AG存在チェック
    │      │      └─ $server.AvailabilityGroups.Count
    │      │
    │      └─ 指定AG存在チェック
    │             └─ $AvailabilityGroup -in $server.AvailabilityGroups.Name
    │
    └─ end ブロック
           │
           ├─ リスナー展開 (サーバー数=1の場合)
           │      └─ AvailabilityReplicas.Name 取得
           │
           ├─ Get-DbaAgDatabase
           │      └─ AGデータベース一覧取得
           │
           ├─ Get-DbaDbBackupHistory
           │      └─ 全レプリカのバックアップ履歴取得
           │
           ├─ AvailabilityGroupName 設定
           │
           └─ フィルタリング
                  ├─ -Last: Select-DbaBackupInformation
                  └─ -LastFull/Diff/Log: Sort + Select -Last 1
```

### データフロー図

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

$SqlInstance ──────────▶ Connect-DbaInstance ─────────▶ $server
(リスナー or レプリカ)            │
                                 │
$AvailabilityGroup ────▶ AG存在確認 ─────────────────▶ $serverList
                                 │
(1サーバーの場合) ────────▶ レプリカ一覧取得 ──────────▶ $serverList更新
                                 │
$serverList ───────────▶ Get-DbaDbBackupHistory ───▶ $AgResults
                                 │
$AvailabilityGroup ────▶ AvailabilityGroupName設定 ─▶ $AgResults
                                 │
$Last/LastFull/... ────▶ フィルタリング ───────────────▶ 最終結果
                                                        (BackupHistory[])
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgBackupHistory.ps1 | `public/Get-DbaAgBackupHistory.ps1` | ソース | メイン関数実装 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得基盤 |
| Get-DbaAgDatabase.ps1 | `public/Get-DbaAgDatabase.ps1` | ソース | AGデータベース一覧取得 |
| Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | ソース | Lastフィルタ用 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
