# 機能設計書 50-Test-DbaBackupInformation

## 概要

本ドキュメントは、バックアップ履歴オブジェクトを検証してデータベースリストアの成功を確認するdbatools PowerShellコマンド `Test-DbaBackupInformation` の機能設計書である。

### 本機能の処理概要

この機能は、バックアップ履歴オブジェクトに対して包括的なリストア前検証を実行し、リストア失敗を事前に防止する。入力は通常Format-DbaBackupInformationから取得され、リストア準備完了性を確認するためにパースされる。

**業務上の目的・背景**：リストア操作は時間がかかり、失敗した場合の影響は大きい。特にメンテナンスウィンドウ中や災害復旧シナリオでは、事前に構成の問題を検出することが重要である。検証済みのバックアップセットはIsVerified = $Trueでマークされ、リストア候補として容易にフィルタリングできる。

**機能の利用シーン**：
- Restore-DbaDatabase実行前の検証
- 災害復旧計画の検証
- バックアップ整合性の定期チェック
- リストアスクリプトの事前テスト

**主要な処理内容**：
1. トランザクションログバックアップのLSNチェーン整合性検証
2. ターゲットデータベースの存在確認（WithReplace指定なしの場合）
3. SQL Serverサービスアカウントによるバックアップファイルアクセス確認
4. 既存データベースとのファイル競合検証
5. ターゲットディレクトリの作成（必要に応じて）

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

**権限による制御**：バックアップファイルおよびターゲットディレクトリへのアクセス権限、データベース存在確認のための権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | バックアップ情報 | 補助機能 | バックアップ情報の検証 |

## 機能種別

検証 / リストア前チェック

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| BackupHistory | object[] | Yes | Format-DbaBackupInformationからのバックアップ履歴 | パイプライン入力必須 |
| SqlInstance | DbaInstanceParameter | No | リストア先SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| WithReplace | switch | No | 既存データベースの置換を許可 | - |
| Continue | switch | No | 継続リストアを示す | - |
| VerifyOnly | switch | No | バックアップ読み取り可能性のみ検証 | - |
| OutputScriptOnly | switch | No | ディレクトリ自動作成を無効化 | - |
| EnableException | switch | No | 例外を有効にするスイッチ | - |
| WhatIf | switch | No | 実行せずに何が起きるか表示 | - |
| Confirm | switch | No | 確認プロンプト表示 | - |

### 入力データソース

Format-DbaBackupInformation出力オブジェクト

## 出力仕様

### 出力データ

入力されたBackupHistoryオブジェクトに IsVerified プロパティを追加して返す。

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (入力プロパティ全て) | - | 入力オブジェクトの全プロパティ |
| IsVerified | bool | 検証成功フラグ（追加プロパティ） |

### 出力先

PowerShellパイプライン（検証済みバックアップ履歴オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. SQL Server接続
   └─ Connect-DbaInstanceで接続確立
2. 既存ファイル情報取得
   └─ Get-DbaDbPhysicalFileで登録済みファイル一覧取得
3. データベースごとの検証
   ├─ 複数ソースデータベースチェック
   ├─ データベース存在チェック（WithReplace/Continue未指定時）
   ├─ ファイル競合チェック
   ├─ ターゲットパス存在チェック
   ├─ LSNチェーン検証（Continue未指定時）
   └─ バックアップファイル読み取り可能性検証
