# 機能設計書 633-Get-DbaDbFile

## 概要

本ドキュメントは、dbatools PowerShellモジュールのGet-DbaDbFileコマンドレットの機能設計書である。このコマンドは、SQL Serverデータベースファイル（データファイルおよびログファイル）の詳細情報を取得し、容量計画、パフォーマンス分析、ストレージ管理に必要な情報を提供する。

### 本機能の処理概要

Get-DbaDbFileは、直接T-SQLクエリを使用してデータベースファイルの詳細情報を取得する。現在のサイズ、使用済み領域、成長設定、I/O統計、ボリューム空き領域など、DBAが容量計画やパフォーマンス分析に必要とする包括的なファイルメタデータを返す。SMOベースのアプローチとは異なり、コストのかかる列挙操作を避け、複数のデータベース全体のファイル構成を分析する際により高速な結果を提供する。

**業務上の目的・背景**：データベースファイルの管理は、SQL Server運用において最も重要なタスクの一つである。ファイルサイズの監視、自動拡張設定の確認、I/Oパフォーマンスの把握は、安定したデータベース運用に不可欠である。このコマンドは、これらの情報を単一のコマンドで取得でき、複数のデータベースやインスタンスにまたがる分析を効率化する。

**機能の利用シーン**：
- データベース容量計画と領域監視
- 自動拡張設定の監査と最適化
- I/Oパフォーマンスのベースライン取得
- ファイルグループごとの領域使用状況分析
- ディスクボリュームの空き領域確認

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続
2. SQL Serverバージョンに応じた適切なT-SQLクエリを生成
3. sys.database_files、sys.filegroups、sys.dm_io_virtual_file_stats等からデータ取得
4. サイズ情報をdbasizeオブジェクトとしてフォーマット
5. 結果をPSCustomObjectとして出力

**関連システム・外部連携**：Get-DbaDatabase、Get-DbaDbFileGroup、Set-DbaDbFileGrowth等と連携したファイル管理ワークフロー

**権限による制御**：対象データベースへのVIEW DATABASE STATE権限が必要

## 関連画面

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

## 機能種別

データ取得（SELECT）/ パフォーマンス分析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス。複数指定可、パイプライン入力対応 | なし |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows認証、SQL認証、AD認証対応 |
| Database | object[] | No | 対象データベース。ワイルドカード対応 | なし |
| ExcludeDatabase | object[] | No | 除外データベース。ワイルドカード対応 | なし |
| FileGroup | object[] | 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 | データベース名 |
| DatabaseID | Int | データベースID |
| FileGroupName | String | ファイルグループ名（ログファイルはNULL） |
| ID | Int | データベース内のファイルID |
| Type | Int | ファイルタイプ（0: データ、1: ログ） |
| TypeDescription | String | ファイルタイプ説明（ROWS/LOG） |
| LogicalName | String | SQL Server内の論理ファイル名 |
| PhysicalName | String | OSファイルパス |
| State | String | ファイル状態（ONLINE、OFFLINE等） |
| MaxSize | dbasize | 最大サイズ |
| Growth | Int | 成長増分値 |
| GrowthType | String | 成長タイプ（Percent/kb） |
| NextGrowthEventSize | dbasize | 次回自動拡張時のサイズ |
| Size | dbasize | 現在のサイズ |
| UsedSpace | dbasize | 使用済み領域 |
| AvailableSpace | dbasize | 空き領域 |
| IsOffline | Boolean | オフラインかどうか |
| IsReadOnly | Boolean | 読み取り専用かどうか |
| IsReadOnlyMedia | Boolean | メディアが読み取り専用かどうか |
| IsSparse | Boolean | スパースファイルかどうか |
| NumberOfDiskWrites | Int | ディスク書き込み回数 |
| NumberOfDiskReads | Int | ディスク読み取り回数 |
| ReadFromDisk | dbasize | ディスクからの読み取りバイト数 |
| WrittenToDisk | dbasize | ディスクへの書き込みバイト数 |
| VolumeFreeSpace | dbasize | ボリュームの空き領域 |
| FileGroupDataSpaceId | Int | ファイルグループのデータスペースID |
| FileGroupType | String | ファイルグループタイプ |
| FileGroupTypeDescription | String | ファイルグループタイプ説明 |
| FileGroupDefault | Boolean | デフォルトファイルグループかどうか |
| FileGroupReadOnly | Boolean | ファイルグループが読み取り専用かどうか |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. SQLクエリ生成（beginブロック）
   └─ バージョン別のクエリテンプレートを準備
   └─ SQL 2008+用、SQL 2005用、SQL 2000用の3種類

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

