# 画面設計書 23-バックアップテスト

## 概要

本ドキュメントは、dbatoolsモジュールの「バックアップテスト」機能群に関する画面設計書です。SQL Serverバックアップの整合性検証を自動化し、バックアップが実際にリストア可能かどうかを確認するためのコマンド群を提供します。

### 本画面の処理概要

**業務上の目的・背景**：
バックアップは障害復旧の要ですが、バックアップファイルが破損していたり、リストアに必要な証明書が不足していたりすると、いざという時に復旧できません。本機能群は、バックアップの整合性を定期的にテストし、問題を事前に検出することで、障害復旧の確実性を高めます。Test-DbaLastBackupはバックアップのリストアとDBCC CHECKDBを自動実行し、バックアップの品質を包括的に検証します。Test-DbaBackupEncryptedはバックアップファイルの暗号化状態を確認し、セキュリティ監査やリストア準備に役立ちます。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドレットを直接呼び出します：
- `Test-DbaLastBackup` - 最終バックアップのテスト
- `Test-DbaBackupEncrypted` - バックアップ暗号化状態の確認

**主要な操作・処理内容**：
1. 最終バックアップの取得とテストリストアの実行（Test-DbaLastBackup）
2. DBCC CHECKDBによるデータベース整合性検証（Test-DbaLastBackup）
3. テストデータベースの自動削除（Test-DbaLastBackup）
4. バックアップファイルの暗号化状態確認（Test-DbaBackupEncrypted）

**画面遷移**：
- 入力: SQLインスタンス接続、データベース名、バックアップファイルパス
- 出力: テスト結果オブジェクト（リストア成功/失敗、DBCC結果、暗号化情報）

**権限による表示制御**：
- SQL Serverインスタンスへのsysadmin権限が必要（リストア操作のため）
- リストア先ディレクトリへの書き込み権限が必要
- バックアップファイルへの読み取り権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 51 | Test-DbaLastBackup | 主機能 | 最終バックアップのテスト |
| 49 | Test-DbaBackupEncrypted | 補助機能 | バックアップ暗号化状態の確認 |

## 画面種別

コマンドラインインターフェース（CLI）- パイプライン処理対応

## URL/ルーティング

PowerShellコマンドレット形式:
- `Test-DbaLastBackup`
- `Test-DbaBackupEncrypted`

## 入出力項目

### Test-DbaLastBackup

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | ソースSQLインスタンス |
| SqlCredential | PSCredential | No | ソースへの認証情報 |
| Database | object[] | No | テスト対象データベース名 |
| ExcludeDatabase | object[] | No | 除外データベース名 |
| Destination | DbaInstanceParameter | No | テストリストア先インスタンス |
| DestinationSqlCredential | object | No | リストア先への認証情報 |
| DataDirectory | string | No | データファイル配置先 |
| LogDirectory | string | No | ログファイル配置先 |
| 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） |
| MaxDop | int | No | DBCC CHECKDBのMaxDOP |
| DeviceType | string[] | No | デバイスタイプフィルタ |
| StorageCredential | string | No | クラウドストレージ認証情報名 |
| IncludeCopyOnly | Switch | No | コピーオンリーバックアップを含める |
| IgnoreLogBackup | Switch | No | ログバックアップを無視 |
| IgnoreDiffBackup | Switch | No | 差分バックアップを無視 |
| MaxTransferSize | int | No | リストア時の転送サイズ |
| BufferCount | int | No | リストア時のバッファ数 |
| ReuseSourceFolderStructure | Switch | No | 元のフォルダ構造を維持 |
| Checksum | Switch | No | チェックサム検証を有効化 |
| Wait | int | No | データベース間の待機秒数 |
| InputObject | Database[] | No | パイプライン入力用DBオブジェクト |

### Test-DbaBackupEncrypted

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | No | バックアップヘッダー読み取り用インスタンス |
| SqlCredential | PSCredential | No | 認証情報 |
| FilePath | string[] | Yes | 検査対象のバックアップファイルパス |

## 表示項目

### Test-DbaLastBackup 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| SourceServer | string | ソースSQLサーバー名 |
| TestServer | string | テスト先SQLサーバー名 |
| Database | string | データベース名 |
| FileExists | bool | バックアップファイルが存在するか |
| Size | dbasize | バックアップサイズ |
| RestoreResult | string | リストア結果（Success/Failure/Skipped） |
| DbccResult | string | DBCC CHECKDB結果 |
| RestoreStart | datetime | リストア開始時刻 |
| RestoreEnd | datetime | リストア終了時刻 |
| RestoreElapsed | string | リストア所要時間（HH:mm:ss） |
| DbccMaxDop | int | DBCC CHECKDBのMaxDOP |
| DbccStart | datetime | DBCC開始時刻 |
| DbccEnd | datetime | DBCC終了時刻 |
| DbccElapsed | string | DBCC所要時間（HH:mm:ss） |
| BackupDates | datetime[] | バックアップ日時の配列 |
| BackupFiles | string[] | バックアップファイルパスの配列 |

