# 機能設計書 51-Test-DbaLastBackup

## 概要

本ドキュメントは、SQL Serverデータベースの最新バックアップをテスト検証する機能「Test-DbaLastBackup」の設計仕様を記述する。

### 本機能の処理概要

Test-DbaLastBackupは、SQL Serverインスタンス上のデータベースに対して最新のバックアップファイルをリストアし、データベースの整合性チェック(DBCC CHECKDB)を実行することで、バックアップの復元可能性と完全性を検証する機能である。

**業務上の目的・背景**：データベースのバックアップは災害復旧(DR)戦略の根幹であるが、バックアップファイルが実際にリストア可能であることを定期的に確認しなければ、いざという時に復旧できないリスクがある。本機能は、バックアップのリストア検証とDBCC CHECKDBによる整合性確認を自動化し、バックアップの信頼性を担保する。

**機能の利用シーン**：
- 定期的なバックアップ検証ジョブの実行
- 災害復旧テストの一環としてのバックアップリストア確認
- 新規サーバー構築後のバックアップ/リストア動作確認
- 特定データベースのバックアップ問題調査

**主要な処理内容**：
1. 対象データベースの最新フルバックアップ履歴を取得
2. バックアップファイルを指定先(または同一インスタンス)にテスト用名称でリストア
3. リストア完了後にDBCC CHECKDBを実行し整合性を検証
4. テストデータベースを自動的に削除してクリーンアップ

**関連システム・外部連携**：
- Azure Blob Storage、S3互換ストレージへのバックアップファイルアクセス(StorageCredentialパラメータ使用)
- 別サーバーへのリストアテスト(Destinationパラメータ使用)

**権限による制御**：
- バックアップ履歴取得にはmsdb読み取り権限が必要
- リストア操作にはsysadminまたはdbcreator権限が必要
- DBCC CHECKDBにはdb_owner権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主画面 | PowerShellコマンドラインからの直接実行 |

## 機能種別

バリデーション / 災害復旧テスト

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | ソースSQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | ソース接続用認証情報 | - |
| Database | object[] | No | 対象データベース名(ワイルドカード対応) | - |
| ExcludeDatabase | object[] | No | 除外データベース名 | - |
| Destination | DbaInstanceParameter | No | リストア先インスタンス(省略時はソースと同一) | - |
| DestinationSqlCredential | object | No | リストア先接続用認証情報 | - |
| DataDirectory | string | No | データファイル配置ディレクトリ | SQL Serverからアクセス可能なパス |
| LogDirectory | string | No | ログファイル配置ディレクトリ | SQL Serverからアクセス可能なパス |
| FileStreamDirectory | string | No | FileStreamデータ配置ディレクトリ | - |
| Prefix | string | No | テストDB名接頭辞(デフォルト: "dbatools-testrestore-") | - |
| VerifyOnly | switch | No | RESTORE VERIFYONLYのみ実行 | - |
| NoCheck | switch | No | DBCC CHECKDBをスキップ | - |
| NoDrop | switch | No | テストDB削除をスキップ | - |
| CopyFile | switch | No | バックアップファイルをコピー | - |
| CopyPath | string | No | バックアップファイルコピー先 | - |
| MaxSize | int | No | 最大データベースサイズ(MB) | 0以上の整数 |
| MaxDop | int | No | DBCC CHECKDB並列度 | 1以上の整数 |
| DeviceType | string[] | No | バックアップデバイスタイプフィルタ | Disk/Tape/Virtual Device |
| StorageCredential | string | No | クラウドストレージ認証情報名 | - |
| IncludeCopyOnly | switch | No | コピーオンリーバックアップを含む | - |
| IgnoreLogBackup | switch | No | ログバックアップをスキップ | - |
| IgnoreDiffBackup | switch | No | 差分バックアップをスキップ | - |
| InputObject | Database[] | No | パイプライン入力用データベースオブジェクト | - |
| MaxTransferSize | int | No | リストア転送サイズ | 64KBの倍数、最大4GB |
| BufferCount | int | No | I/Oバッファ数 | 1以上の整数 |
| ReuseSourceFolderStructure | switch | No | ソースフォルダ構造を維持 | - |
| Checksum | switch | No | チェックサム検証を強制 | - |
| Wait | int | No | データベース間待機秒数 | 0以上の整数 |
| EnableException | switch | No | 例外をスローする | - |

