# 機能設計書 632-Get-DbaDbDetachedFileInfo

## 概要

本ドキュメントは、dbatools PowerShellモジュールのGet-DbaDbDetachedFileInfoコマンドレットの機能設計書である。このコマンドは、デタッチされたSQL Serverデータベースファイル（MDF）を読み取り、アタッチせずにメタデータとファイル構造を抽出する。

### 本機能の処理概要

Get-DbaDbDetachedFileInfoは、デタッチされたMDFファイルを解析し、データベース名、SQL Serverバージョン、照合順序、ファイル構造などの重要なメタデータを取得する。これにより、データベースファイルをライブインスタンスにアタッチするリスクなしに内容を調査できる。

**業務上の目的・背景**：データベース移行計画時に、異なるSQL Serverバージョン間の互換性を事前に確認する必要がある。また、アーカイブやストレージにあるデタッチされたデータベースファイルの構造や要件を、アタッチ前に把握したいケースがある。このコマンドは、MDFファイルヘッダーをSQL Serverの組み込みメソッドを使用して読み取るため、オンラインのSQL Serverインスタンスが必要であるが、ファイル自体をアタッチすることはない。

**機能の利用シーン**：
- SQL Serverバージョン間の移行計画時の互換性事前確認
- アーカイブされたデータベースファイルの調査
- デタッチされたデータベースの再アタッチ前の要件確認
- データベースファイルの照合順序やバージョン情報の監査

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続
2. DetachedDatabaseInfo SMOメソッドを使用してMDFファイルヘッダーを読み取り
3. 内部バージョン番号を人間が読めるSQL Serverバージョン名にマッピング
4. 照合順序IDを照合順序名に変換
5. EnumDetachedDatabaseFiles/EnumDetachedLogFilesでデータファイルとログファイルを列挙

**関連システム・外部連携**：Mount-DbaDatabase、Dismount-DbaDatabase、Restore-DbaDatabase等と連携してデータベースライフサイクル管理を支援

**権限による制御**：SQL Serverサービスアカウントが対象ファイルパスへの読み取りアクセス権限を持っている必要がある

## 関連画面

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

## 機能種別

データ取得 / メタデータ解析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | Yes | MDFファイルを解析するためのオンラインSQL Serverインスタンス | なし |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows認証、SQL認証、AD認証対応 |
| Path | string[] | Yes | 解析対象のMDFファイルパス（複数可、パイプライン対応） | SQL Serverサービスアカウントがアクセス可能 |
| EnableException | switch | No | 例外を有効にして詳細なエラー情報を取得 | なし |

### 入力データソース

- Path: ファイルシステム上のデタッチされたMDFファイル
- SqlInstance: MDFファイルのバイナリデータを解釈するためのSQL Serverインスタンス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名 |
| Name | String | MDFファイルに格納されている元のデータベース名 |
| Version | String | 人間が読めるSQL Serverバージョン名（例："SQL Server 2019"） |
| ExactVersion | Int | MDFファイルヘッダーの内部バージョン番号 |
| Collation | String | データベースの照合順序名またはID |
| DataFiles | StringCollection | データベースに属していたすべてのデータファイルパス |
| LogFiles | StringCollection | データベースに属していたすべてのログファイルパス |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. SQL Serverインスタンスへの接続
   └─ Connect-DbaInstanceで接続確立
   └─ サービスアカウント情報を取得

2. ファイルパスごとの処理ループ
   └─ 各MDFファイルに対して処理を実行

3. ファイルアクセス確認
   └─ Test-DbaPathでSQL Serverからのアクセス可能性を確認
   └─ アクセス不可の場合はエラー出力して次へ

4. MDFファイルヘッダー読み取り
   └─ server.DetachedDatabaseInfo()でメタデータ取得
   └─ データベース名、バージョン、照合順序IDを抽出

5. バージョンマッピング
   └─ 内部バージョン番号を人間が読める名前に変換
   └─ 998 → SQL Server 2025, 957 → SQL Server 2022 等

6. 照合順序名の解決
   └─ fn_helpcollations()を使用して照合順序IDを名前に変換
   └─ 解決できない場合はIDをそのまま使用

7. ファイル列挙
   └─ EnumDetachedDatabaseFiles()でデータファイル取得
   └─ EnumDetachedLogFiles()でログファイル取得

8. 結果オブジェクト出力
   └─ PSCustomObjectとして出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{接続成功?}
    C -->|No| D[Stop-Function]
    C -->|Yes| E[ファイルパスループ]
    E --> F[Test-DbaPath]
    F --> G{アクセス可能?}
    G -->|No| H[エラー出力]
    H --> I[次のファイル]
    G -->|Yes| J[DetachedDatabaseInfo取得]
    J --> K{取得成功?}
    K -->|No| L[エラー出力]
    L --> I
    K -->|Yes| M[バージョンマッピング]
    M --> N[照合順序解決]
    N --> O[ファイル列挙]
    O --> P[結果出力]
    P --> I
    I --> Q{次のファイル?}
    Q -->|Yes| E
    Q -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョンマッピング | 内部バージョン番号を対応するSQL Serverバージョン名にマッピング | すべてのMDF解析時 |
| BR-002 | 照合順序解決 | 照合順序IDをfn_helpcollations()で名前に変換。失敗時はID使用 | すべてのMDF解析時 |
| BR-003 | ファイルアクセス確認 | SQL Serverサービスアカウントがファイルにアクセス可能か確認 | 各ファイル処理前 |
| BR-004 | デタッチ状態確認 | DetachedDatabaseInfo失敗時はデタッチされていない可能性を警告 | メタデータ取得失敗時 |

