# 機能設計書 42-Read-DbaBackupHeader

## 概要

本ドキュメントは、SQL Serverバックアップファイルからメタデータを抽出するdbatools PowerShellコマンド `Read-DbaBackupHeader` の機能設計書である。

### 本機能の処理概要

この機能は、SQL ServerのRESTORE HEADERONLY機能を使用してバックアップファイルから詳細なメタデータ（データベース名、バックアップタイプ、作成日時、ファイルリスト、バックアップサイズ情報など）を抽出する。実際のリストア操作を行わずにバックアップ内容を検証できる。

**業務上の目的・背景**：データベース管理者がリストア計画を立案する際、バックアップファイルの内容を事前に確認する必要がある。また、バックアップインベントリの監査、バックアップの妥当性検証、リストア前の互換性確認などに使用される。特に災害復旧シナリオでは、迅速なバックアップ情報の把握が重要となる。

**機能の利用シーン**：
- リストア前のバックアップファイル内容確認
- バックアップインベントリの棚卸し作業
- バックアップファイルの整合性事前検証
- 複数バックアップファイルの一括情報収集
- Azure Blob StorageやS3からのバックアップ情報取得

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続
2. バックアップファイルパスのアクセス可能性検証
3. マルチスレッドによる並列処理でRESTORE HEADERONLYを実行
4. バックアップヘッダー情報の取得とDataTable形式での返却
5. FileListプロパティへのファイル詳細情報の格納
6. SQL Serverバージョン文字列への変換

**関連システム・外部連携**：
- ローカルファイルシステム、ネットワーク共有、Azure Blob Storage、AWS S3からのバックアップファイル読み取り
- SQL Server SMO (RESTORE HEADERONLY, RESTORE FILELISTONLY)

**権限による制御**：対象SQL Serverインスタンスへの接続権限と、バックアップファイルへの読み取りアクセス権（SQL Serverサービスアカウントが読み取り可能であること）が必要。

## 関連画面

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

## 機能種別

データ取得 / メタデータ抽出

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance | Yes | バックアップ読み取りに使用するSQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Path | object[] | Yes | バックアップファイルパス（ローカル、UNC、Azure URL、S3 URL） | 拡張子が存在すること |
| Simple | switch | No | 簡易出力モード | - |
| FileList | switch | No | ファイルリスト詳細を出力 | - |
| StorageCredential | string | No | Azure/S3ストレージ資格情報名 | - |
| EnableException | switch | No | 例外を有効にするスイッチ | - |

### 入力データソース

バックアップファイル（.bak, .trn, .dif等）

## 出力仕様

### 出力データ

**デフォルト出力（System.Data.DataRow）**

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DatabaseName | string | バックアップ元データベース名 |
| BackupFinishDate | DateTime | バックアップ完了日時 |
| RecoveryModel | string | 復旧モデル（Simple/Full/BulkLogged） |
| BackupSize | DbaSize | バックアップサイズ |
| CompressedBackupSize | DbaSize | 圧縮後バックアップサイズ |
| DatabaseCreationDate | DateTime | データベース作成日時 |
| UserName | string | バックアップ実行ログイン |
| ServerName | string | バックアップ作成元インスタンス名 |
| SqlVersion | string | SQL Serverバージョン文字列 |
| BackupPath | string | バックアップファイルパス |
| FileList | object | ファイル詳細情報コレクション |
| BackupType | string | バックアップタイプ |
| Position | int | バックアップセット内位置 |
| その他 | - | SMO ReadBackupHeader()から返される全プロパティ |

**-Simple 出力**

DatabaseName, BackupFinishDate, RecoveryModel, BackupSize, CompressedBackupSize, DatabaseCreationDate, UserName, ServerName, SqlVersion, BackupPath の10項目のみ

**-FileList 出力**

| 項目名 | 型 | 説明 |
|--------|-----|------|
| LogicalName | string | ファイル論理名 |
| PhysicalName | string | ファイル物理パス |
| Type | string | ファイルタイプ（D/L） |
| FileGroupName | string | ファイルグループ名 |
| Size | long | ファイルサイズ（バイト） |
| その他 | - | RESTORE FILELISTONLY結果 |

### 出力先

PowerShellパイプライン（System.Data.DataRow）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ Pathが拡張子を持つファイルであることを確認
2. SQL Serverインスタンス接続
   └─ Connect-DbaInstanceで接続確立
3. ファイルアクセス検証
   └─ Test-DbaPathでSQL Serverからのアクセス可能性確認
4. Runspaceプール初期化
   └─ 最小1、最大10スレッドでプール作成
5. 各ファイルに対してスレッド起動
   └─ getHeaderScriptブロックを非同期実行
6. RESTORE HEADERONLY実行
   └─ SMO Restore.ReadBackupHeader()呼び出し
7. 結果処理
   └─ FileList追加、SqlVersion変換、サイズ型変換
8. 出力フォーマット
   └─ Simple/FileList/デフォルト出力の選択
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パス検証]
    B --> C{ファイル拡張子あり?}
    C -->|No| D[Stop-Function]
    C -->|Yes| E[Connect-DbaInstance]
    E --> F{接続成功?}
    F -->|No| G[Stop-Function]
    F -->|Yes| H[Test-DbaPath]
    H --> I[Runspaceプール初期化]
    I --> J{各ファイルループ}
    J --> K{URL/S3?}
    K -->|Yes| L[DeviceType=URL]
    K -->|No| M[DeviceType=FILE]
    L --> N{ファイル存在?}
    M --> N
    N -->|No| O[警告出力]
    N -->|Yes| P[スレッド起動]
    P --> Q[ReadBackupHeader実行]
    Q --> R[FileList追加]
    R --> S[SqlVersion変換]
    S --> J
    J --> T{全スレッド完了?}
    T -->|No| U[待機]
    U --> T
    T -->|Yes| V{Simple指定?}
    V -->|Yes| W[簡易出力]
    V -->|No| X{FileList指定?}
    X -->|Yes| Y[FileList出力]
    X -->|No| Z[全項目出力]
    W --> AA[終了]
    Y --> AA
    Z --> AA
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-42-01 | パス検証 | Pathは拡張子を持つファイルでなければならない | 全入力パス |
| BR-42-02 | デバイスタイプ判定 | http/s3で始まるパスはURLタイプ、それ以外はFILEタイプ | Path形式による |
| BR-42-03 | 並列処理上限 | 同時実行スレッド数は最大10 | 常時 |
| BR-42-04 | バージョン変換 | DatabaseVersionからSQL Serverバージョン文字列に変換 | 全バックアップ |