### 入力データソース

- Get-DbaDbBackupHistory: バックアップ履歴の取得
- Get-DbaDatabase: パイプライン入力時のデータベースオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SourceServer | string | ソースSQL Serverインスタンス名 |
| TestServer | string | テストリストア先インスタンス名 |
| Database | string | データベース名 |
| FileExists | boolean | バックアップファイル存在確認結果 |
| Size | dbasize | バックアップファイル合計サイズ |
| RestoreResult | string | リストア結果(Success/Failure/Skipped/エラーメッセージ) |
| DbccResult | string | DBCC CHECKDB結果(Success/Failure/Skipped/詳細エラー) |
| RestoreStart | datetime | リストア開始日時 |
| RestoreEnd | datetime | リストア終了日時 |
| RestoreElapsed | string | リストア所要時間(HH:mm:ss形式) |
| DbccMaxDop | int | DBCC CHECKDB並列度 |
| DbccStart | datetime | DBCC開始日時 |
| DbccEnd | datetime | DBCC終了日時 |
| DbccElapsed | string | DBCC所要時間(HH:mm:ss形式) |
| BackupDates | datetime[] | バックアップ開始日時配列 |
| BackupFiles | string[] | バックアップファイルパス配列 |

### 出力先

PowerShellパイプライン(即座に出力)

## 処理フロー

### 処理シーケンス