4. 検証結果マーキング
   └─ IsVerified = $True / 警告出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{接続成功?}
    C -->|No| D[Stop-Function]
    C -->|Yes| E[Get-DbaDbPhysicalFile]
    E --> F{各データベースループ}
    F --> G[複数ソースDBチェック]
    G --> H{VerifyOnly?}
    H -->|Yes| I[バックアップ読み取りのみ]
    H -->|No| J{DB存在 & WithReplace/Continue無?}
    J -->|Yes| K[警告: WithReplace必須]
    J -->|No| L[ファイル競合チェック]
    K --> M[VerificationErrors++]
    L --> N{自DBファイルとの競合?}
    N -->|Yes, Replace/Continue無| O[警告: ファイル競合]
    N -->|No| P{他DBファイルとの競合?}
    O --> M
    P -->|Yes| Q[警告: 他DBファイル使用中]
    P -->|No| R{パス存在?}
    Q --> M
    R -->|No| S{OutputScriptOnly?}
    S -->|No| T[New-DbaDirectory]
    S -->|Yes| U[警告: パス不存在]
    T --> V{Continue?}
    R -->|Yes| V
    U --> V
    V -->|No| W[Test-DbaLsnChain]
    V -->|Yes| X[バックアップ読み取りチェック]
    W --> X
    X --> Y{全パス読み取り可?}
    Y -->|No| Z[警告: 読み取り不可]
    Y -->|Yes| AA{VerificationErrors=0?}
    Z --> M
    M --> AA
    AA -->|Yes| AB[IsVerified = True]
    AA -->|No| AC[警告出力のみ]
    AB --> F
    AC --> F
    F --> AD[InternalHistory出力]
    AD --> AE[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-50-01 | 単一ソースDB | 1つのリストア対象DBに対して複数ソースDBからのバックアップは不可 | 常時 |
| BR-50-02 | DB存在チェック | ターゲットDBが既存の場合、WithReplaceまたはContinue必須 | VerifyOnly=false時 |
| BR-50-03 | ファイル競合 | 他DBが使用中のファイルパスへのリストア不可 | VerifyOnly=false時 |
| BR-50-04 | ディレクトリ作成 | ターゲットパスが存在しない場合、自動作成（OutputScriptOnly時は除く） | VerifyOnly=false時 |
| BR-50-05 | LSNチェーン | トランザクションログのLSNチェーンが連続していること | Continue=false時 |
| BR-50-06 | URL/S3スキップ | http/s3で始まるパスはアクセスチェックをスキップ | クラウドストレージ時 |

### 計算ロジック

特に複雑な計算ロジックは、Test-DbaLsnChain内部関数に委譲される。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ファイル情報取得 | sys.master_files | SELECT | 登録済みファイル一覧取得 |
| データベース存在確認 | sys.databases | SELECT | ターゲットDB存在確認 |
| ディレクトリ作成 | - | xp_create_subdir | ターゲットディレクトリ作成 |

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

#### sys.master_files（Get-DbaDbPhysicalFile経由）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | physical_name, database_id | 全ファイル | ファイル競合チェック用 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionで終了 |
| - | 複数ソースDB | 1つのターゲットに複数ソースDBのバックアップ | 警告出力、VerificationErrors++ |
| - | DB存在 | WithReplace/Continue無しでDB存在 | 警告出力、VerificationErrors++ |
| - | ファイル競合 | 他DBのファイルパスと重複 | 警告出力、VerificationErrors++ |
| - | パス不存在 | ターゲットディレクトリが存在しない | 自動作成または警告 |
| - | LSNチェーン破綻 | ログバックアップのLSN不連続 | 警告出力、VerificationErrors++ |
| - | 読み取り不可 | バックアップファイルにアクセスできない | 警告出力、VerificationErrors++ |

### リトライ仕様

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

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

読み取り専用操作（ディレクトリ作成除く）のため、トランザクション管理は不要。

## パフォーマンス要件

- Test-DbaPathで複数パスを一括チェックすることでパフォーマンス最適化
- VerifyOnlyモードでは一部チェックをスキップして高速化

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

- SQL Serverサービスアカウントがバックアップファイルにアクセス可能であること
- ターゲットディレクトリへの書き込み権限（ディレクトリ自動作成時）
- ConfirmImpact = "Low"で確認プロンプトは最小限

## 備考

- Restore-DbaDatabase内部で使用される検証処理コマンド
- 検証エラーがあってもリストアは実行可能（警告のみ）
- ただし、検証エラーがあると実際のリストアで失敗する可能性が高い

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: ConfirmImpact = "Low"なので確認プロンプトは最小限。

#### Step 2: 初期化と物理ファイル取得を理解する

beginブロックの処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaBackupInformation.ps1 | `public/Test-DbaBackupInformation.ps1` | 106-114行目 |

**主要処理フロー**:
- **107-112行目**: Connect-DbaInstance接続

#### Step 3: 物理ファイル競合チェックを理解する

登録済みファイルとの競合チェックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaBackupInformation.ps1 | `public/Test-DbaBackupInformation.ps1` | 125-167行目 |

**主要処理フロー**:
- **125行目**: Get-DbaDbPhysicalFileで全ファイル取得
- **147-148行目**: DBFileCheckとOtherFileCheckの分離
- **153-167行目**: パスごとの競合チェック

#### Step 4: LSNチェーン検証を理解する

Test-DbaLsnChainの使用を確認する。

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

**主要処理フロー**:
- **196-197行目**: Continue未指定時のTest-DbaLsnChain呼び出し

#### Step 5: バックアップ読み取りチェックを理解する

Test-DbaPathによるアクセスチェックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Test-DbaBackupInformation.ps1 | `public/Test-DbaBackupInformation.ps1` | 205-212行目 |

**主要処理フロー**:
- **205行目**: 全パスの取得
- **206行目**: Test-DbaPathで一括チェック
- **207-211行目**: http/s3以外のパスでアクセス不可の場合に警告

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

```
Test-DbaBackupInformation
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ Get-DbaDbPhysicalFile
    │      └─ 登録済みファイル一覧取得
    │
    ├─ Get-DbaDatabase
    │      └─ ターゲットDB存在確認
    │
    ├─ Test-DbaPath
    │      └─ パスアクセス可能性チェック
    │
    ├─ New-DbaDirectory
    │      └─ ターゲットディレクトリ作成
    │
    └─ Test-DbaLsnChain
           └─ LSNチェーン整合性検証
```

### データフロー図

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

BackupHistory ───────────────► processブロックで収集 ────────────►
                                      │
SqlInstance ─────────────────► Connect-DbaInstance ──────────────►
                                      │
                                      ▼
                              Get-DbaDbPhysicalFile
                                      │
                                      ▼
                              データベースループ
                                      │
                                      ├──► Get-DbaDatabase（存在確認）
                                      │
                                      ├──► ファイル競合チェック
                                      │
WithReplace ─────────────────► ├──► パス存在チェック
Continue ────────────────────►         │
                                      ├──► New-DbaDirectory（必要時）
                                      │
                                      ├──► Test-DbaLsnChain
                                      │
                                      └──► Test-DbaPath（読み取りチェック）
                                             │
                                             ▼
                                      VerificationErrors判定
                                             │
                                             ▼
                              IsVerified設定 ────► 出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaBackupInformation.ps1 | `public/Test-DbaBackupInformation.ps1` | ソース | メイン機能実装 |
| Test-DbaBackupInformation.Tests.ps1 | `tests/Test-DbaBackupInformation.Tests.ps1` | テスト | Pesterテストコード |
| Format-DbaBackupInformation.ps1 | `public/Format-DbaBackupInformation.ps1` | ソース | 入力データ提供（前段コマンド） |
| Test-DbaLsnChain.ps1 | `private/functions/Test-DbaLsnChain.ps1` | ソース | LSNチェーン検証（依存関数） |
| Get-DbaDbPhysicalFile.ps1 | `public/Get-DbaDbPhysicalFile.ps1` | ソース | 物理ファイル取得（依存コマンド） |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パスアクセスチェック（依存コマンド） |
| New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | ソース | ディレクトリ作成（依存コマンド） |