3. データベースごとの処理ループ
   └─ 各データベースに対してクエリ実行

4. バージョン判定
   └─ compatibility_levelからバージョンを判定
   └─ 適切なクエリを選択

5. クエリ実行
   └─ server.Query()でT-SQL実行
   └─ ファイルグループフィルタ適用

6. 結果処理
   └─ サイズをdbasizeオブジェクトに変換
   └─ スパースファイルの場合はsize_on_disk_bytesを使用
   └─ ボリューム空き領域の取得（SQL 2008未満はxp_fixeddrives使用）

7. 出力
   └─ PSCustomObjectとして出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ準備]
    B --> C{InputObject指定?}
    C -->|No| D[Get-DbaDatabase呼び出し]
    C -->|Yes| E[InputObject使用]
    D --> E
    E --> F[データベースループ]
    F --> G[バージョン判定]
    G --> H{Version >= 11?}
    H -->|Yes| I[SQL 2008+クエリ]
    H -->|No| J{Version >= 9?}
    J -->|Yes| K[SQL 2005クエリ]
    J -->|No| L[SQL 2000クエリ]
    I --> M[クエリ実行]
    K --> M
    L --> M
    M --> N{FileGroup指定?}
    N -->|Yes| O[結果フィルタリング]
    N -->|No| P[結果処理]
    O --> P
    P --> Q[サイズ変換・出力]
    Q --> R{次のDB?}
    R -->|Yes| F
    R -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン別クエリ | SQL Serverバージョンに応じて適切なクエリを使用 | 全データベース |
| BR-002 | サイズ変換 | サイズは8192バイト（ページサイズ）倍して変換 | 全サイズ計算 |
| BR-003 | スパースファイル対応 | スパースファイルはsize_on_disk_bytesを使用 | IsSparse=True時 |
| BR-004 | ボリューム情報取得 | SQL 2008未満はxp_fixeddrivesで空き領域取得 | Version < 11 |
| BR-005 | MaxSize変換 | MaxSize=-1は無制限、それ以外は8192倍 | 全ファイル |

### 計算ロジック

サイズ変換：
```powershell
$size = [dbasize]($result.Size * 8192)
$usedspace = [dbasize]($result.UsedSpace * 8192)
```

