# 機能設計書 636-Get-DbaDbFileMapping

## 概要

本ドキュメントは、dbatools PowerShellモジュールのGet-DbaDbFileMappingコマンドレットの機能設計書である。このコマンドは、既存のデータベースからファイルマッピングハッシュテーブルを作成し、Restore-DbaDatabase等のリストア操作で使用できる形式で提供する。

### 本機能の処理概要

Get-DbaDbFileMappingは、既存のデータベースから論理ファイル名と物理ファイルパスのマッピングを抽出し、Restore-DbaDatabase互換のハッシュテーブル形式で返す。これにより、データベースを異なるサーバーや場所にリストアする際に、ファイルパスを手動で指定する必要がなくなる。データファイルとログファイルの両方をデータベースのファイルグループから読み取り、元のファイル構造を保持した完全なマッピングを作成する。

**業務上の目的・背景**：データベースのリストア操作では、論理ファイル名から物理ファイルパスへのマッピングが必要になることが多い。特に、異なるサーバーや異なるディレクトリ構造へのリストア時に、このマッピング情報は不可欠である。本コマンドは、既存のデータベースからこのマッピングを自動的に抽出することで、手動でのパス指定作業を省略し、リストア操作を効率化する。

**機能の利用シーン**：
- データベースの移行（別サーバーへのリストア）
- データベースのクローン作成
- バックアップからの復元時のファイルパス設定
- ディザスターリカバリー計画の準備
- テスト環境へのデータベース展開

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続し、データベースを取得
2. 各データベースのファイルグループからデータファイル情報を抽出
3. ログファイル情報を抽出
4. 論理ファイル名をキー、物理ファイルパスを値とするハッシュテーブルを作成
5. PSCustomObjectとして出力

**関連システム・外部連携**：Restore-DbaDatabase（-FileMappingパラメータ）、Get-DbaDatabase、Backup-DbaDatabase等と連携

**権限による制御**：対象データベースへのアクセス権限が必要。アクセス不可のデータベースはスキップされる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン/PowerShellコンソール | 主画面 | コマンド実行および結果表示 |

## 機能種別

データ取得 / マッピング生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス。複数指定可、パイプライン入力対応 | なし |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows認証、SQL認証、AD認証対応 |
| Database | string[] | No | 対象データベース。ワイルドカード対応 | なし |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | Get-DbaDatabase等からのパイプライン入力 | SMO Databaseオブジェクト |
| EnableException | switch | No | 例外を有効にして詳細なエラー情報を取得 | なし |

### 入力データソース

- SqlInstance/Database指定時：Get-DbaDatabase経由でデータベースを取得
- InputObject指定時：パイプラインから受け取ったDatabaseオブジェクトを直接処理

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名（サービス名） |
| SqlInstance | String | 完全なSQL Serverインスタンス名 |
| Database | String | データベース名 |
| FileMapping | Hashtable | 論理ファイル名（キー）と物理ファイルパス（値）のマッピング |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstanceまたはInputObjectの指定確認
   └─ 両方未指定の場合は警告出力

2. データベースオブジェクト取得
   └─ InputObject未指定時：Get-DbaDatabase呼び出し
   └─ InputObject指定時：直接使用

3. データベースごとの処理ループ
   └─ IsAccessibleプロパティで到達可能性確認
   └─ 到達不可の場合はスキップ

4. ファイルマッピング作成
   └─ 空のハッシュテーブルを初期化
   └─ FileGroups.Filesからデータファイルを追加
   └─ LogFilesからログファイルを追加

5. 結果出力
   └─ PSCustomObjectとして出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstanceまたはInputObject?}
    B -->|どちらもなし| C[警告出力・終了]
    B -->|あり| D{InputObject指定?}
    D -->|No| E[Get-DbaDatabase呼び出し]
    D -->|Yes| F[InputObject使用]
    E --> F
    F --> G[データベースループ]
    G --> H{IsAccessible?}
    H -->|No| I[スキップ・ログ出力]
    H -->|Yes| J[空のハッシュテーブル作成]
    I --> K{次のDB?}
    J --> L[FileGroups.Files処理]
    L --> M[LogFiles処理]
    M --> N[PSCustomObject出力]
    N --> K
    K -->|Yes| G
    K -->|No| O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 必須パラメータ確認 | SqlInstanceまたはInputObjectのいずれかが必要 | 処理開始時 |
