# 機能設計書 634-Get-DbaDbFileGroup

## 概要

本ドキュメントは、dbatools PowerShellモジュールのGet-DbaDbFileGroupコマンドレットの機能設計書である。このコマンドは、SQL Serverデータベースのファイルグループ構成と詳細情報を取得し、ストレージ組織の分析、容量計画、構成ドキュメント作成を支援する。

### 本機能の処理概要

Get-DbaDbFileGroupは、1つ以上のデータベースからファイルグループの詳細情報を取得する。ファイルグループタイプ、サイズ、構成詳細を含む情報を返し、データベースストレージ構造の分析やドキュメント作成に役立つ。特定のファイルグループ名でフィルタリングできるため、対象を絞ったストレージ分析やパフォーマンス問題のトラブルシューティングに有用である。

**業務上の目的・背景**：SQL Serverのファイルグループは、データファイルの論理的なグループ化を提供し、バックアップ、リストア、パフォーマンス最適化の単位となる。DBAは定期的にファイルグループの構成を確認し、ストレージ容量計画、移行準備、コンプライアンスドキュメント作成を行う必要がある。このコマンドは、これらの作業を効率化する。

**機能の利用シーン**：
- データベースストレージ構造の監査・ドキュメント化
- ファイルグループ単位の容量計画
- パフォーマンス問題のトラブルシューティング（データ分散の確認）
- データベース移行前の構造分析
- 特定ファイルグループの設定確認（PRIMARY、FILESTREAM等）

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続し、データベースを取得
2. 各データベースのFilegroupsコレクションを列挙
3. ファイルグループ名でフィルタリング（指定時）
4. SMO FileGroupオブジェクトにカスタムプロパティを追加
5. Select-DefaultViewで既定の表示プロパティを設定して出力

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

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

## 関連画面

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

## 機能種別

データ取得 / SMOオブジェクト列挙

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名（サービス名） |
| SqlInstance | String | 完全なSQL Serverインスタンス名（ドメイン\インスタンス） |
| Parent | String | 親データベースオブジェクト名 |
| FileGroupType | String | ファイルグループタイプ（RowsFileGroup、FileStreamFileGroup、MemoryOptimizedFileGroup） |
| Name | String | ファイルグループ名（PRIMARY、SECONDARY、FILESTREAM等） |
| Size | Int | ファイルグループの合計サイズ（キロバイト） |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.FileGroupオブジェクト拡張版）

## 処理フロー

### 処理シーケンス

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

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

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

4. ファイルグループ取得
   └─ db.Filegroupsコレクションから取得
   └─ Databaseパラメータで追加フィルタ（指定時）

5. ファイルグループフィルタリング
   └─ FileGroupパラメータで名前フィルタ（指定時）

6. プロパティ追加と出力
   └─ ComputerName、InstanceName、SqlInstanceを追加
   └─ Select-DefaultViewで既定プロパティを設定して出力
```

### フローチャート

```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[Filegroupsコレクション取得]
    I --> K{次のDB?}
    J --> L{FileGroup指定?}
    L -->|Yes| M[名前フィルタリング]
    L -->|No| N[ファイルグループループ]
    M --> N
    N --> O[プロパティ追加]
    O --> P[Select-DefaultView出力]
    P --> Q{次のFG?}
    Q -->|Yes| N
    Q -->|No| K
    K -->|Yes| G
    K -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 必須パラメータ確認 | SqlInstanceまたはInputObjectのいずれかが必要 | 処理開始時 |
| BR-002 | アクセス可能性確認 | IsAccessible=Falseのデータベースはスキップ | 各データベース処理時 |
| BR-003 | ファイルグループフィルタ | FileGroupパラメータ指定時は名前でフィルタ | FileGroup指定時 |
| BR-004 | SMOオブジェクト拡張 | FileGroupオブジェクトにComputerName等を追加 | 各ファイルグループ出力時 |

### 計算ロジック

ファイルグループサイズはSMO FileGroupオブジェクトのSizeプロパティから取得（キロバイト単位）。

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

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

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

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, type, type_desc, data_space_id | 全ファイルグループ | SMO Filegroupsコレクション経由 |

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

- SMOを使用するため、初回アクセス時に若干のオーバーヘッドが発生
- 大量のデータベースを処理する場合、順次処理のため時間がかかる
- FileGroupパラメータで対象を絞ることで性能改善可能

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

- 対象データベースへのアクセス権限が必要
- SqlCredentialパラメータでSQL認証、Windows認証、AD認証をサポート
- MFA対応の場合はConnect-DbaInstanceを事前に使用することを推奨

## 備考

- 出力されるFileGroupオブジェクトにはFilesコレクションが含まれ、各ファイルグループ内のデータファイル一覧にアクセス可能
- FileGroupType値：RowsFileGroup（通常データ）、FileStreamFileGroup（FILESTREAM）、MemoryOptimizedFileGroup（インメモリOLTP）
- システムデータベースを除外したい場合はGet-DbaDatabase -ExcludeSystemとパイプライン連携

---

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

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

### 推奨読解順序

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

SMO FileGroupオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbFileGroup.ps1 | `public/Get-DbaDbFileGroup.ps1` | 140行目のdefaultprops配列 |

**読解のコツ**: 出力はSMO FileGroupオブジェクトにNotePropertyを追加したもの。Select-DefaultViewで既定の表示プロパティを制限している。

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

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

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

#### Step 3: ファイルグループ処理ロジックを理解する

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

**主要処理フロー**:
- **122行目**: IsAccessibleチェック
- **125-127行目**: Databaseパラメータによる追加フィルタ
- **128行目**: Filegroupsコレクション取得
- **130-132行目**: FileGroupパラメータによるフィルタ
- **136-138行目**: NoteProperty追加

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

```
Get-DbaDbFileGroup
    │
    ├─ Test-Bound
    │      └─ パラメータ指定確認
    │
    ├─ Get-DbaDatabase（InputObject未指定時）
    │      └─ 対象データベース取得
    │
    ├─ Write-Message
    │      └─ Verbose/Warningログ出力
    │
    └─ Select-DefaultView
           └─ 出力プロパティフィルタリング
```

### データフロー図

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

SqlInstance/Database  ───▶ Get-DbaDatabase
                                 │
                                 ▼
                           Filegroupsコレクション取得
                                 │
                                 ▼
                           フィルタリング              ───▶ FileGroup +
                           (FileGroupパラメータ)            ComputerName
                                 │                          InstanceName
                                 ▼                          SqlInstance
                           プロパティ追加
                           (Add-Member)
```

### 関連ファイル一覧

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