# 機能設計書 650-Set-DbaDbFileGroup

## 概要

本ドキュメントは、SQL Serverデータベースのファイルグループプロパティを変更するdbatools PowerShellコマンド「Set-DbaDbFileGroup」の機能設計書です。

### 本機能の処理概要

Set-DbaDbFileGroupは、データベースファイルグループのデフォルト指定、読み取り専用状態、自動拡張動作などのプロパティを変更するコマンドです。

**業務上の目的・背景**：データベースのストレージ管理において、ファイルグループの設定を変更する必要があります。新しいオブジェクトのデフォルト格納先の変更、アーカイブデータの読み取り専用化、またはファイル成長パターンの最適化など、運用ニーズに応じた設定変更が必要です。本機能により、これらの設定変更を自動化し、複数データベースへの一括適用を効率化できます。

**機能の利用シーン**：
- デフォルトファイルグループの変更（新規テーブル作成先の指定）
- アーカイブデータの読み取り専用化
- 高トランザクションファイルグループの自動拡張最適化
- tempdbファイルグループの均等成長設定
- 複数データベースへの標準設定適用

**主要な処理内容**：
1. パラメータ検証（SqlInstance時はDatabase必須）
2. 対象データベースまたはファイルグループオブジェクトの取得
3. ファイルグループの存在確認と空でないことの確認
4. 指定されたプロパティの設定（Default, ReadOnly, AutoGrowAllFiles）
5. FileGroup.Alter() による変更適用

**関連システム・外部連携**：
- SQL Serverインスタンス（SMO）

**権限による制御**：対象データベースに対するALTER DATABASE権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI専用 | 主機能 | コマンドライン実行のみ |

## 機能種別

データ更新（DDL ALTER） / ストレージ構成管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | 対象SQL Serverインスタンス | InputObject未使用時に必要 |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| Database | string[] | 条件付き | 対象データベース名 | SqlInstance使用時に必要 |
| FileGroup | string[] | 条件付き | 変更するファイルグループ名 | Database使用時に必要 |
| Default | switch | No | このファイルグループをデフォルトに設定 | - |
| ReadOnly | switch | No | 読み取り専用状態を設定（:$true/:$false） | - |
| AutoGrowAllFiles | switch | No | 全ファイル自動拡張を設定（:$true/:$false） | - |
| InputObject | object[] | No | パイプラインからのデータベースまたはファイルグループオブジェクト | - |
| EnableException | switch | No | エラー時に例外をスロー | - |

### 入力データソース

- パイプライン入力:
  - Get-DbaDatabase からのデータベースオブジェクト
  - Get-DbaDbFileGroup からのファイルグループオブジェクト
- 直接パラメータ指定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | ファイルグループ名 |
| IsDefault | bool | デフォルトファイルグループかどうか |
| ReadOnly | bool | 読み取り専用かどうか |
| AutogrowAllFiles | bool | 全ファイル自動拡張が有効かどうか |
| ID | int | ファイルグループID |
| Parent | Database | 親データベースオブジェクト |
| Files | DataFileCollection | ファイルグループ内のファイルコレクション |
| FileGroupType | FileGroupType | ファイルグループタイプ |
| Urn | string | オブジェクトのURN |
| State | string | SMOオブジェクトの状態 |

### 出力先

パイプライン出力（Microsoft.SqlServer.Management.Smo.FileGroup）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance指定時はDatabase必須チェック

2. 入力オブジェクトの収集
   ├─ SqlInstance指定時: Get-DbaDatabase で取得
   └─ InputObject: そのまま使用

3. 変更対象ファイルグループの特定
   ├─ Databaseオブジェクト入力時:
   │   ├─ FileGroup必須チェック
   │   └─ FileGroups[$FileGroup]を収集
   └─ FileGroupオブジェクト入力時:
       └─ そのまま使用

