# 機能設計書 48-Select-DbaBackupInformation

## 概要

本ドキュメントは、ポイントインタイムデータベースリカバリに必要な最小限のバックアップチェーンを特定するdbatools PowerShellコマンド `Select-DbaBackupInformation` の機能設計書である。

### 本機能の処理概要

この機能は、バックアップ履歴オブジェクトを分析し、特定のポイントインタイムへのデータベースリストアに必要なバックアップの正確なシーケンスを決定する。フル、差分、トランザクションログバックアップから必要なものを特定する複雑なLSNロジックを処理し、手動リストア計画の推測作業を排除する。

**業務上の目的・背景**：ポイントインタイムリカバリでは、どのバックアップファイルが必要で、どの順序でリストアすべきかを正確に把握する必要がある。LSN（Log Sequence Number）チェーンの理解は複雑であり、誤ったファイル選択はリストア失敗につながる。本機能はこのプロセスを自動化する。

**機能の利用シーン**：
- 災害復旧時の必要バックアップファイル特定
- リストア計画の作成と検証
- バックアップストレージ最適化（不要ファイルの特定）
- 継続的リストア操作のサポート

**主要な処理内容**：
1. バックアップ履歴の受け取りとフィルタリング
2. フルバックアップの特定（RestoreTime以前で最新のもの）
3. 差分バックアップの特定（オプション）
4. トランザクションログバックアップチェーンの構築
5. 継続リストア（Continue）モードのサポート

**関連システム・外部連携**：Get-DbaBackupInformationの出力を入力として受け取る。

**権限による制御**：特に権限は不要（メモリ内のオブジェクト処理）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | バックアップ情報 | 補助機能 | バックアップ履歴のフィルタリング |

## 機能種別

データフィルタリング / バックアップチェーン選択

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| BackupHistory | object | Yes | Get-DbaBackupInformationからのバックアップ履歴 | パイプライン入力必須 |
| RestoreTime | DateTime | No | リストア目標時刻。デフォルト: 1ヶ月後 | - |
| IgnoreLogs | switch | No | トランザクションログバックアップを除外 | - |
| IgnoreDiffs | switch | No | 差分バックアップを除外 | - |
| DatabaseName | string[] | No | 対象データベース名でフィルタ | - |
| ServerName | string[] | No | サーバー名/AG名でフィルタ | - |
| ContinuePoints | object | No | 継続リストアのためのLSN情報 | - |
| LastRestoreType | object | No | 最後に実行されたリストアタイプ情報 | - |
| EnableException | switch | No | 例外を有効にするスイッチ | - |

### 入力データソース

Get-DbaBackupInformation出力オブジェクト

## 出力仕様

### 出力データ

入力されたBackupHistoryオブジェクトのうち、リストアチェーンに必要なもののみが返される。

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Database | string | データベース名 |
| Type | string | バックアップタイプ（Full/Differential/Log等） |
| BackupSetID | string | バックアップセットID |
| Start | DateTime | バックアップ開始日時 |
| End | DateTime | バックアップ終了日時 |
| FirstLsn | bigint | 最初のLSN |
| LastLsn | bigint | 最後のLSN |
| CheckpointLsn | bigint | チェックポイントLSN |
| DatabaseBackupLsn | bigint | データベースバックアップLSN |
| FullName | string[] | バックアップファイルパス |
| RestoreTime | DateTime | リストア目標時刻（追加プロパティ） |

### 出力先

PowerShellパイプライン（フィルタ済みバックアップ履歴オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. 入力バックアップ履歴の収集
   └─ processブロックでパイプライン入力を集約
2. RestoreTimeプロパティの追加
   └─ 各履歴オブジェクトにRestoreTime追加
3. フィルタリング
   └─ DatabaseName/ServerNameによる絞り込み
4. データベースごとの処理
   ├─ フルバックアップ特定（IgnoreFull=false時）
   ├─ 差分バックアップ特定（IgnoreDiffs=false時）
   └─ ログバックアップチェーン構築（IgnoreLogs=false時）
5. 結果出力
   └─ 選択されたバックアップ履歴を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[BackupHistory収集]
    B --> C[RestoreTimeプロパティ追加]
    C --> D{DatabaseName指定?}
    D -->|Yes| E[データベースフィルタ]
    D -->|No| F{ServerName指定?}
    E --> F
    F -->|Yes| G[サーバー/AGフィルタ]
    F -->|No| H[データベースループ]
    G --> H
    H --> I{Continue指定?}
    I -->|Yes| J[ContinuePoints処理]
    I -->|No| K{IgnoreFull?}
    J --> L{IgnoreDiffs判定}
    K -->|No| M[フルバックアップ特定]
    K -->|Yes| L
    M --> L
    L -->|No| N[差分バックアップ特定]
    L -->|Yes| O[ログベースLSN決定]
    N --> O
    O --> P{IgnoreLogs?}
    P -->|No| Q[ログバックアップチェーン構築]
    P -->|Yes| R[dbhistory出力]
    Q --> R
    R --> H
    H --> S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-48-01 | フルバックアップ選択 | RestoreTime以前で最新のフルバックアップを選択 | IgnoreFull=false時 |