| BR-002 | アクセス可能性確認 | IsAccessible=Falseのデータベースはスキップ | 各データベース処理時 |
| BR-003 | データファイルマッピング | FileGroups.Filesの各ファイルをName=>FileNameでマッピング | 各データベース処理時 |
| BR-004 | ログファイルマッピング | LogFilesの各ファイルをName=>FileNameでマッピング | 各データベース処理時 |

### 計算ロジック

ファイルマッピング生成ロジック：
```powershell
foreach ($file in $db.FileGroups.Files) {
    $fileMap[$file.Name] = $file.FileName
}
foreach ($file in $db.LogFiles) {
    $fileMap[$file.Name] = $file.FileName
}
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ファイル情報取得 | sys.database_files（内部） | SELECT | SMO経由でファイルメタデータ取得 |

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

#### sys.database_files（SMO経由）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, physical_name | 全ファイル | SMO FileGroups.Files/LogFiles経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ParameterError | SqlInstanceとInputObject両方未指定 | 警告メッセージ出力して終了 |
| - | AccessError | データベースがアクセス不可 | Verboseログ出力してスキップ |

### リトライ仕様

リトライ機能なし。アクセス不可のデータベースはスキップして次を処理。

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

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

## パフォーマンス要件

- SMOを使用するため、初回アクセス時に若干のオーバーヘッドが発生
- 大量のファイルを持つデータベースでも、メモリ内ハッシュテーブル操作のため高速

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

- 対象データベースへのアクセス権限が必要
- SqlCredentialパラメータでSQL認証、Windows認証、AD認証をサポート
- ファイルパス情報を含むため、出力の取り扱いに注意

## 備考

- 出力されるFileMappingハッシュテーブルはRestore-DbaDatabase -FileMappingパラメータに直接渡すことが可能
- 複数のファイルグループを持つデータベースでも、すべてのデータファイルが含まれる
- FILESTREAM filegroup のファイルも含まれる

---

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

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

### 推奨読解順序

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

出力されるFileMappingハッシュテーブルの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbFileMapping.ps1 | `public/Get-DbaDbFileMapping.ps1` | 92-98行目の出力オブジェクト構造 |
| 1-2 | Get-DbaDbFileMapping.ps1 | `public/Get-DbaDbFileMapping.ps1` | 83-90行目のファイルマッピング作成 |

**読解のコツ**: FileMappingはハッシュテーブル型で、論理ファイル名がキー、物理ファイルパスが値となる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbFileMapping.ps1 | `public/Get-DbaDbFileMapping.ps1` | 70-78行目のprocessブロック開始部分 |

**主要処理フロー**:
1. **71-74行目**: SqlInstanceとInputObject両方未指定時の警告
2. **76-78行目**: InputObject未指定時のGet-DbaDatabase呼び出し

#### Step 3: ファイルマッピング処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbFileMapping.ps1 | `public/Get-DbaDbFileMapping.ps1` | 80-102行目のデータベースループ |

**主要処理フロー**:
- **81行目**: IsAccessibleチェック
- **83行目**: 空のハッシュテーブル初期化
- **85-87行目**: FileGroups.Filesループでデータファイル追加
- **88-90行目**: LogFilesループでログファイル追加

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

```
Get-DbaDbFileMapping
    │
    ├─ Test-Bound
    │      └─ パラメータ指定確認
    │
    ├─ Get-DbaDatabase（InputObject未指定時）
    │      └─ 対象データベース取得
    │
    └─ Write-Message
           └─ Verbose/Warningログ出力
```

### データフロー図

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

SqlInstance/Database  ───▶ Get-DbaDatabase
                                 │
                                 ▼
                           db.FileGroups.Files
                           db.LogFiles
                                 │
                                 ▼
                           ハッシュテーブル作成        ───▶ PSCustomObject
                           $fileMap[Name] = FileName         - FileMapping
                                                              (Hashtable)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbFileMapping.ps1 | `public/Get-DbaDbFileMapping.ps1` | ソース | メイン処理ロジック |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | 内部依存（データベース取得） |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | 連携先コマンド（-FileMapping使用） |
