# 画面設計書：25-データベースファイル管理

## 1. 基本情報

| 項目 | 内容 |
|------|------|
| 画面ID | 25 |
| 画面名 | データベースファイル管理 |
| カテゴリ | データベース |
| 対応コマンド | Get-DbaDbFile |
| 関連機能No | 109 |

## 2. 概要・目的

データベースファイル（データファイル・ログファイル）の詳細情報を取得する機能です。ファイルサイズ、使用領域、成長設定、I/O統計、ボリューム空き容量など、容量計画やパフォーマンス分析に必要な情報を包括的に提供します。

SMOベースのアプローチではなくT-SQLクエリを直接実行し、高速なファイル情報取得を実現しています。

## 3. 機能説明

### 3.1 主要機能

- **ファイル情報取得**: データファイル・ログファイルの詳細情報
- **サイズ情報**: 現在サイズ、使用領域、空き領域、最大サイズ
- **成長設定**: 自動拡張設定（固定/パーセント）
- **I/O統計**: 読み取り/書き込み回数・バイト数
- **ボリューム情報**: ファイルが存在するボリュームの空き容量
- **ファイルグループ情報**: 所属ファイルグループの詳細

### 3.2 SQLバージョン対応

| バージョン | 対応内容 |
|-----------|---------|
| SQL 2012以上 (compat 110+) | dm_os_volume_stats使用でボリューム情報取得 |
| SQL 2005-2008R2 (compat 90-100) | 基本クエリのみ（ボリューム情報なし） |
| SQL 2000 (compat 80) | レガシークエリ（sysfiles/sysfilegroups使用） |

## 4. パラメータ仕様

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | No | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | - | 認証資格情報 |
| Database | object[] | No | - | 対象データベース（ワイルドカード対応） |
| ExcludeDatabase | object[] | No | - | 除外データベース（ワイルドカード対応） |
| FileGroup | object[] | No | - | フィルタ対象ファイルグループ名 |
| InputObject | Database[] | No | - | パイプライン入力（Get-DbaDatabase等から） |
| EnableException | switch | No | $false | 例外を有効化 |

## 5. 出力仕様

**型**: PSCustomObject

| プロパティ | 型 | 説明 |
|-----------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| DatabaseID | int | データベースID |
| FileGroupName | string | ファイルグループ名（ログファイルはNULL） |
| ID | int | ファイルID |
| Type | int | ファイルタイプ（0=データ、1=ログ） |
| TypeDescription | string | タイプ説明（ROWS/LOG） |
| LogicalName | string | 論理ファイル名 |
| PhysicalName | string | 物理パス |
| State | string | ファイル状態（ONLINE/OFFLINE等） |
| MaxSize | dbasize | 最大サイズ |
| Growth | int | 成長増分値 |
| GrowthType | string | 成長タイプ（Percent/kb） |
| NextGrowthEventSize | dbasize | 次回拡張サイズ |
| Size | dbasize | 現在サイズ |
| UsedSpace | dbasize | 使用領域 |
| AvailableSpace | dbasize | 空き領域 |
| IsOffline | bool | オフラインフラグ |
| IsReadOnly | bool | 読み取り専用フラグ |
| IsReadOnlyMedia | bool | メディア読み取り専用フラグ |
| IsSparse | bool | スパースファイルフラグ |
| NumberOfDiskWrites | long | ディスク書き込み回数 |
| NumberOfDiskReads | long | ディスク読み取り回数 |
| ReadFromDisk | dbasize | 読み取りバイト数 |
| WrittenToDisk | dbasize | 書き込みバイト数 |
| VolumeFreeSpace | dbasize | ボリューム空き容量 |
| FileGroupDataSpaceId | int | ファイルグループデータスペースID |
| FileGroupType | string | ファイルグループタイプ |
| FileGroupTypeDescription | string | ファイルグループタイプ説明 |
| FileGroupDefault | bool | デフォルトファイルグループフラグ |
| FileGroupReadOnly | bool | ファイルグループ読み取り専用フラグ |

## 6. 処理フロー

