# 画面設計書 21-バックアップ情報

## 概要

本ドキュメントは、dbatoolsモジュールの「バックアップ情報」機能群に関する画面設計書です。SQL Serverバックアップファイルのヘッダー情報を読み取り、リストア操作に必要なバックアップ履歴オブジェクトを作成・編集・検証するためのコマンド群を提供します。

### 本画面の処理概要

**業務上の目的・背景**：
データベースのリストア操作を計画する際、バックアップファイルの詳細情報（バックアップチェーン、LSN、ファイルパス等）を手動で追跡することは非常に煩雑です。本機能群は、バックアップファイルのヘッダー情報を自動的に読み取り、Restore-DbaDatabase コマンドと互換性のあるBackupHistoryオブジェクトを生成することで、リストア計画を大幅に簡素化します。また、異なるサーバーへのリストア、データベース名の変更、ファイルパスの変更などの複雑なリストアシナリオにも対応できます。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドレットを直接呼び出します：
- `Get-DbaBackupInformation` - バックアップ情報の取得
- `Format-DbaBackupInformation` - バックアップ情報のフォーマット
- `Select-DbaBackupInformation` - バックアップ情報のフィルタリング
- `Test-DbaBackupInformation` - バックアップ情報の検証

**主要な操作・処理内容**：
1. バックアップファイルのスキャンとヘッダー情報の読み取り（Get-DbaBackupInformation）
2. リストア先に応じたパス・名前の変換（Format-DbaBackupInformation）
3. ポイントインタイムリカバリに必要なバックアップチェーンの選択（Select-DbaBackupInformation）
4. リストア前のバックアップ情報検証（Test-DbaBackupInformation）

**画面遷移**：
- 入力: バックアップファイルパス、SQLインスタンス接続
- 出力: BackupHistoryオブジェクト（Restore-DbaDatabase へパイプライン入力可能）

**権限による表示制御**：
- SQL Serverインスタンスへの接続権限が必要
- バックアップファイルへのアクセスには、SQL Serverサービスアカウントの読み取り権限が必要
- xp_dirtree使用時はSQL Serverサービスアカウントのディレクトリアクセス権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | Get-DbaBackupInformation | 主機能 | バックアップ情報の取得 |
| 33 | Format-DbaBackupInformation | 補助機能 | バックアップ履歴メタデータの変更 |
| 48 | Select-DbaBackupInformation | 補助機能 | バックアップ履歴のフィルタリング |
| 50 | Test-DbaBackupInformation | 補助機能 | バックアップ情報の検証 |

## 画面種別

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

## URL/ルーティング

PowerShellコマンドレット形式:
- `Get-DbaBackupInformation`
- `Format-DbaBackupInformation`
- `Select-DbaBackupInformation`
- `Test-DbaBackupInformation`

## 入出力項目

### Get-DbaBackupInformation

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Path | object[] | Yes | バックアップファイルのパスまたはFileInfoオブジェクト |
| SqlInstance | DbaInstanceParameter | Yes(Create) | バックアップヘッダーを読み取るSQLインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| DatabaseName | string[] | No | フィルタリング対象のデータベース名 |
| SourceInstance | string[] | No | 元のインスタンス名でフィルタリング |
| NoXpDirTree | Switch | No | xp_dirtreeを使用しない |
| DirectoryRecurse | Switch | No | ディレクトリを再帰的にスキャン |
| MaintenanceSolution | Switch | No | Ola Hallengrenバックアップフォルダ構造対応 |
| IgnoreLogBackup | Switch | No | ログバックアップを無視 |
| IgnoreDiffBackup | Switch | No | 差分バックアップを無視 |
| StorageCredential | string | No | クラウドストレージ認証情報名 |
| Import | Switch | No | エクスポートされたBackupHistoryをインポート |
| ExportPath | string | No | CliXml形式でエクスポートするパス |
| Anonymise | Switch | No | 出力を匿名化 |