```
1. データベースオブジェクト取得
   └─ SqlInstance指定時はGet-DbaDatabase実行、InputObject指定時はそのまま使用

2. 各データベースに対してループ処理
   └─ tempdbはスキップ

3. バックアップ履歴確認
   └─ LastFullBackup.Year == 1 の場合はバックアップなしとしてスキップ

4. 宛先サーバー接続・検証
   └─ バージョン互換性チェック(宛先 >= ソース)

5. バックアップ履歴取得
   └─ Get-DbaDbBackupHistory で最新バックアップチェーン取得

6. サイズ確認
   └─ MaxSize超過時はスキップ

7. バックアップファイルコピー(CopyFile指定時)
   └─ ソースからコピー先へファイル転送

8. バックアップファイル存在確認
   └─ Test-DbaPath でアクセス可否確認

9. リストア実行
   └─ Restore-DbaDatabase でテスト名称にリストア

10. DBCC CHECKDB実行(NoCheck未指定時)
    └─ Start-DbccCheck でデータベース整合性確認

11. テストDB削除(NoDrop未指定時)
    └─ Remove-DbaDatabase でクリーンアップ

12. コピーファイル削除(CopyFile使用時)
    └─ コピーしたバックアップファイルを削除

13. 結果出力
    └─ PSCustomObjectとして即座にパイプラインへ出力

14. 待機(Wait指定時)
    └─ 次のデータベース処理前に指定秒数待機
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaDatabase]
    B -->|No| D[InputObjectを使用]
    C --> E[データベースループ開始]
    D --> E
    E --> F{tempdb?}
    F -->|Yes| E
    F -->|No| G{バックアップ履歴あり?}
    G -->|No| H[Skipped出力]
    H --> E
    G -->|Yes| I[宛先サーバー接続]
    I --> J{バージョン互換?}
    J -->|No| K[エラー: 非互換]
    K --> E
    J -->|Yes| L[バックアップ履歴取得]
    L --> M{MaxSize超過?}
    M -->|Yes| N[サイズ超過出力]
    N --> E
    M -->|No| O{CopyFile?}
    O -->|Yes| P[ファイルコピー]
    P --> Q{ファイル存在?}
    O -->|No| Q
    Q -->|No| R[Skipped出力]
    R --> E
    Q -->|Yes| S[リストア実行]
    S --> T{VerifyOnly?}
    T -->|Yes| U[結果出力]
    T -->|No| V{NoCheck?}
    V -->|Yes| W[テストDB削除]
    V -->|No| X[DBCC CHECKDB実行]
    X --> W
    W --> U
    U --> Y{Wait指定?}
    Y -->|Yes| Z[待機]
    Z --> E
    Y -->|No| E
    E --> AA{全DB処理完了?}
    AA -->|No| E
    AA -->|Yes| AB[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | tempdb除外 | tempdbデータベースは処理対象外 | 常時 |
| BR-02 | バージョン互換性 | 宛先サーバーはソースと同じかそれ以上のバージョン | Destination指定時 |
| BR-03 | クラウドストレージコピー不可 | StorageCredential使用時はCopyFile無効 | 両パラメータ指定時 |
| BR-04 | masterのDBCC制限 | masterデータベースはDBCC CHECKDBスキップ | 対象DBがmaster |
| BR-05 | UNCパス要件 | 異なるサーバー間ではUNCパスまたはCopyFileが必要 | ソース != 宛先 |

### 計算ロジック

- RestoreElapsed: RestoreEnd - RestoreStart をHH:mm:ss形式にフォーマット
- DbccElapsed: DbccEnd - DbccStart をHH:mm:ss形式にフォーマット
- Size: lastbackup.TotalSizeの合計値をdbасizeオブジェクトに変換

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| バックアップ履歴取得 | msdb..backupset等 | SELECT | 最新バックアップ情報取得 |
| リストア | 宛先データベース | CREATE/RESTORE | テストデータベース作成 |
| DBCC CHECKDB | テストデータベース | SELECT(内部) | データベース整合性検証 |
| 削除 | テストデータベース | DROP | テストデータベース削除 |

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

#### msdb..backupset

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | backup_set_id, database_name等 | Get-DbaDbBackupHistoryで使用 | 間接的な参照 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | 宛先サーバーに接続できない | Stop-Functionで処理継続 |
| VersionMismatch | バージョン不整合 | 宛先がソースより低いバージョン | Stop-Functionでスキップ |
| PathAccessDenied | パスアクセス拒否 | DataDirectory/LogDirectory未アクセス可 | Stop-Functionでスキップ |
| RestoreFailure | リストア失敗 | リストア操作エラー | エラーメッセージを結果に含める |
| DbccFailure | DBCC失敗 | DBCC CHECKDB実行エラー | エラー詳細を結果に含める |

### リトライ仕様

特になし。各データベースは独立して処理され、失敗時は次のデータベースへ継続する。

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

各リストア操作はSQL Serverのリストアトランザクションとして実行。DBCC CHECKDBは読み取り専用。

## パフォーマンス要件

- MaxDopパラメータでDBCC CHECKDBの並列度を制御可能
- MaxTransferSize/BufferCountでリストアI/O性能を調整可能
- Waitパラメータで連続リストア時のI/O負荷を軽減可能

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

- SqlCredential/DestinationSqlCredentialによる認証情報の安全な受け渡し
- StorageCredentialはSQL Server内に事前登録された資格情報名を指定
- テストデータベースは処理後に自動削除(NoDrop未指定時)

## 備考

- SQL Server 2022以降でS3互換ストレージをサポート
- VerifyOnlyモードはDBCC CHECKDBをスキップし高速検証が可能
- Checksumスイッチでバックアップファイルのチェックサム検証を強制可能

---

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

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

### 推奨読解順序

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

まず、出力されるPSCustomObjectの構造と各プロパティの意味を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaLastBackup.ps1 | `public/Test-DbaLastBackup.ps1` | 672-689行目の出力オブジェクト定義を確認 |

**読解のコツ**: PowerShellのPSCustomObjectは動的にプロパティを定義できる。@{}記法でハッシュテーブルを作成し、型キャスト[PSCustomObject]でオブジェクト化している。

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

処理の起点となるパラメータ定義と処理開始部分を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaLastBackup.ps1 | `public/Test-DbaLastBackup.ps1` | 281-313行目のパラメータ定義、314-316行目のInputObject構築 |

**主要処理フロー**:
1. **314-317行目**: SqlInstance指定時にGet-DbaDatabase呼び出し
2. **319-322行目**: 各データベースのループ開始、tempdbスキップ
3. **336-356行目**: バックアップ履歴がない場合の早期リターン

#### Step 3: バックアップ履歴取得処理を理解する

Get-DbaDbBackupHistoryの呼び出しと結果処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaLastBackup.ps1 | `public/Test-DbaLastBackup.ps1` | 418-430行目のバックアップ履歴取得ロジック |

**主要処理フロー**:
- **418-427行目**: IgnoreLogBackup時は-LastFullと-LastDiffで個別取得
- **429行目**: 通常時は-Lastで全バックアップチェーン取得

#### Step 4: リストア処理を理解する

Restore-DbaDatabase呼び出しとパラメータ構築を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaLastBackup.ps1 | `public/Test-DbaLastBackup.ps1` | 541-585行目のリストア実行部分 |

**主要処理フロー**:
- **542-565行目**: ReuseSourceFolderStructureの有無でスプラットを切り替え
- **580-584行目**: VerifyOnlyの場合とフルリストアで分岐

#### Step 5: DBCC CHECKDB処理を理解する

整合性チェック実行と結果処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Test-DbaLastBackup.ps1 | `public/Test-DbaLastBackup.ps1` | 608-630行目のDBCC CHECKDB実行 |

**主要処理フロー**:
- **610-614行目**: masterデータベースはDBCC CHECKDBスキップ
- **619-625行目**: Start-DbccCheck呼び出しと経過時間計算

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

```
Test-DbaLastBackup
    │
    ├─ Connect-DbaInstance (宛先接続)
    │
    ├─ Get-DbaDatabase (DB一覧取得、SqlInstance指定時)
    │
    ├─ Get-DbaDbBackupHistory (バックアップ履歴取得)
    │      └─ msdb..backupset等をクエリ
    │
    ├─ Test-DbaPath (パスアクセス確認)
    │
    ├─ Get-SqlDefaultPaths (デフォルトディレクトリ取得)
    │
    ├─ Restore-DbaDatabase (テストリストア実行)
    │      └─ RESTORE DATABASE コマンド発行
    │
    ├─ Start-DbccCheck (整合性チェック)
    │      └─ DBCC CHECKDB コマンド発行
    │
    └─ Remove-DbaDatabase (テストDB削除)
           └─ DROP DATABASE コマンド発行
```

### データフロー図

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

SqlInstance/Database  ──────▶ Get-DbaDatabase ──────────────────▶
                                    │
                                    ▼
                              Get-DbaDbBackupHistory
                                    │
                                    ▼
                              バックアップファイル
                              存在確認
                                    │
                                    ▼
                              Restore-DbaDatabase ────────────────▶
                                    │
                                    ▼
                              Start-DbccCheck ────────────────────▶
                                    │
                                    ▼
                              Remove-DbaDatabase
                                    │
                                    ▼
                              PSCustomObject ──────────────────────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaLastBackup.ps1 | `public/Test-DbaLastBackup.ps1` | ソース | メイン機能実装 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得 |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | データベースリストア |
| Remove-DbaDatabase.ps1 | `public/Remove-DbaDatabase.ps1` | ソース | データベース削除 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パスアクセス確認 |
| Start-DbccCheck.ps1 | `private/Start-DbccCheck.ps1` | ソース | DBCC CHECKDB実行 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