### Test-DbaBackupEncrypted 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| FilePath | string | バックアップファイルパス |
| BackupName | string | バックアップセット名 |
| Encrypted | bool | 暗号化されているか |
| KeyAlgorithm | string | 暗号化キーアルゴリズム |
| EncryptorThumbprint | string | 暗号化証明書のサムプリント |
| EncryptorType | string | 暗号化タイプ |
| TDEThumbprint | string | TDE証明書のサムプリント |
| Compressed | bool | 圧縮されているか |

## イベント仕様

### 1-バックアップテスト（Test-DbaLastBackup）

1. ソースインスタンスからデータベース情報取得
2. 最終バックアップが存在しない場合はSkippedを返す
3. 宛先インスタンスへの接続とバージョン互換性確認
4. 最終バックアップ履歴の取得（Get-DbaDbBackupHistory）
5. バックアップサイズのMaxSize確認
6. CopyFile指定時はバックアップファイルをコピー
7. リストア実行（Restore-DbaDatabase）または検証のみ（VerifyOnly）
8. DBCC CHECKDB実行（NoCheck未指定時）
9. テストデータベースの削除（NoDrop未指定時）
10. コピーしたバックアップファイルの削除
11. 結果オブジェクトの出力

### 2-バックアップ暗号化確認（Test-DbaBackupEncrypted）

1. SQLインスタンスへの接続
2. RESTORE HEADERONLYによるヘッダー情報取得
3. 暗号化情報（KeyAlgorithm、EncryptorThumbprint、EncryptorType）の確認
4. RESTORE FILELISTONLYによるTDE情報取得
5. TDEThumbprintの確認
6. 結果オブジェクトの出力

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Test-DbaLastBackup | N/A | CREATE DATABASE | テストデータベースの作成（リストア） |
| Test-DbaLastBackup | N/A | DROP DATABASE | テストデータベースの削除 |
| Test-DbaLastBackup | N/A | DBCC CHECKDB | 整合性チェック（読み取りのみ） |
| Test-DbaBackupEncrypted | N/A | RESTORE HEADERONLY | ヘッダー情報読み取り |
| Test-DbaBackupEncrypted | N/A | RESTORE FILELISTONLY | ファイルリスト情報読み取り |

### テーブル別更新項目詳細

Test-DbaLastBackupはテストデータベースを一時的に作成・削除しますが、既存のデータベースやテーブルは変更しません。

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|-----|---------|------|
| Warning | "$Destination is a lower version than $instance" | リストア先バージョンが低い場合 |
| Warning | "$destserver cannot access $CopyPath" | コピーパスにアクセスできない場合 |
| Warning | "Can't access $datadirectory" | データディレクトリにアクセスできない場合 |
| Warning | "Cannot use CopyFile with cloud storage backups" | クラウドバックアップでCopyFile使用時 |
| Warning | "Failed to Drop database" | テストDB削除失敗時 |
| Verbose | "Getting recent backup history" | バックアップ履歴取得開始 |
| Verbose | "Performing restore" | リストア実行開始 |
| Verbose | "Starting DBCC" | DBCC開始 |
| Verbose | "Dropping database" | テストDB削除開始 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQLインスタンス接続失敗 | Stop-Functionでエラー出力、処理継続 |
| バックアップなし | Skippedとして結果出力 |
| バージョン非互換 | Stop-Functionで警告、スキップ |
| バックアップサイズ超過 | サイズ超過メッセージと共に結果出力 |
| リストア失敗 | エラーメッセージをRestoreResultに設定 |
| DBCC失敗 | エラーメッセージをDbccResultに設定 |
| ファイルコピー失敗 | 警告出力、元パスでリストア試行 |

## 備考

- VerifyOnlyオプションは実際のリストアを行わず、RESTORE VERIFYONLYでバックアップの整合性のみを確認します
- masterデータベースのDBCC CHECKDBはスキップされます（リストア後のmasterは正常なチェックが不可能なため）
- Prefixのデフォルト値は "dbatools-testrestore-" で、テストDBは "dbatools-testrestore-{元DB名}" という名前で作成されます
- Waitパラメータはネットワークストレージへのリストア時のI/Oエラー回避に有用です
- S3互換ストレージからのテストはSQL Server 2022以降で対応（StorageCredential使用）
- Checksumパラメータ使用時、バックアップにチェックサムが含まれていないとエラーになります

