# 機能設計書 647-New-DbaDbFileGroup

## 概要

本ドキュメントは、SQL Serverデータベースに新しいファイルグループを作成するdbatools PowerShellコマンド「New-DbaDbFileGroup」の機能設計書です。

### 本機能の処理概要

New-DbaDbFileGroupは、指定されたデータベースに新しいファイルグループを作成するコマンドです。標準の行データ用、FileStream用、メモリ最適化用の3種類のファイルグループタイプをサポートします。

**業務上の目的・背景**：データベースのストレージ設計において、ファイルグループを使用してテーブルやインデックスを異なるディスクドライブに分散させることで、I/Oパフォーマンスを最適化できます。また、部門別やコンプライアンス要件に応じたデータ分離も可能になります。本機能により、ファイルグループの作成を自動化し、複数データベースへの一括適用を効率化できます。

**機能の利用シーン**：
- 新規データベース構築時のストレージ設計
- パフォーマンス最適化のためのファイルグループ追加
- FileStreamデータ格納用ファイルグループの作成
- インメモリOLTP用ファイルグループの作成
- 複数データベースへの標準ファイルグループ構成の適用

**主要な処理内容**：
1. パラメータ検証（FileGroup必須、SqlInstance時はDatabase必須）
2. 対象データベースの取得
3. 既存ファイルグループとの重複確認
4. SMO FileGroupオブジェクトの作成と設定
5. FileGroup.Create()メソッドによるファイルグループ作成

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

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

## 関連画面

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

## 機能種別

データ作成（DDL） / ストレージ構成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | 対象SQL Serverインスタンス | InputObject未使用時に必要 |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| Database | string[] | 条件付き | 対象データベース名 | SqlInstance使用時に必要 |
| FileGroup | string | Yes | 作成するファイルグループ名 | 一意であること |
| FileGroupType | string | No | ファイルグループタイプ（デフォルト: RowsFileGroup） | RowsFileGroup/FileStreamDataFileGroup/MemoryOptimizedDataFileGroup |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | パイプラインからのデータベースオブジェクト | - |
| EnableException | switch | No | エラー時に例外をスロー | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Parent | Database | 親データベースオブジェクト |
| FileGroupType | FileGroupType | ファイルグループタイプ |
| Name | string | ファイルグループ名 |
| Size | int | ファイルグループサイズ（KB） |
| IsDefault | bool | デフォルトファイルグループかどうか |
| State | string | ファイルグループの状態 |
| Files | DataFileCollection | ファイルグループ内のファイルコレクション |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

2. データベースオブジェクトの取得
   └─ SqlInstance指定時: Get-DbaDatabase で取得

3. 各データベースに対してループ
   ├─ 既存ファイルグループ名との重複確認
   │   └─ 重複時: Stop-Function でスキップ
   ├─ FileGroupオブジェクト作成
   │   └─ New-Object Microsoft.SqlServer.Management.Smo.FileGroup
   ├─ FileGroupType設定
   └─ FileGroup.Create() 実行
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{FileGroup指定?}
    B -->|No| C[エラー終了]
    B -->|Yes| D{SqlInstance指定?}
    D -->|Yes| E{Database指定?}
    E -->|No| C
    E -->|Yes| F[Get-DbaDatabase]
    D -->|No| G[InputObject使用]
    F --> H[データベースループ]
    G --> H
    H --> I{ファイルグループ存在?}
    I -->|Yes| J[Stop-Function]
    I -->|No| K{ShouldProcess?}
    J --> L{次DB?}
    K -->|No| L
    K -->|Yes| M[New-Object FileGroup]
    M --> N[FileGroupType設定]
    N --> O[FileGroup.Create]
    O --> P{成功?}
    P -->|No| Q[Stop-Function]
    P -->|Yes| R[FileGroup出力]
    Q --> L
    R --> L
    L -->|Yes| H
    L -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ファイルグループ一意性 | 同一データベース内でファイルグループ名は一意である必要がある | 常時 |
| BR-002 | デフォルトタイプ | FileGroupType未指定時はRowsFileGroupを使用 | FileGroupType未指定時 |
| BR-003 | 空のファイルグループ | 作成されるファイルグループは空（ファイルなし）で作成される | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ファイルグループ作成 | sys.filegroups | DDL CREATE | ALTER DATABASE ADD FILEGROUP相当 |

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | FileGroupパラメータ値 | SMO経由で自動 |
| INSERT | type | FileGroupTypeに対応する値 | 0=ROWS, 2=FILESTREAM, 4=MEMORY_OPTIMIZED |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ValidationError | FileGroup未指定 | FileGroupを指定 |
| - | ValidationError | SqlInstance指定時にDatabase未指定 | Databaseを指定 |
| - | DuplicateError | 同名のファイルグループが存在 | 異なる名前を使用 |
| - | CreateError | ファイルグループ作成失敗 | 権限とデータベース状態を確認 |

### リトライ仕様

リトライなし（データベース単位でContinueしてスキップ）

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

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

## パフォーマンス要件

- 通常100ms以下でファイルグループ作成完了

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

- 対象データベースに対するALTER DATABASE権限が必要
- ShouldProcess対応（WhatIf/Confirm）

## 備考

- ファイルグループ作成後、Add-DbaDbFileでデータファイルを追加する必要がある
- ConfirmImpact = "Low"

---

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

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

### 推奨読解順序

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

SMO FileGroupオブジェクトの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaDbFileGroup.ps1 | `public/New-DbaDbFileGroup.ps1` | L135の New-Object FileGroup |

**読解のコツ**: 出力はSMO FileGroupオブジェクトそのもので、追加のラッピングはありません。

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

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

**主要処理フロー**:
1. **113-116行目**: FileGroup必須チェック
2. **118-121行目**: SqlInstance時のDatabase必須チェック
3. **123-125行目**: Get-DbaDatabase でデータベース取得
4. **127-131行目**: 既存ファイルグループとの重複確認
5. **133-145行目**: FileGroup作成処理

#### Step 3: FileGroup作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbFileGroup.ps1 | `public/New-DbaDbFileGroup.ps1` | L133-145の作成処理 |

**主要処理フロー**:
- **135行目**: New-Object Microsoft.SqlServer.Management.Smo.FileGroup
- **137-139行目**: FileGroupType設定
- **141行目**: FileGroup.Create() 実行
- **142行目**: 作成したFileGroupオブジェクトを出力

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

```
New-DbaDbFileGroup
    │
    ├─ Get-DbaDatabase（データベースオブジェクト取得）
    │      └─ Connect-DbaInstance
    │
    └─ SMO FileGroup操作
           ├─ New-Object FileGroup
           └─ FileGroup.Create()
```

### データフロー図

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

SqlInstance ──────────┐
                      │
Database ─────────────┼──▶ Get-DbaDatabase ─────────┐
                      │                              │
FileGroup ────────────┤                              ▼
                      │    ┌───────────────────────────────┐
FileGroupType ────────┤    │ New-Object FileGroup          │
                      │    │ FileGroupType設定             │
InputObject ──────────┘    │ FileGroup.Create()            │
                           └───────────────────────────────┘
                                         │
                                         ▼
                           Microsoft.SqlServer.Management.Smo.FileGroup
```

### 関連ファイル一覧

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