### Format-DbaBackupInformation

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| BackupHistory | object[] | Yes | Select-DbaBackupInformationからのバックアップ履歴 |
| ReplaceDatabaseName | object | No | データベース名の置換（文字列またはハッシュテーブル） |
| DataFileDirectory | string | No | データファイルの配置先ディレクトリ |
| LogFileDirectory | string | No | ログファイルの配置先ディレクトリ |
| DestinationFileStreamDirectory | string | No | FileStreamファイルの配置先 |
| DatabaseNamePrefix | string | No | データベース名のプレフィックス |
| DatabaseFilePrefix | string | No | ファイル名のプレフィックス |
| DatabaseFileSuffix | string | No | ファイル名のサフィックス |
| RebaseBackupFolder | string | No | バックアップファイル検索パスの変更 |
| ReplaceDbNameInFile | Switch | No | ファイル名内のDB名も置換 |
| FileMapping | hashtable | No | 論理名から物理パスへのカスタムマッピング |

### Select-DbaBackupInformation

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| 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 | 中断されたリストアの継続情報 |
| LastRestoreType | object | No | 最後のリストア操作情報 |

### Test-DbaBackupInformation

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| BackupHistory | object[] | Yes | 検証対象のバックアップ履歴 |
| SqlInstance | DbaInstanceParameter | Yes | リストア先SQLインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| WithReplace | Switch | No | 既存データベースの上書きを許可 |
| Continue | Switch | No | 既存のリストア操作の継続 |
| VerifyOnly | Switch | No | ファイルアクセス確認のみ |
| OutputScriptOnly | Switch | No | ディレクトリ作成をスキップ |

## 表示項目

### BackupHistory オブジェクト出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | バックアップ元のコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| Database | string | データベース名 |
| UserName | string | バックアップ実行ユーザー |
| Start | DateTime | バックアップ開始時刻 |
| End | DateTime | バックアップ終了時刻 |
| Duration | TimeSpan | バックアップ所要時間 |
| Type | string | バックアップ種別（Full/Differential/Log） |
| Path | string[] | バックアップファイルパス |
| FileList | object[] | ファイル詳細（Type, LogicalName, PhysicalName, Size） |
| TotalSize | long | バックアップの合計サイズ（バイト） |
| CompressedBackupSize | long | 圧縮後のサイズ（バイト） |
| BackupSetId | Guid | バックアップセットの一意識別子 |
| FirstLsn | BigInt | 最初のLSN |
| LastLsn | BigInt | 最後のLSN |
| DatabaseBackupLsn | BigInt | データベースバックアップLSN |
| CheckpointLSN | BigInt | チェックポイントLSN |
| SoftwareVersionMajor | int | バックアップを作成したSQL Serverのメジャーバージョン |
| RecoveryModel | string | リカバリモデル |
| IsCopyOnly | bool | コピーオンリーバックアップかどうか |
| IsVerified | bool | 検証済みかどうか（Test-DbaBackupInformationで設定） |

## イベント仕様

### 1-バックアップ情報取得（Get-DbaBackupInformation）

1. パスの解析とファイルリストの構築
2. xp_dirtreeまたはGet-ChildItemによるファイル検出
3. Read-DbaBackupHeaderによるヘッダー情報読み取り
4. BackupSetGUIDでグループ化してBackupHistoryオブジェクト生成
5. フィルタリング（DatabaseName、SourceInstance）適用
6. 匿名化処理（Anonymise指定時）
7. エクスポート（ExportPath指定時）

### 2-バックアップ情報フォーマット（Format-DbaBackupInformation）

1. 元のデータベース名、ファイルリスト、フルネームを保存
2. バックアップタイプ名の正規化（Full→Database、Differential→Database Differential等）
3. データベース名の置換処理
4. ファイルパスの変換処理（DataFileDirectory、LogFileDirectory等）
5. バックアップフォルダのリベース処理

### 3-バックアップ選択（Select-DbaBackupInformation）

1. RestoreTimeプロパティの追加
2. サーバー名・データベース名によるフィルタリング
3. フルバックアップの特定（最新のCheckpointLSN基準）
4. 差分バックアップの特定（DatabaseBackupLSN一致確認）
5. トランザクションログの選択（LSNチェーン構築）
6. 最小限のバックアップチェーン出力