| BR-48-02 | 差分バックアップ選択 | フルのCheckpointLSNと一致するDatabaseBackupLSNを持つ最新差分を選択 | IgnoreDiffs=false時 |
| BR-48-03 | ログチェーン構築 | LogBaseLsn以上のLastLsnを持ち、RestoreTime以前のログを選択 | IgnoreLogs=false時 |
| BR-48-04 | 継続リストア | ContinuePoints指定時はフルバックアップをスキップ | Continue時 |
| BR-48-05 | 最終ログ選択 | RestoreTime以降で最初のログバックアップも含める | ポイントインタイム用 |

### 計算ロジック

**ログベースLSN決定（236-250行目）**:
```powershell
if ($null -ne ($dbHistory | Sort-Object -Property LastLsn -Descending | Select-Object -First 1).lastLsn) {
    [bigint]$LogBaseLsn = ($dbHistory | Sort-Object -Property LastLsn -Descending | Select-Object -First 1).lastLsn.ToString()
    $FirstRecoveryForkID = $Full.FirstRecoveryForkID
} else {
    # ContinuePointsから取得
    [bigint]$LogBaseLsn = ($ContinuePoints | Where-Object { $_.Database -eq $DatabaseFilter }).redo_start_lsn
    $FirstRecoveryForkID = ($ContinuePoints | Where-Object { $_.Database -eq $DatabaseFilter }).FirstRecoveryForkID
}
```

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

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

本機能はデータベース操作を行わない（メモリ内のオブジェクト処理のみ）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | フルバックアップなし | フルバックアップが見つからない | Stop-Functionでエラー |
| - | 継続リストア不整合 | 複数DBの継続リストアとリネーム | Stop-Functionでエラー |
| - | LSN取得失敗 | ContinuePointsからのLSN取得失敗 | Stop-Functionでエラー |

### リトライ仕様

本機能にはリトライ機構は実装されていない。

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

メモリ内のオブジェクト処理のため、トランザクション管理は不要。

## パフォーマンス要件

大量のバックアップ履歴がある場合でも、メモリ内でのフィルタリング処理のため高速に動作する。

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

特になし（メモリ内オブジェクト処理のみ）。

## 備考

- Restore-DbaDatabase内部で使用される中間処理コマンド
- 可用性グループの場合、ServerNameはAG名でフィルタリングされる
- DatabaseName/ServerNameフィルタはワイルドカードをサポート

---

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

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

### 推奨読解順序

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

入力パラメータの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | 108-120行目のparam定義 |

**読解のコツ**: BackupHistoryはパイプライン入力必須。RestoreTimeのデフォルトは1ヶ月後。

#### Step 2: 継続リストア（Continue）処理を理解する

ContinuePoints指定時の特別処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | 121-138行目のbeginブロック |

**主要処理フロー**:
- **124-127行目**: ContinuePoints指定時のフラグ設定
- **128-137行目**: DatabaseNameのContinuePointsによるフィルタリング

#### Step 3: データベースごとの処理を理解する

フル/差分/ログバックアップの選択ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | 173-269行目のデータベースループ |

**主要処理フロー**:
- **204-212行目**: フルバックアップの選択
- **221-232行目**: 差分バックアップの選択
- **252-267行目**: ログバックアップチェーンの構築

#### Step 4: LSNチェーン構築を理解する

ログバックアップのLSNフィルタリングを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | 252-267行目 |

**主要処理フロー**:
- **253行目**: LogBaseLsn以上、RestoreTime以前、FirstLsn != LastLsnでフィルタ
- **254-258行目**: BackupSetIDでグループ化
- **262-265行目**: RestoreTime以降の最初のログも含める

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

```
Select-DbaBackupInformation
    │
    └─ 内部処理のみ（他のコマンド呼び出しなし）
           │
           ├─ RestoreTimeプロパティ追加
           │
           ├─ DatabaseName/ServerNameフィルタ
           │
           ├─ フルバックアップ選択
           │      └─ Type='Full'/'Database', End <= RestoreTime
           │
           ├─ 差分バックアップ選択
           │      └─ DatabaseBackupLSN = Full.CheckpointLSN
           │
           └─ ログバックアップチェーン構築
                  └─ LastLsn >= LogBaseLsn, Start < RestoreTime
```

### データフロー図

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

BackupHistory ───────────────► processブロックで収集 ────────────►
                                      │
                                      ▼
                              RestoreTime追加
                                      │
                                      ▼
DatabaseName ────────────────► フィルタリング ───────────────────►
ServerName ──────────────────►         │
                                      ▼
                              データベースループ
                                      │
                                      ├──► フルバックアップ選択
                                      │
IgnoreDiffs ─────────────────► ├──► 差分バックアップ選択
                                      │
IgnoreLogs ──────────────────► └──► ログチェーン構築
                                      │
                                      ▼
ContinuePoints ──────────────► LSN決定 ────────────────────────►
                                      │
                                      ▼
                              選択済みバックアップ ────► 出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | ソース | メイン機能実装 |
| Select-DbaBackupInformation.Tests.ps1 | `tests/Select-DbaBackupInformation.Tests.ps1` | テスト | Pesterテストコード |
| Get-DbaBackupInformation.ps1 | `public/Get-DbaBackupInformation.ps1` | ソース | 入力データ提供（前段コマンド） |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | 本機能を呼び出すコマンド |