### 計算ロジック

**デバイスタイプ判定（299-303行目）**:
```powershell
if ($file -like 'http*' -or $file -like 's3*') {
    $deviceType = 'URL'
} else {
    $deviceType = 'FILE'
}
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ヘッダー読取 | - | RESTORE HEADERONLY | バックアップファイルのヘッダー情報取得 |
| ファイルリスト取得 | - | RESTORE FILELISTONLY | バックアップ内ファイル一覧取得 |

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

本機能はバックアップファイルを直接読み取るため、データベーステーブルへの操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidArgument | パラメータエラー | Pathにフォルダが指定された | Stop-Functionでエラー終了 |
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionでエラー終了 |
| - | ファイルアクセスエラー | SQL Serverがファイルにアクセスできない | 警告出力してスキップ |
| - | バージョン非互換 | バックアップがSqlInstanceより新しい | Stop-Functionでスキップ |
| - | ストレージアクセスエラー | Azure/S3資格情報エラー | Stop-Functionでスキップ |

### リトライ仕様

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

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- Runspaceプールによる並列処理（最大10スレッド）でパフォーマンス最適化
- 大量ファイル処理時はプログレスバーで進捗表示

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

- SQL Serverサービスアカウントがバックアップファイルへの読み取り権限を持つ必要がある
- Azure/S3ストレージアクセスにはStorageCredentialパラメータで資格情報を指定
- SqlCredentialパラメータでセキュアな認証情報の受け渡しが可能

## 備考

- バックアップファイルはローカルワークステーションからではなく、SqlInstanceからアクセス可能である必要がある
- S3サポートはSQL Server 2022以降が必要

---

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

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

### 推奨読解順序

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

バックアップヘッダーから取得される情報構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | 46-128行目の.OUTPUTSセクションで出力構造を確認 |

**読解のコツ**: RESTORE HEADERONLYとRESTORE FILELISTONLYの出力列は異なる。両方の構造を理解する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | 189-202行目のparam定義 |

**主要処理フロー**:
1. **204行目**: beginブロック開始
2. **205-211行目**: パス検証（拡張子チェック）
3. **213-218行目**: SQL Server接続

#### Step 3: ヘッダー読取スクリプトを理解する

Runspaceで実行されるスクリプトブロックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | 219-265行目の$getHeaderScript |

**主要処理フロー**:
- **227-228行目**: SMO ServerとRestoreオブジェクト作成
- **230-232行目**: URL時の資格情報設定
- **234-236行目**: BackupDeviceItem追加とReadBackupHeader実行
- **241-263行目**: FileList追加、サイズ型変換

#### Step 4: 並列処理を理解する

Runspaceプールによる並列実行ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | 290-336行目のスレッド起動処理 |

**主要処理フロー**:
- **290-294行目**: Runspaceプール初期化（1-10スレッド）
- **298-336行目**: ファイルごとのスレッド起動
- **319-332行目**: スレッドオブジェクト管理

#### Step 5: 結果処理を理解する

スレッド完了後の結果処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | 338-380行目の結果受信処理 |

**主要処理フロー**:
- **341行目**: プログレスバー更新
- **344行目**: EndInvokeで結果取得
- **356-363行目**: SqlVersion変換
- **364-370行目**: Simple/FileList/デフォルト出力選択

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

```
Read-DbaBackupHeader
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ Test-DbaPath
    │      └─ ファイルアクセス可能性確認
    │
    └─ Runspaceプール
           │
           └─ $getHeaderScript (並列実行)
                  │
                  ├─ SMO.Restore.ReadBackupHeader()
                  │      └─ RESTORE HEADERONLY実行
                  │
                  └─ SMO.Restore.ReadFileList()
                         └─ RESTORE FILELISTONLY実行
```

### データフロー図

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

Path ───────────────────────► パス検証 ─────────────────────────►
SqlInstance ────────────────► Connect-DbaInstance ──────────────►
                                      │
                                      ▼
                              Test-DbaPath ──────────────────────►
                                      │
                                      ▼
バックアップファイル ────────► Runspaceプール ───────────────────►
                                      │
                                      ├─► ReadBackupHeader()
                                      │         │
                                      │         ▼
                                      │   DataTable
                                      │         │
                                      └─► ReadFileList()
                                                │
                                                ▼
                                          FileList追加
                                                │
                                                ▼
                              Convert-DbVersionToSqlVersion ────►
                                                │
                                                ▼
                              Simple/FileList選択 ───► DataRow出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | ソース | メイン機能実装 |
| Read-DbaBackupHeader.Tests.ps1 | `tests/Read-DbaBackupHeader.Tests.ps1` | テスト | Pesterテストコード |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パスアクセス検証（依存コマンド） |
| Convert-DbVersionToSqlVersion.ps1 | `private/functions/Convert-DbVersionToSqlVersion.ps1` | ソース | バージョン変換（依存関数） |