### 4-バックアップ情報検証（Test-DbaBackupInformation）

1. SQLインスタンスへの接続
2. 既存データベースファイルの取得
3. 各データベースについて:
   - 複数ソースデータベースからのリストア検出
   - 既存データベース存在確認（WithReplace/Continue考慮）
   - ファイルパス競合確認
   - 必要ディレクトリの作成
   - LSNチェーン整合性検証
4. バックアップファイルアクセス確認
5. IsVerifiedフラグの設定

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaBackupInformation | N/A | SELECT | バックアップヘッダー読み取りのみ |
| Format-DbaBackupInformation | N/A | なし | メモリ内オブジェクト変換のみ |
| Select-DbaBackupInformation | N/A | なし | メモリ内フィルタリングのみ |
| Test-DbaBackupInformation | sys.database_files | SELECT | ファイル情報の読み取り |
| Test-DbaBackupInformation | N/A | CREATE DIRECTORY | 必要なディレクトリ作成 |

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

本機能群はデータベースの更新を行わず、バックアップファイルの読み取りとメモリ内のオブジェクト操作のみを行います。

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|-----|---------|------|
| Warning | "IgnoreLogBackup can only by used with MaintenanceSolution. Will not be used" | IgnoreLogBackupをMaintenanceSolutionなしで使用 |
| Warning | "$f does not exist or is unreadable" | インポート時にファイルが見つからない |
| Warning | "Trying to restore $Database from multiple sources databases" | 複数ソースからのリストア検出 |
| Warning | "Database $Database exists, so WithReplace must be specified" | 既存DBにWithReplaceなしでリストア |
| Warning | "File $path already exists on $SqlInstance and owned by another database" | ファイルパス競合 |
| Warning | "Backup File cannot be read by instance" | バックアップファイルアクセス不可 |
| Verbose | "Reading backup headers of $count files" | ヘッダー読み取り開始 |
| Verbose | "Marking $Database as verified" | 検証成功 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQLインスタンス接続失敗 | Stop-Functionでエラー出力、処理継続 |
| バックアップファイルアクセス不可 | 警告出力、検証エラーカウント増加 |
| LSNチェーン不整合 | 検証エラーとしてカウント、IsVerified=False |
| ディレクトリ作成失敗 | 警告出力、検証エラーカウント増加 |
| エクスポートパス存在（NoClobber時） | Stop-Functionで処理停止 |

## 備考

- Ola Hallengren Maintenance Solutionのフォルダ構造（FULL/DIFF/LOG）に最適化されたスキャンモードを提供
- Azure Blob StorageおよびS3互換ストレージからのバックアップ読み取りをサポート（SQL Server 2022以降）
- エクスポート機能により、バックアップ履歴を別マシンに転送してリストア計画に使用可能
- Anonymise機能は、dbatoolsチームへの障害報告時にセンシティブ情報を隠蔽するために使用

---

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

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

### 推奨読解順序

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

バックアップ情報機能の中心となるデータ構造はBackupHistoryオブジェクトです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | BackupHistory.cs | `bin/projects/dbatools/dbatools/Database/BackupHistory.cs` | BackupHistoryクラスの構造、プロパティ定義を理解 |

**読解のコツ**: BackupHistoryオブジェクトはRestore-DbaDatabase と互換性があり、パイプラインで直接渡せる設計になっています。

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

Get-DbaBackupInformationが主要なエントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaBackupInformation.ps1 | `public/Get-DbaBackupInformation.ps1` | パラメータセット、処理フロー全体を理解 |

**主要処理フロー**:
1. **行211-221**: Get-HashString関数（匿名化用）
2. **行225-240**: 初期化処理、SQLインスタンス接続
3. **行246-261**: Import処理（既存エクスポートファイル読み込み）
4. **行262-335**: パススキャンとファイルリスト構築
5. **行347-354**: Read-DbaBackupHeaderによるヘッダー読み取り
6. **行356-405**: BackupHistoryオブジェクト生成
7. **行414-427**: Anonymise処理

#### Step 3: バックアップ情報フォーマット処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Format-DbaBackupInformation.ps1 | `public/Format-DbaBackupInformation.ps1` | リストア先変更のためのメタデータ変換ロジック |