次回成長イベントサイズ計算：
```powershell
if ($result.GrowthType -eq "Percent") {
    $nextgrowtheventadd = [dbasize]($result.size * 8 * ($result.Growth * 0.01) * 1024)
} else {
    $nextgrowtheventadd = [dbasize]($result.Growth * 1024)
}
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ファイル情報取得 | sys.database_files | SELECT | データベースファイル一覧 |
| ファイルグループ取得 | sys.filegroups | SELECT | ファイルグループ情報 |
| I/O統計取得 | sys.dm_io_virtual_file_stats | SELECT | ファイルI/O統計 |
| マスターファイル情報 | sys.master_files | SELECT | インスタンスレベルファイル情報 |
| ボリューム情報取得 | sys.dm_os_volume_stats | SELECT | ボリューム空き領域（SQL 2008+） |
| ドライブ情報取得 | xp_fixeddrives | EXEC | ドライブ空き領域（SQL 2008未満） |

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

#### sys.database_files + sys.filegroups

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, file_id, type, type_desc, state_desc, size, max_size, growth | 全ファイル | LEFTジョインでファイルグループと結合 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | QueryError | T-SQLクエリ実行失敗 | Stop-Function -Continueでスキップ |
| - | VersionError | compatibility_level取得失敗 | バージョン8として処理 |

### リトライ仕様

リトライ機能なし。エラー時は当該データベースをスキップして次を処理。

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

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

## パフォーマンス要件

- T-SQL直接クエリにより、SMOベースよりも高速
- 多数のデータベースを処理する場合、順次クエリ実行のため時間がかかる
- sys.dm_io_virtual_file_statsへのアクセスにより軽微なオーバーヘッド

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

- VIEW DATABASE STATE権限が必要
- xp_fixeddrivesの実行にはsysadmin権限推奨（SQL 2008未満）
- SqlCredentialパラメータでSQL認証、Windows認証、AD認証をサポート

## 備考

- サイズ関連プロパティはdbasizeオブジェクトとして返され、表示時に自動的にKB/MB/GB/TB単位でフォーマットされる
- FileGroupパラメータでファイルグループ単位のフィルタリングが可能
- SQL Server 2000互換クエリはsysfiles/sysfilegroupsを使用

---

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

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

### 推奨読解順序

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

T-SQLクエリとその結果構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbFile.ps1 | `public/Get-DbaDbFile.ps1` | 136-197行目のbeginブロック内SQLクエリ定義 |
| 1-2 | Get-DbaDbFile.ps1 | `public/Get-DbaDbFile.ps1` | 290-324行目の出力オブジェクト構造 |

**読解のコツ**: SQL Serverのファイル関連DMVとシステムビューの知識が必要。$sql、$sql2008、$sql2000の3種類のクエリを理解する。

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

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

**主要処理フロー**:
1. **201-203行目**: SqlInstance指定時はGet-DbaDatabase呼び出し
2. **205行目**: データベースループ開始

#### Step 3: バージョン判定とクエリ選択を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbFile.ps1 | `public/Get-DbaDbFile.ps1` | 210-223行目のバージョン判定ロジック |

**主要処理フロー**:
- **211-215行目**: compatibility_levelからバージョン計算
- **217-223行目**: バージョンに応じたクエリ選択

#### Step 4: サイズ計算ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaDbFile.ps1 | `public/Get-DbaDbFile.ps1` | 238-288行目のサイズ計算と変換ロジック |

**主要処理フロー**:
- **239-244行目**: Size、UsedSpace、AvailableSpaceの計算
- **248-252行目**: MaxSizeの変換（-1は無制限）
- **254-279行目**: VolumeFreeSpaceの取得（バージョン別）
- **281-288行目**: NextGrowthEventSizeの計算

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

```
Get-DbaDbFile
    │
    ├─ Get-DbaDatabase（SqlInstance指定時）
    │      └─ 対象データベース取得
    │
    ├─ server.Query() - compatibility_level取得
    │      └─ バージョン判定用
    │
    ├─ server.Query() - メインクエリ
    │      ├─ sys.database_files
    │      ├─ sys.filegroups
    │      ├─ sys.dm_io_virtual_file_stats
    │      ├─ sys.master_files
    │      └─ sys.dm_os_volume_stats (SQL 2008+)
    │
    └─ server.Query() - xp_fixeddrives (SQL 2008未満)
           └─ ドライブ空き領域取得
```

### データフロー図

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

SqlInstance/Database  ───▶ Get-DbaDatabase
                                 │
                                 ▼
                           バージョン判定
                                 │
                                 ▼
                           T-SQLクエリ実行
                                 │
                                 ▼
                           サイズ計算・変換          ───▶ PSCustomObject
                           (dbasize変換)                 - Size
                                                        - UsedSpace
                                                        - VolumeFreeSpace
                                                        - I/O統計
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbFile.ps1 | `public/Get-DbaDbFile.ps1` | ソース | メイン処理ロジック |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | 内部依存（データベース取得） |
| Get-DbaDbFileGroup.ps1 | `public/Get-DbaDbFileGroup.ps1` | ソース | 関連コマンド（ファイルグループ情報） |
| Get-DbaDbFileGrowth.ps1 | `public/Get-DbaDbFileGrowth.ps1` | ソース | 関連コマンド（成長設定の簡易取得） |