### 計算ロジック

バージョンマッピングテーブル：
| 内部バージョン | SQL Serverバージョン |
|--------------|---------------------|
| 998 | SQL Server 2025 |
| 957 | SQL Server 2022 |
| 904 | SQL Server 2019 |
| 869, 868 | SQL Server 2017 |
| 852 | SQL Server 2016 |
| 782 | SQL Server 2014 |
| 706 | SQL Server 2012 |
| 661, 660 | SQL Server 2008 R2 |
| 655 | SQL Server 2008 SP2+ |
| 612, 611 | SQL Server 2005 |
| 539 | SQL Server 2000 |
| 515 | SQL Server 7.0 |
| 408 | SQL Server 6.5 |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 照合順序取得 | master.dbo.fn_helpcollations() | SELECT | 照合順序IDから名前への変換 |

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

#### fn_helpcollations()

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name | COLLATIONPROPERTY(name, 'COLLATIONID') = $collationid | 照合順序名の取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverへの接続失敗 | Stop-Functionで処理中断 |
| - | FileAccessError | ファイルへのアクセス不可 | 警告出力してスキップ |
| - | DetachedInfoError | MDFファイル読み取り失敗 | データベースがデタッチされているか確認を促す |
| - | FileEnumError | ファイル列挙失敗 | 警告出力してスキップ |

### リトライ仕様

リトライ機能なし。エラー時は当該ファイルをスキップして次のファイルを処理。

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

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

## パフォーマンス要件

- 各MDFファイルに対してSQL Serverのメソッド呼び出しを行うため、ネットワーク遅延の影響を受ける
- 大量のファイルを処理する場合は順次処理のため時間がかかる

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

- SQL Serverサービスアカウントがファイルパスに読み取りアクセス権限を持つ必要がある
- SqlCredentialパラメータでSQL認証、Windows認証、AD認証をサポート
- MFA対応の場合はConnect-DbaInstanceを事前に使用することを推奨
- デタッチされたファイルをアタッチせずに調査できるため、セキュリティリスクを低減

## 備考

- ファイルパスはSQL Serverインスタンスから見たパスである点に注意
- MDFファイルのみがサポートされ、NDFファイル単体では解析不可
- 内部バージョン番号の参照元: https://sqlserverbuilds.blogspot.com/2014/01/sql-server-internal-database-versions.html

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造とバージョンマッピングを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbDetachedFileInfo.ps1 | `public/Get-DbaDbDetachedFileInfo.ps1` | 152-162行目の出力オブジェクト構造 |
| 1-2 | Get-DbaDbDetachedFileInfo.ps1 | `public/Get-DbaDbDetachedFileInfo.ps1` | 110-128行目のバージョンマッピングswitch文 |

**読解のコツ**: SQL Serverの内部バージョン番号は公式ドキュメントには記載されていないが、sqlserverbuilds.blogspotで管理されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbDetachedFileInfo.ps1 | `public/Get-DbaDbDetachedFileInfo.ps1` | 80-89行目のbeginブロック（接続処理） |

**主要処理フロー**:
1. **81-86行目**: Connect-DbaInstanceで接続、失敗時はStop-Function
2. **87-88行目**: サーバー名とサービスアカウントを取得

#### Step 3: メイン処理ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbDetachedFileInfo.ps1 | `public/Get-DbaDbDetachedFileInfo.ps1` | 90-163行目のprocessブロック |

**主要処理フロー**:
- **96-98行目**: Test-DbaPathでファイルアクセス確認
- **100-107行目**: DetachedDatabaseInfoでメタデータ取得
- **130-137行目**: fn_helpcollationsで照合順序解決
- **141-148行目**: EnumDetachedDatabaseFiles/LogFilesでファイル列挙

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

```
Get-DbaDbDetachedFileInfo
    │
    ├─ Connect-DbaInstance（beginブロック）
    │      └─ SQL Server接続確立
    │
    ├─ Test-DbaPath
    │      └─ ファイルアクセス確認
    │
    ├─ server.DetachedDatabaseInfo()
    │      └─ SMOメソッドでMDFヘッダー読み取り
    │
    ├─ server.databases['master'].ExecuteWithResults()
    │      └─ 照合順序クエリ実行
    │
    ├─ server.EnumDetachedDatabaseFiles()
    │      └─ データファイル列挙
    │
    └─ server.EnumDetachedLogFiles()
           └─ ログファイル列挙
```

### データフロー図

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

MDFファイルパス      ───▶ Test-DbaPath
                                 │
                                 ▼
                           DetachedDatabaseInfo
                                 │
                                 ▼
                           バージョンマッピング         ───▶ PSCustomObject
                           照合順序解決                     - Name
                           ファイル列挙                     - Version
                                                           - Collation
                                                           - DataFiles
                                                           - LogFiles
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbDetachedFileInfo.ps1 | `public/Get-DbaDbDetachedFileInfo.ps1` | ソース | メイン処理ロジック |
| Mount-DbaDatabase.ps1 | `public/Mount-DbaDatabase.ps1` | ソース | 関連コマンド（データベースアタッチ） |
| Dismount-DbaDatabase.ps1 | `public/Dismount-DbaDatabase.ps1` | ソース | 関連コマンド（データベースデタッチ） |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | 内部依存（ファイルアクセス確認） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | 内部依存（インスタンス接続） |