---

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

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

### 推奨読解順序

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

テスト結果はPSCustomObjectとして出力されます。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaLastBackup.ps1 | `public/Test-DbaLastBackup.ps1` | 行672-690の結果オブジェクト構造を理解 |

**読解のコツ**: 結果オブジェクトのプロパティと、各処理ステップでどのように値が設定されるかを追跡してください。

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

Test-DbaLastBackupが主要なエントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaLastBackup.ps1 | `public/Test-DbaLastBackup.ps1` | パラメータ定義、処理フロー全体 |

**主要処理フロー**:
1. **行314-317**: InputObject取得（Get-DbaDatabase使用）
2. **行319-356**: データベースループ開始、バックアップなしチェック
3. **行358-391**: 宛先接続とバージョン確認
4. **行416-430**: 最終バックアップ履歴取得
5. **行432-459**: サイズ確認とSkipped判定
6. **行461-501**: CopyFile処理
7. **行538-604**: リストア実行（Restore-DbaDatabase呼び出し）
8. **行608-629**: DBCC CHECKDB実行
9. **行636-652**: テストDB削除
10. **行671-690**: 結果オブジェクト出力

#### Step 3: バックアップ暗号化確認処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaBackupEncrypted.ps1 | `public/Test-DbaBackupEncrypted.ps1` | 暗号化検出ロジック |

**主要処理フロー**:
- **行78-84**: SQLインスタンス接続
- **行87-97**: RESTORE HEADERONLY実行
- **行99-105**: 暗号化情報チェック（KeyAlgorithm、EncryptorThumbprint、EncryptorType）
- **行107-124**: RESTORE FILELISTONLY実行、TDEThumbprint取得
- **行127-139**: 結果オブジェクト出力

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

```
Test-DbaLastBackup
    |
    +-- Get-DbaDatabase (InputObject取得)
    |
    +-- Connect-DbaInstance (宛先接続)
    |
    +-- Get-DbaDbBackupHistory (最終バックアップ取得)
    |       +-- Get-DbaDbBackupHistory -LastFull
    |       +-- Get-DbaDbBackupHistory -LastDiff
    |       +-- Get-DbaDbBackupHistory -Last
    |
    +-- Test-DbaPath (パスアクセス確認)
    |
    +-- Copy-Item (CopyFile時)
    |
    +-- Restore-DbaDatabase (リストア実行)
    |
    +-- Start-DbccCheck (DBCC CHECKDB)
    |
    +-- Remove-DbaDatabase (テストDB削除)

Test-DbaBackupEncrypted
    |
    +-- Connect-DbaInstance (接続)
    |
    +-- $server.Query("RESTORE HEADERONLY")
    |
    +-- $server.Query("RESTORE FILELISTONLY")
    |
    +-- Convert-ByteToHexString (TDEThumbprint変換)
```

### データフロー図

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

SQLインスタンス
Database名
      |
      v
+-------------------+
| Test-DbaLastBackup|
+-------------------+
      |
      +-- バックアップ履歴取得
      |
      +-- (オプション) ファイルコピー
      |
      +-- Restore-DbaDatabase -----> テストDB作成
      |
      +-- DBCC CHECKDB ------------> 整合性確認
      |
      +-- Remove-DbaDatabase ------> テストDB削除
      |
      v
テスト結果オブジェクト
  - RestoreResult
  - DbccResult
  - 所要時間

バックアップファイルパス
      |
      v
+----------------------+
| Test-DbaBackup       |
| Encrypted            |
+----------------------+
      |
      +-- RESTORE HEADERONLY
      +-- RESTORE FILELISTONLY
      |
      v
暗号化情報オブジェクト
  - Encrypted (bool)
  - KeyAlgorithm
  - EncryptorThumbprint
  - TDEThumbprint
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaLastBackup.ps1 | `public/Test-DbaLastBackup.ps1` | ソース | バックアップテストの主機能 |
| Test-DbaBackupEncrypted.ps1 | `public/Test-DbaBackupEncrypted.ps1` | ソース | 暗号化状態確認 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得 |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | リストア実行 |
| Remove-DbaDatabase.ps1 | `public/Remove-DbaDatabase.ps1` | ソース | テストDB削除 |
| Start-DbccCheck.ps1 | `private/functions/Start-DbccCheck.ps1` | ソース | DBCC CHECKDB実行 |
| Convert-ByteToHexString.ps1 | `private/functions/Convert-ByteToHexString.ps1` | ソース | バイト配列から16進文字列変換 |