```
[開始]
    |
    v
[SqlInstance指定時]
    | - Get-DbaDatabase呼び出し
    | - InputObjectに追加
    v
[データベースループ]
    |
    v
[互換性レベル取得]
    | - sys.databasesからcompatibility_level取得
    | - バージョン判定（11以上/9以上/8）
    v
[クエリ選択]
    | - version >= 11: $sql + $sql2008 + $sqlfrom + $sql2008from
    | - version >= 9:  $sql + $sqlfrom
    | - version < 9:   $sql2000
    v
[クエリ実行]
    | - $server.Query($query, $db.Name)
    v
[FileGroupフィルタ（オプション）]
    | - FileGroup指定時のみフィルタリング
    v
[結果処理ループ]
    | - サイズ計算（8192バイト単位）
    | - スパースファイル対応
    | - ボリューム空き容量取得
    | - 次回拡張サイズ計算
    v
[PSCustomObject出力]
    |
    v
[終了]
```

## 7. 内部実装詳細

### 7.1 メインクエリ（SQL 2005以上）

```sql
-- Get-DbaDbFile.ps1 行136-162
SELECT
    fg.name AS FileGroupName,
    df.file_id AS 'ID',
    df.Type,
    df.type_desc AS TypeDescription,
    df.name AS LogicalName,
    mf.physical_name AS PhysicalName,
    df.state_desc AS State,
    df.max_size AS MaxSize,
    CASE mf.is_percent_growth WHEN 1 THEN df.growth
         ELSE df.Growth*8 END AS Growth,
    COALESCE(FILEPROPERTY(df.name, 'spaceused'), 0) AS UsedSpace,
    df.size AS Size,
    ...
FROM sys.database_files df
LEFT OUTER JOIN sys.filegroups fg ON df.data_space_id=fg.data_space_id
LEFT JOIN sys.dm_io_virtual_file_stats(DB_ID(),NULL) vfs ON df.file_id=vfs.file_id
INNER JOIN sys.master_files mf ON df.file_id = mf.file_id AND mf.database_id = DB_ID()
```

### 7.2 ボリューム情報取得（SQL 2012以上）

```sql
-- Get-DbaDbFile.ps1 行170-171
CROSS APPLY sys.dm_os_volume_stats(DB_ID(), df.file_id) vs
-- vs.available_bytes AS 'VolumeFreeSpace'
```

### 7.3 レガシークエリ（SQL 2000）

```sql
-- Get-DbaDbFile.ps1 行173-196
SELECT
    fg.groupname AS FileGroupName,
    df.fileid AS ID,
    CONVERT(INT,df.status & 0x40) / 64 AS Type,
    ...
FROM sysfiles df
LEFT OUTER JOIN sysfilegroups fg ON df.groupid=fg.groupid
```

### 7.4 サイズ計算ロジック

```powershell
# Get-DbaDbFile.ps1 行239-252
$size = [dbasize]($result.Size * 8192)  # 8KBページ単位
$usedspace = [dbasize]($result.UsedSpace * 8192)
$AvailableSpace = $size - $usedspace

# スパースファイル/スナップショット対応
if ($result.size_on_disk_bytes) {
    $size = [dbasize]($result.size_on_disk_bytes)
}

# 最大サイズ処理（-1は無制限）
if ($maxsize -gt -1) {
    $maxsize = [dbasize]($result.MaxSize * 8192)
}
```

### 7.5 次回拡張サイズ計算

```powershell
# Get-DbaDbFile.ps1 行281-288
if ($result.GrowthType -eq "Percent") {
    $nextgrowtheventadd = [dbasize]($result.size * 8 * ($result.Growth * 0.01) * 1024)
} else {
    $nextgrowtheventadd = [dbasize]($result.Growth * 1024)
}
# 最大サイズ超過時は0
if (($nextgrowtheventadd.Byte -gt ($MaxSize.Byte - $size.Byte)) -and $maxsize -gt 0) {
    $nextgrowtheventadd = 0
}
```

### 7.6 ボリューム空き容量取得（フォールバック）

SQL 2012未満でボリューム情報を取得するフォールバック処理:

```powershell
# Get-DbaDbFile.ps1 行257-279
$query2 = @'
DECLARE @FixedDrives TABLE(Drive CHAR(1), MB_Free BIGINT);
INSERT @FixedDrives EXEC sys.xp_fixeddrives;

SELECT DISTINCT fd.MB_Free, LEFT(df.physical_name, 1) AS [Drive]
FROM @FixedDrives AS fd
INNER JOIN sys.database_files AS df
ON fd.Drive = LEFT(df.physical_name, 1);
'@
```

## 8. 使用例

### 8.1 基本的な使用

```powershell
# インスタンス上の全データベースファイル情報を取得
Get-DbaDbFile -SqlInstance sql2016
```

