# 機能設計書 33-Format-DbaBackupInformation

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Format-DbaBackupInformation`コマンドレットに関する機能設計書です。このコマンドは、バックアップ履歴オブジェクトのメタデータを変更し、異なる名前、パス、または場所でのデータベースリストアを準備する機能を提供します。

### 本機能の処理概要

Format-DbaBackupInformationは、Select-DbaBackupInformationから取得したバックアップ履歴オブジェクトを受け取り、データベース名の変更、ファイル配置先の変更、バックアップパスの再構成など、リストア操作に必要なメタデータ変換を実行します。これにより、異なるサーバーへのリストアやデータベースのリネームを含む複雑なディザスタリカバリシナリオに対応します。

**業務上の目的・背景**：ディザスタリカバリやサーバー移行において、バックアップを元のサーバーとは異なる環境にリストアする必要があります。その際、データベース名、ファイルパス、論理名などの変更が必要となります。この機能により、複雑なリストア前の手動編集を自動化し、確実かつ効率的なリストア準備を実現します。

**機能の利用シーン**：
- 本番環境から開発/テスト環境へのデータベースコピー
- データベース名を変更してのリストア
- 異なるドライブ構成を持つサーバーへの移行
- ネットワーク共有からローカルストレージへのバックアップファイル移動後のリストア

**主要な処理内容**：
1. 入力BackupHistoryオブジェクトの検証と複製
2. データベース名の置換（単一またはハッシュテーブルによるマッピング）
3. データベース名プレフィックスの追加
4. データ/ログ/FileStreamファイルのディレクトリ変更
5. 物理ファイル名のプレフィックス/サフィックス追加
6. バックアップファイルパスの再構成（RebaseBackupFolder）

**関連システム・外部連携**：
- Get-DbaBackupInformation / Select-DbaBackupInformation からのパイプライン入力
- Restore-DbaDatabase / Invoke-DbaAdvancedRestore へのパイプライン出力

**権限による制御**：この機能はメタデータの変換のみを行い、データベースやファイルシステムへの直接アクセスは行いません。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | バックアップ情報 | 補助機能 | バックアップ履歴メタデータの変更 |

## 機能種別

データ変換処理 / メタデータ編集

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| BackupHistory | object[] | Yes | バックアップ履歴オブジェクト | ValueFromPipeline |
| ReplaceDatabaseName | object | No | データベース名の置換（文字列またはハッシュテーブル） | - |
| ReplaceDbNameInFile | switch | No | ファイル名内のDB名も置換 | - |
| DataFileDirectory | string | No | データファイルの出力先ディレクトリ | - |
| LogFileDirectory | string | No | ログファイルの出力先ディレクトリ | - |
| DestinationFileStreamDirectory | string | No | FileStreamファイルの出力先ディレクトリ | - |
| DatabaseNamePrefix | string | No | データベース名に追加するプレフィックス | - |
| DatabaseFilePrefix | string | No | 物理ファイル名に追加するプレフィックス | - |
| DatabaseFileSuffix | string | No | 物理ファイル名に追加するサフィックス | - |
| RebaseBackupFolder | string | No | バックアップファイルの新しい基底パス | - |
| Continue | switch | No | 継続リストアシーケンスとしてマーク | - |
| FileMapping | hashtable | No | 論理名から物理パスへのカスタムマッピング | - |
| PathSep | string | No | パス区切り文字（デフォルト: \） | - |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- Select-DbaBackupInformationからのBackupHistoryオブジェクト
- Get-DbaBackupInformationからのBackupHistoryオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホスト名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| Database | string | データベース名（変更後） |
| OriginalDatabase | string | 元のデータベース名（追加プロパティ） |
| Path | string[] | バックアップファイルパス（変更後） |
| FullName | string[] | バックアップファイルパス（変更後） |
| OriginalFullName | string[] | 元のバックアップファイルパス（追加プロパティ） |
| FileList | object[] | ファイル情報（変更後） |
| OriginalFileList | object[] | 元のファイル情報（追加プロパティ） |
| IsVerified | bool | 検証済みフラグ（$False初期化） |
| Type | string | バックアップタイプ（正規化後） |

### 出力先

- PowerShellパイプライン（Dataplat.Dbatools.Database.BackupHistory）
- Restore-DbaDatabase / Invoke-DbaAdvancedRestore へのパイプライン

## 処理フロー

### 処理シーケンス

```
1. begin ブロック
   └─ ReplaceDatabaseName の型判定（string/hashtable）
   └─ 各ディレクトリパスの末尾区切り文字除去