4. 各ファイルグループの変更処理
   ├─ 空のファイルグループ: Stop-Function でスキップ
   └─ 変更処理
       ├─ Default指定時: IsDefault = $true
       ├─ ReadOnly指定時: ReadOnly = $ReadOnly値
       ├─ AutoGrowAllFiles指定時: AutogrowAllFiles = $AutoGrowAllFiles値
       └─ FileGroup.Alter() 実行
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C{Database指定?}
    C -->|No| D[エラー終了]
    C -->|Yes| E[Get-DbaDatabase]
    B -->|No| F[InputObject使用]
    E --> G[InputObjectに追加]
    F --> H[オブジェクトループ]
    G --> H
    H --> I{オブジェクトの型?}
    I -->|Database| J{FileGroup指定?}
    J -->|No| K[エラー: FileGroup必須]
    J -->|Yes| L[FileGroup存在確認]
    L --> M{存在?}
    M -->|No| N[エラー: 存在しない]
    M -->|Yes| O[変更リストに追加]
    I -->|FileGroup| O
    K --> P{次オブジェクト?}
    N --> P
    O --> P
    P -->|Yes| H
    P -->|No| Q[変更リストループ]
    Q --> R{ファイルあり?}
    R -->|No| S[エラー: 空]
    R -->|Yes| T{ShouldProcess?}
    S --> U{次FG?}
    T -->|No| U
    T -->|Yes| V[プロパティ設定]
    V --> W[FileGroup.Alter]
    W --> X{成功?}
    X -->|No| Y[エラー出力]
    X -->|Yes| Z[FileGroup出力]
    Y --> U
    Z --> U
    U -->|Yes| Q
    U -->|No| AA[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 空チェック | ファイルグループ内にファイルがない場合は設定変更不可 | 常時 |
| BR-002 | 存在チェック | 指定されたファイルグループがデータベースに存在しない場合はエラー | 常時 |
| BR-003 | FileGroup必須 | Databaseオブジェクト入力時はFileGroupパラメータが必須 | Databaseオブジェクト入力時 |
| BR-004 | Default単方向 | Defaultは$trueに設定のみ（$falseは指定不要、他FGをDefaultに設定すれば自動解除） | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ファイルグループ設定変更 | sys.filegroups | DDL ALTER | ALTER DATABASE MODIFY FILEGROUP相当 |

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

#### sys.filegroups（メタデータ）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | is_default | Default指定時に1 | SMO経由で自動 |
| UPDATE | is_read_only | ReadOnly指定値 | SMO経由で自動 |
| UPDATE | is_autogrow_all_files | AutoGrowAllFiles指定値 | SMO経由で自動 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ValidationError | SqlInstance指定時にDatabase未指定 | Databaseを指定 |
| - | ValidationError | Databaseオブジェクト入力時にFileGroup未指定 | FileGroupを指定 |
| - | NotFoundError | 指定ファイルグループが存在しない | 正しいファイルグループ名を指定 |
| - | EmptyError | ファイルグループにファイルがない | 先にファイルを追加 |
| - | AlterError | 設定変更失敗 | 権限と依存関係を確認 |

### リトライ仕様

リトライなし（ファイルグループ単位でContinueしてスキップ）

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

SMO FileGroup.Alter() はDDL操作として暗黙的コミット

## パフォーマンス要件

- 通常100ms以下でファイルグループ設定変更完了

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

- 対象データベースに対するALTER DATABASE権限が必要
- ShouldProcess対応（WhatIf/Confirm）
- ConfirmImpact = "High"（確認プロンプト表示）

## 備考

- ReadOnlyとAutoGrowAllFilesはswitch型のため、:$true/:$falseで明示的に値を指定可能
- Defaultスイッチは$true設定のみ（別のファイルグループをDefaultにすれば自動的に解除される）

---

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

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

### 推奨読解順序

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

出力されるSMO FileGroupオブジェクトの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaDbFileGroup.ps1 | `public/Set-DbaDbFileGroup.ps1` | L185の FileGroup オブジェクト出力 |

**読解のコツ**: 出力はSMO FileGroupオブジェクトそのもので、Alter()適用後の状態が返されます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaDbFileGroup.ps1 | `public/Set-DbaDbFileGroup.ps1` | processブロック全体の流れ |

**主要処理フロー**:
1. **132-135行目**: SqlInstance時のDatabase必須チェック
2. **137-139行目**: Get-DbaDatabase でデータベース取得
3. **143-162行目**: 入力オブジェクトの型判定と変更リスト構築
4. **164-190行目**: 変更処理ループ

#### Step 3: プロパティ設定ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaDbFileGroup.ps1 | `public/Set-DbaDbFileGroup.ps1` | L172-184のプロパティ設定 |

**主要処理フロー**:
- **172-174行目**: Default設定（Test-Boundで指定有無確認）
- **176-178行目**: ReadOnly設定（switch値をそのまま適用）
- **180-182行目**: AutoGrowAllFiles設定
- **184行目**: FileGroup.Alter() 実行

#### Step 4: 入力オブジェクト処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaDbFileGroup.ps1 | `public/Set-DbaDbFileGroup.ps1` | L143-162の型判定 |

**主要処理フロー**:
- **145行目**: Databaseオブジェクト判定
- **147-149行目**: FileGroup必須チェック
- **151-155行目**: ファイルグループ存在確認と収集
- **159-161行目**: FileGroupオブジェクトの直接追加

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

```
Set-DbaDbFileGroup
    │
    ├─ Get-DbaDatabase（データベースオブジェクト取得）
    │      └─ Connect-DbaInstance
    │
    ├─ 型判定
    │      ├─ Microsoft.SqlServer.Management.Smo.Database
    │      └─ Microsoft.SqlServer.Management.Smo.FileGroup
    │
    └─ SMO FileGroup操作
           ├─ IsDefault設定
           ├─ ReadOnly設定
           ├─ AutogrowAllFiles設定
           └─ FileGroup.Alter()
```

### データフロー図

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

SqlInstance ──────────┐
                      │
Database ─────────────┼──▶ Get-DbaDatabase ─────────┐
                      │                              │
FileGroup ────────────┤                              ▼
                      │    ┌───────────────────────────────┐
Default ──────────────┤    │ 型判定                        │
                      │    │ ├─ Database → FileGroups取得   │
ReadOnly ─────────────┤    │ └─ FileGroup → そのまま使用    │
                      │    └───────────────────────────────┘
AutoGrowAllFiles ─────┤                    │
                      │                    ▼
InputObject ──────────┘    ┌───────────────────────────────┐
                           │ プロパティ設定                 │
                           │ ├─ IsDefault = true           │
                           │ ├─ ReadOnly = 指定値          │
                           │ └─ AutogrowAllFiles = 指定値  │
                           └───────────────────────────────┘
                                         │
                                         ▼
                                FileGroup.Alter()
                                         │
                                         ▼
                           Microsoft.SqlServer.Management.Smo.FileGroup
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaDbFileGroup.ps1 | `public/Set-DbaDbFileGroup.ps1` | ソース | メインコマンド実装 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Get-DbaDbFileGroup.ps1 | `public/Get-DbaDbFileGroup.ps1` | ソース | ファイルグループオブジェクト取得 |
| New-DbaDbFileGroup.ps1 | `public/New-DbaDbFileGroup.ps1` | ソース | ファイルグループ作成 |
| Remove-DbaDbFileGroup.ps1 | `public/Remove-DbaDbFileGroup.ps1` | ソース | ファイルグループ削除 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