### 8.2 特定データベースの指定

```powershell
# 特定データベースのファイル情報を取得
Get-DbaDbFile -SqlInstance sql2016 -Database Impromptu
```

### 8.3 複数データベースの指定

```powershell
# 複数データベースのファイル情報を取得
Get-DbaDbFile -SqlInstance sql2016 -Database Impromptu, Trading
```

### 8.4 パイプライン入力

```powershell
# Get-DbaDatabase からパイプライン入力
Get-DbaDatabase -SqlInstance sql2016 -Database Impromptu, Trading | Get-DbaDbFile
```

### 8.5 ファイルグループフィルタ

```powershell
# 特定ファイルグループのファイルのみ取得
Get-DbaDbFile -SqlInstance sql2016 -Database AdventureWorks2017 -FileGroup Index
```

## 9. エラーハンドリング

| エラー状況 | 処理 | ソース位置 |
|-----------|------|-----------|
| 互換性レベル取得失敗 | バージョン8として処理 | Get-DbaDbFile.ps1 行213-215 |
| クエリ実行失敗 | Stop-Function -Continue | Get-DbaDbFile.ps1 行229-231 |

## 10. 関連コマンド

| コマンド | 関係 | 説明 |
|---------|------|------|
| Get-DbaDatabase | 内部使用 | データベースオブジェクト取得 |
| Get-DbaDbSpace | 関連 | データベース領域情報取得 |
| Expand-DbaDbLogFile | 関連 | ログファイル拡張 |
| Set-DbaDbFileGrowth | 関連 | ファイル成長設定変更 |

## 11. 注意事項・制約

1. **dbasize型**: サイズ関連プロパティはdbasizeオブジェクト（自動フォーマット対応）
2. **ページサイズ**: SQL Serverは8KB（8192バイト）ページを使用
3. **スパースファイル**: スナップショットDBではsize_on_disk_bytesを使用
4. **ボリューム情報**: SQL 2012以上はdm_os_volume_stats、2008以下はxp_fixeddrives使用
5. **I/O統計**: インスタンス起動後からの累積値

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

### 12.1 関連ファイル一覧

| ファイル | 種類 | 行数 | 説明 |
|---------|------|------|------|
| public/Get-DbaDbFile.ps1 | メインコマンド | 328 | データベースファイル情報取得 |

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

```
Get-DbaDbFile
    |
    +-- Get-DbaDatabase (InputObject取得, 行202)
    |       |
    |       +-- Connect-DbaInstance
    |
    +-- $server.Query (互換性レベル取得, 行211)
    +-- $server.Query (メインクエリ実行, 行228)
    +-- $server.Query (xp_fixeddrives, 行271)
    +-- Write-Message (ログ出力)
```

### 12.3 データフロー図

```
[SqlInstance / InputObject]
    |
    v
[Get-DbaDatabase]
    |
    | Database SMOオブジェクト
    v
[バージョン判定クエリ]
    | SELECT compatibility_level FROM sys.databases
    v
[バージョンに応じたクエリ選択]
    |
    +-- version >= 11 --> $sql + $sql2008 (dm_os_volume_stats)
    +-- version >= 9  --> $sql (基本クエリのみ)
    +-- version < 9   --> $sql2000 (sysfiles/sysfilegroups)
    |
    v
[クエリ結果]
    |
    | sys.database_files + sys.filegroups + dm_io_virtual_file_stats + sys.master_files
    v
[サイズ変換・計算]
    |
    | 8192バイト単位 -> dbasize変換
    | 次回拡張サイズ計算
    | ボリューム空き容量取得
    v
[PSCustomObject出力]
```

### 12.4 読み解きの流れ

1. **beginブロック (行134-198)**
   - SQL 2005以上用クエリ定義（$sql, $sqlfrom）
   - SQL 2012以上用追加クエリ（$sql2008, $sql2008from）
   - SQL 2000用レガシークエリ（$sql2000）

2. **processブロック (行200-327)**
   - SqlInstance指定時のGet-DbaDatabase呼び出し（行201-203）
   - データベースループ開始（行205）
   - 互換性レベル取得とバージョン判定（行210-215）
   - クエリ選択と実行（行217-231）
   - FileGroupフィルタ（行233-236）
   - 結果処理とPSCustomObject生成（行238-325）

## 13. 改訂履歴

| 日付 | バージョン | 変更内容 |
|------|-----------|---------|
| 2026-02-18 | 1.0 | 初版作成 |