2. process ブロック（各BackupHistoryに対して）
   └─ Original* プロパティの追加（未存在の場合）
   └─ Type値の正規化（Full→Database等）

3. データベース名変更
   └─ single: 直接置換
   └─ multi: ハッシュテーブルによるマッピング
   └─ DatabaseNamePrefixの追加

4. FileListの処理
   └─ FileMapping指定時: 論理名→物理パスのマッピング適用
   └─ 未指定時:
      └─ パス解析とファイル名抽出
      └─ ReplaceDbNameInFile処理
      └─ ファイルタイプ別ディレクトリ決定（D/L/S）
      └─ プレフィックス/サフィックス追加
      └─ 新しいPhysicalName構築

5. FullNameの処理
   └─ RebaseBackupFolder指定時:
      └─ 各バックアップファイルのパスを新しい基底に再構成
      └─ HTTP URLの場合はスキップ

6. 変更後のBackupHistoryオブジェクトを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ReplaceDatabaseName型判定]
    B --> C[ディレクトリパス正規化]
    C --> D[foreach BackupHistory]
    D --> E{Original*プロパティ存在?}
    E -->|No| F[Original*プロパティ追加]
    E -->|Yes| G[Type値正規化]
    F --> G
    G --> H{ReplaceDatabaseName指定?}
    H -->|single| I[Database名直接置換]
    H -->|multi| J[ハッシュテーブルマッピング]
    H -->|No| K[DatabaseNamePrefix追加のみ]
    I --> K
    J --> K
    K --> L[FileList処理]
    L --> M{FileMapping指定?}
    M -->|Yes| N[カスタムマッピング適用]
    M -->|No| O[ファイルタイプ別ディレクトリ決定]
    N --> P[RebaseBackupFolder処理]
    O --> P
    P --> Q{RebaseBackupFolder指定?}
    Q -->|Yes| R[FullNameパス再構成]
    Q -->|No| S[BackupHistory出力]
    R --> S
    S --> D
    D --> T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | Type正規化 | Full→Database, Differential→Database Differential, Log→Transaction Log | Type値変換時 |
| BR-02 | ファイルタイプ判定 | D=データ, L=ログ, S=FileStream | FileList処理時 |
| BR-03 | ディレクトリ優先順位 | FileMapping > 専用ディレクトリ > DataFileDirectory | ファイル配置決定時 |
| BR-04 | HTTP URLスキップ | RebaseBackupFolderはHTTP URLには適用しない | FullName処理時 |
| BR-05 | 元データ保持 | Original*プロパティで変更前の値を保持 | 常時 |

### 計算ロジック

ファイルタイプ別ディレクトリ決定：
```
if FileMapping[LogicalName] exists:
    use FileMapping[LogicalName]
elif Type = 'D':
    use DataFileDirectory (if specified)
elif Type = 'L':
    use LogFileDirectory (if specified) else DataFileDirectory
elif Type = 'S':
    use DestinationFileStreamDirectory (if specified) else DataFileDirectory
else:
    extract directory from original path
```

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

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

この機能はデータベース操作を行いません。メタデータの変換のみを実行します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidType | ReplaceDatabaseNameが不正な型 | 文字列またはハッシュテーブルを使用 |

### リトライ仕様

リトライ機能は実装されていません。

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

トランザクションは使用しません（メタデータ変換のみ）。

## パフォーマンス要件

入力オブジェクト数に比例した線形処理時間。大量のバックアップファイルリストでも効率的に処理可能。

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