**主要処理フロー**:
- **行159-184**: パラメータの正規化（末尾セパレータ除去）
- **行190-208**: 元データの保存とタイプ名正規化
- **行211-219**: データベース名置換処理
- **行222-274**: ファイルパス変換処理
- **行275-283**: バックアップフォルダリベース処理

#### Step 4: バックアップ選択処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | ポイントインタイムリカバリのためのバックアップチェーン選択 |

**主要処理フロー**:
- **行121-138**: ContinuePoints処理とデータベースフィルタリング
- **行144-149**: RestoreTimeプロパティ追加
- **行173-219**: フル・差分バックアップ特定
- **行236-267**: トランザクションログ選択（LSNチェーン構築）

#### Step 5: バックアップ情報検証処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Test-DbaBackupInformation.ps1 | `public/Test-DbaBackupInformation.ps1` | リストア前検証ロジック |

**主要処理フロー**:
- **行106-113**: SQLインスタンス接続
- **行125-136**: 既存データベースファイル情報取得
- **行138-202**: 各種検証処理（DB存在、ファイル競合、パス作成）
- **行196-201**: LSNチェーン検証
- **行205-212**: バックアップファイルアクセス確認
- **行214-220**: IsVerifiedフラグ設定

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

```
Get-DbaBackupInformation
    |
    +-- Connect-DbaInstance (接続)
    |
    +-- Get-XpDirTreeRestoreFile (ファイルリスト取得)
    |       |
    |       +-- xp_dirtree (SQL Server内蔵プロシージャ)
    |
    +-- Read-DbaBackupHeader (ヘッダー読み取り)
    |       |
    |       +-- RESTORE HEADERONLY/FILELISTONLY
    |
    +-- Export-Clixml (エクスポート)

Format-DbaBackupInformation
    |
    +-- (メモリ内オブジェクト変換のみ)

Select-DbaBackupInformation
    |
    +-- (メモリ内フィルタリングのみ)

Test-DbaBackupInformation
    |
    +-- Connect-DbaInstance (接続)
    |
    +-- Get-DbaDbPhysicalFile (既存ファイル取得)
    |
    +-- Get-DbaDatabase (DB存在確認)
    |
    +-- Test-DbaPath (パス確認)
    |
    +-- New-DbaDirectory (ディレクトリ作成)
    |
    +-- Test-DbaLsnChain (LSNチェーン検証)
```

### データフロー図

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

バックアップファイルパス
        |
        v
+-------------------+
| Get-DbaBackup     |---> BackupHistory[]
| Information       |
+-------------------+
        |
        v
+-------------------+
| Format-DbaBackup  |---> BackupHistory[] (変換済み)
| Information       |
+-------------------+
        |
        v
+-------------------+
| Select-DbaBackup  |---> BackupHistory[] (フィルタ済み)
| Information       |
+-------------------+
        |
        v
+-------------------+
| Test-DbaBackup    |---> BackupHistory[] (検証済み)
| Information       |           |
+-------------------+           v
                        Restore-DbaDatabase
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaBackupInformation.ps1 | `public/Get-DbaBackupInformation.ps1` | ソース | バックアップ情報取得の主機能 |
| Format-DbaBackupInformation.ps1 | `public/Format-DbaBackupInformation.ps1` | ソース | バックアップ情報のフォーマット変換 |
| Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | ソース | ポイントインタイム用バックアップ選択 |
| Test-DbaBackupInformation.ps1 | `public/Test-DbaBackupInformation.ps1` | ソース | リストア前検証 |
| Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | ソース | バックアップヘッダー読み取り |
| Test-DbaLsnChain.ps1 | `private/functions/Test-DbaLsnChain.ps1` | ソース | LSNチェーン整合性検証 |
| Get-XpDirTreeRestoreFile.ps1 | `private/functions/Get-XpDirTreeRestoreFile.ps1` | ソース | xp_dirtreeによるファイルリスト取得 |
| BackupHistory.cs | `bin/projects/dbatools/dbatools/Database/BackupHistory.cs` | ソース | BackupHistoryクラス定義 |
