# 機能設計書 625-Add-DbaDbFile

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Add-DbaDbFile`コマンドレットに関する機能設計書である。このコマンドレットは、SQL Serverデータベースの既存ファイルグループにデータファイルを追加する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：データベースのストレージ拡張、パフォーマンス向上のための複数ファイル構成、In-Memory OLTP用のMemoryOptimizedDataFileGroup設定など、ファイルグループへのデータファイル追加は重要な管理タスクである。特にMemoryOptimizedDataFileGroupはファイルが追加されるまでデータを格納できないため、この機能は必須である。

**機能の利用シーン**：
- 新規ファイルグループ作成後のデータファイル追加
- In-Memory OLTP用コンテナの追加
- I/O分散のための複数ファイル構成
- ストレージ容量の拡張

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続確立
2. 指定されたデータベースとファイルグループの確認
3. MemoryOptimizedDataFileGroupの場合はSQL Server 2014以上のチェック
4. ファイル名の自動生成（未指定時）
5. 論理名の重複チェック
6. ファイルパスの決定（未指定時はデフォルトデータディレクトリ）
7. DataFileオブジェクトの作成とプロパティ設定
8. ファイルグループへの追加とAlter()実行

**関連システム・外部連携**：SQL Server Management Objects (SMO)を使用してSQL Serverと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主画面 | PowerShellコンソールからの実行 |

## 機能種別

CRUD操作（Create）/ DDL実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| Database | string[] | 条件付き | 対象データベース名（SqlInstance指定時は必須） | SqlInstance指定時に必須 |
| FileGroup | string | Yes | ファイルを追加するファイルグループ名 | 存在するファイルグループ |
| FileName | string | No | データファイルの論理名（未指定時は自動生成） | ファイルグループ内で一意 |
| Path | string | No | ファイルの物理パス（未指定時はデフォルトパス） | - |
| Size | int | No | 初期サイズ（MB単位、デフォルト: 128） | 正の整数 |
| Growth | int | No | 拡張サイズ（MB単位、デフォルト: 64） | 正の整数 |
| MaxSize | int | No | 最大サイズ（MB単位、デフォルト: -1=無制限） | -1または正の整数 |
| InputObject | Database[] | No | パイプライン入力用データベースオブジェクト | - |
| EnableException | switch | No | 例外処理モード切替 | - |

### 入力データソース

- PowerShellコマンドラインからのパラメータ入力
- パイプラインからのGet-DbaDatabase出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | データファイルの論理名 |
| FileName | string | 物理ファイルパス |
| Size | long | ファイルサイズ（KB単位） |
| Growth | long | 拡張サイズ（KB単位） |
| GrowthType | string | 拡張タイプ（KB/Percent） |
| MaxSize | long | 最大サイズ（KB単位、-1=無制限） |
| Parent | FileGroup | 親ファイルグループオブジェクト |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.DataFileオブジェクト）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ 1.1 FileGroup必須チェック
   └─ 1.2 SqlInstance指定時にDatabaseが必須かチェック
2. データベースオブジェクト取得
   └─ Get-DbaDatabase経由でInputObjectに追加
3. データベースごとのループ処理
   └─ 3.1 ファイルグループ存在チェック
   └─ 3.2 MemoryOptimizedDataFileGroupの場合はSQL 2014チェック
   └─ 3.3 ファイル名自動生成（未指定時）
   └─ 3.4 論理名重複チェック
   └─ 3.5 パス決定（Get-DbaDefaultPath使用）
   └─ 3.6 ShouldProcess確認
   └─ 3.7 DataFileオブジェクト作成
   └─ 3.8 プロパティ設定（MemoryOptimizedの場合は異なる）
   └─ 3.9 ファイルグループへの追加
   └─ 3.10 Alter()実行とRefresh()
   └─ 3.11 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{FileGroup指定?}
    B -->|No| C[エラー: FileGroup必須]
    B -->|Yes| D{SqlInstance && !Database?}
    D -->|Yes| E[エラー: Database必須]
    D -->|No| F[データベースオブジェクト取得]
    F --> G[foreach db]
    G --> H{FileGroup存在?}
    H -->|No| I[警告: FileGroup未発見]
    I --> G
    H -->|Yes| J{MemoryOptimized && Version < 12?}
    J -->|Yes| K[警告: SQL 2014必要]
    K --> G
    J -->|No| L[ファイル名決定]
    L --> M{論理名重複?}
    M -->|Yes| N[警告: 名前重複]
    N --> G
    M -->|No| O[パス決定]
    O --> P[ShouldProcess確認]
    P --> Q{MemoryOptimized?}
    Q -->|Yes| R[コンテナ作成]
    Q -->|No| S[DataFile作成]
    R --> T[Files.Add & Alter]
    S --> T
    T --> U[Refresh & 出力]
    U --> G
    G --> V[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | FileGroup必須 | FileGroupパラメータは必須 | 常時 |
| BR-002 | SQL 2014要件 | MemoryOptimizedDataFileGroupはSQL Server 2014以上が必要 | MemoryOptimized |
| BR-003 | ファイル名自動生成 | 未指定時は`{DB名}_{FileGroup}_{連番}`形式で生成 | FileName未指定時 |
| BR-004 | パス自動決定 | 未指定時はGet-DbaDefaultPathでデータディレクトリ取得 | Path未指定時 |
| BR-005 | MemoryOptimized特別処理 | Size/Growth/MaxSize設定は標準ファイルのみ | ファイルタイプによる |
| BR-006 | デフォルトサイズ | 128MB初期サイズ、64MB拡張、無制限最大 | Size/Growth/MaxSize未指定時 |

### 計算ロジック

- SMOはKB単位で動作するため、MB入力を1024倍してKBに変換

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ファイル追加 | sys.database_files | INSERT | データファイルメタデータ登録 |
| 物理ファイル | ファイルシステム | CREATE | .ndf/.mdfファイル作成 |

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

#### sys.database_files

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | FileNameパラメータ値 | 論理名 |
| INSERT | physical_name | Pathパラメータ値 | 物理パス |
| INSERT | size | Size * 1024 / 8 | 8KBページ単位 |
| INSERT | growth | Growth * 1024 / 8 | 8KBページ単位 |
| INSERT | max_size | MaxSize * 1024 / 8 | 8KBページ単位、-1=無制限 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | FileGroup未指定 | FileGroupパラメータを指定 |
| - | Stop-Function | SqlInstance指定時にDatabase未指定 | Databaseパラメータを指定 |
| - | Stop-Function | ファイルグループが存在しない | ファイルグループ名を確認 |
| - | Stop-Function | MemoryOptimizedでSQL 2014未満 | SQL Server 2014以上を使用 |
| - | Stop-Function | 論理名重複 | 別の名前を使用 |
| - | Stop-Function | ファイル追加失敗 | 権限、パス、ディスク容量を確認 |

### リトライ仕様

リトライ機能なし

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

SMOのAlter()メソッドによる暗黙的トランザクション。失敗時は自動ロールバック。

## パフォーマンス要件

特に定義なし。物理ファイル作成を伴うため、サイズによって実行時間が変動する可能性あり。

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

- ALTER DATABASE権限が必要
- SqlCredentialによる認証情報の安全な受け渡し
- 物理パスへの書き込み権限（SQL Serverサービスアカウント）

## 備考

- MemoryOptimizedDataFileGroupの場合、Pathはディレクトリを指定（ファイル名ではない）
- 標準データファイルは.ndf拡張子が自動付与される
- パイプラインからGet-DbaDatabase出力を受け取り可能
- WhatIfおよびConfirmをサポート

---

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

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

### 推奨読解順序

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

SMO DataFileオブジェクトとFileGroupの関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Add-DbaDbFile.ps1 | `public/Add-DbaDbFile.ps1` | .OUTPUTS セクション - DataFileプロパティ |

**読解のコツ**: DataFileはFileGroupに属し、FileName（論理名）、FileName（物理パス）、Size、Growth、GrowthType、MaxSizeプロパティを持つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Add-DbaDbFile.ps1 | `public/Add-DbaDbFile.ps1` | パラメータ定義とデフォルト値 |

**主要処理フロー**:
1. **135-149行目**: パラメータ定義（Size=128, Growth=64, MaxSize=-1）
2. **150-261行目**: processブロック全体
3. **152-160行目**: パラメータ検証

#### Step 3: 各処理層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Add-DbaDbFile.ps1 | `public/Add-DbaDbFile.ps1` | ファイル追加ロジック |

**主要処理フロー**:
- **170-171行目**: ファイルグループ存在チェック
- **177-180行目**: MemoryOptimized時のバージョンチェック
- **184-187行目**: ファイル名自動生成
- **190-192行目**: 論理名重複チェック
- **195-205行目**: パス決定（標準/MemoryOptimized分岐）
- **209-227行目**: MemoryOptimizedコンテナ作成
- **228-255行目**: 標準DataFile作成
- **232-242行目**: プロパティ設定（Size, Growth, MaxSize）

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

```
Add-DbaDbFile
    │
    ├─ Test-Bound (パラメータ検証)
    │
    ├─ Get-DbaDatabase (データベースオブジェクト取得)
    │
    ├─ Get-DbaDefaultPath (デフォルトパス取得)
    │
    ├─ [SMO] New-Object DataFile (ファイルオブジェクト生成)
    │      └─ プロパティ設定
    │
    ├─ [SMO] FileGroup.Files.Add() (ファイルグループへ追加)
    │
    ├─ [SMO] FileGroup.Alter() (変更の永続化)
    │
    └─ [SMO] Database.Refresh() (状態更新)
```

### データフロー図

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

SqlInstance/Database ───▶ Get-DbaDatabase ───────────────▶ Database object
                                │
FileGroup ──────────────────────▶ FileGroups[$FileGroup]
                                │
FileName (auto or manual) ──────▶
                                │
Path (auto or manual) ──────────▶ Get-DbaDefaultPath
                                │
Size/Growth/MaxSize ────────────▶
                                │
                                ▼
                          New-Object DataFile
                          プロパティ設定
                                │
                                ▼
                          Files.Add & Alter ───────────▶ DB更新
                                │                        物理ファイル作成
                                ▼
                          Refresh & 出力 ──────────────▶ DataFile object
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Add-DbaDbFile.ps1 | `public/Add-DbaDbFile.ps1` | ソース | メインコマンドレット |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Get-DbaDefaultPath.ps1 | `public/Get-DbaDefaultPath.ps1` | ソース | デフォルトパス取得 |
| New-DbaDbFileGroup.ps1 | `public/New-DbaDbFileGroup.ps1` | ソース | ファイルグループ作成（関連機能） |