- ファイルシステムやデータベースへの直接アクセスなし
- 機密情報の変換（パス等）は出力オブジェクトに含まれる

## 備考

- LinuxとWindowsの両方のパス形式に対応（PathSepパラメータ）
- MacOS特有のパス処理にも対応（240-241行目）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Format-DbaBackupInformation.ps1 | `public/Format-DbaBackupInformation.ps1` | パラメータ定義（141-158行目）を確認 |

**読解のコツ**: `ValueFromPipeline`属性がBackupHistoryに設定されており、パイプライン入力に対応している。

#### Step 2: begin ブロックの初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Format-DbaBackupInformation.ps1 | `public/Format-DbaBackupInformation.ps1` | beginブロック（159-185行目）でのReplaceDatabaseName型判定とパス正規化 |

**主要処理フロー**:
1. **162-172行目**: ReplaceDatabaseNameの型判定（string/hashtable）
2. **173-184行目**: 各ディレクトリパスの末尾区切り文字除去

#### Step 3: process ブロックのメイン変換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Format-DbaBackupInformation.ps1 | `public/Format-DbaBackupInformation.ps1` | processブロック（188-287行目）でのメタデータ変換 |

**主要処理フロー**:
- **191-203行目**: Original*プロパティの追加（OriginalDatabase, OriginalFileList, OriginalFullName, IsVerified）
- **204-208行目**: Type値の正規化（Full/Differential/Log）
- **211-220行目**: データベース名の置換処理
- **222-274行目**: FileList処理（ファイルパス変換）
- **275-283行目**: FullName処理（RebaseBackupFolder適用）

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

```
Format-DbaBackupInformation
    │
    ├─ begin ブロック
    │      │
    │      ├─ ReplaceDatabaseName 型判定
    │      │      └─ single / multi 判定
    │      │
    │      └─ Test-Bound + パス正規化
    │             └─ 末尾区切り文字除去
    │
    └─ process ブロック
           │
           ├─ Add-Member (Original*プロパティ)
           │      └─ 元データ保持
           │
           ├─ Type 正規化
           │      └─ Full/Differential/Log → 標準名
           │
           ├─ Database 名変更
           │      ├─ single: 直接置換
           │      └─ multi: ハッシュテーブル参照
           │
           ├─ FileList 変換
           │      ├─ FileMapping 適用
           │      ├─ パス解析
           │      ├─ ReplaceDbNameInFile
           │      ├─ ディレクトリ決定
           │      └─ 新PhysicalName構築
           │
           └─ FullName 変換
                  └─ RebaseBackupFolder 適用
```

### データフロー図

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

BackupHistory ─────────▶ Add-Member ────────────────▶ OriginalDatabase
(パイプライン)                │                          OriginalFileList
                             │                          OriginalFullName
                             │
ReplaceDatabaseName ───▶ Database 置換 ─────────────▶ Database (変更後)
                             │
DataFileDirectory ─────▶ ディレクトリ決定 ──────────▶ FileList.PhysicalName
LogFileDirectory                │                      (変更後)
DestinationFileStream          │
Directory                       │
                             │
DatabaseFilePrefix ────▶ ファイル名構築 ────────────▶ 新ファイル名
DatabaseFileSuffix             │
                             │
RebaseBackupFolder ────▶ パス再構成 ────────────────▶ FullName (変更後)
                             │
                             └─────────────────────────▶ BackupHistory
                                                         (変更後オブジェクト)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Format-DbaBackupInformation.ps1 | `public/Format-DbaBackupInformation.ps1` | ソース | メイン関数実装 |
| Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | ソース | 入力データ提供元 |
| Get-DbaBackupInformation.ps1 | `public/Get-DbaBackupInformation.ps1` | ソース | 入力データ提供元 |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | 出力先コマンド |
| Invoke-DbaAdvancedRestore.ps1 | `public/Invoke-DbaAdvancedRestore.ps1` | ソース | 出力先コマンド |
