# 機能設計書 627-Enable-DbaFilestream

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Enable-DbaFilestream`コマンドレットに関する機能設計書である。このコマンドレットは、SQL ServerのFILESTREAM機能をインスタンスレベルとサービスレベルの両方で有効化する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：FILESTREAMは、ドキュメント、画像、動画などの大きなバイナリデータをファイルシステムに直接格納しながら、データベースとのトランザクション整合性を維持できる機能である。この機能を有効化することで、varbinary(max)列をファイルシステム上に格納可能になり、大規模BLOBデータの効率的な管理が可能になる。

**機能の利用シーン**：
- FILESTREAM機能を使用するアプリケーションのセットアップ
- 大容量ファイルストレージ機能の有効化
- BLOBデータの外部ファイルシステム格納設定
- リモートクライアントからのFILESTREAMアクセス設定

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続確立
2. FileStreamLevelの解析（数値/文字列どちらでも受付）
3. サービスレベルでのFILESTREAM設定（Set-FileSystemSetting）
4. インスタンスレベルでのFilestreamAccessLevel設定（Set-DbaSpConfigure）
5. クラスター環境の場合は各ノードに対して設定
6. Forceスイッチ指定時はSQL Serverサービスを再起動
7. 変更後のFILESTREAM状態を出力

**関連システム・外部連携**：
- SQL Server Management Objects (SMO)
- WMI（Windows Management Instrumentation）
- SQL Serverサービス管理

**権限による制御**：sysadmin権限およびWindowsサーバー管理者権限が必要。

## 関連画面

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

## 機能種別

設定変更 / サービス管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス | ValueFromPipelineByPropertyName |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | ValueFromPipelineByPropertyName |
| Credential | PSCredential | No | Windows接続用資格情報 | ValueFromPipelineByPropertyName |
| FileStreamLevel | string | No | アクセスレベル（1/TSql, 2/TSqlIoStreaming, 3/TSqlIoStreamingRemoteClient）デフォルト:1 | ValidateSet |
| ShareName | string | No | FILESTREAMリモートアクセス用の共有名 | FileStreamLevel >= 2 の場合のみ |
| Force | switch | No | 確認プロンプトをバイパスしサービスを自動再起動 | - |
| EnableException | switch | No | 例外処理モード切替 | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| InstanceAccess | string | インスタンスレベルのアクセス状態 |
| ServiceAccess | string | サービスレベルのアクセス状態 |
| ServiceShareName | string | FILESTREAMの共有名 |

### 出力先

PowerShellパイプライン（PSCustomObject via Get-DbaFilestream）

## 処理フロー

### 処理シーケンス

```
1. begin ブロック
   └─ 1.1 FileStreamLevelの数値変換（TSql=1, TSqlIoStreaming=2, TSqlIoStreamingRemoteClient=3）
   └─ 1.2 出力ルックアップテーブル定義
   └─ 1.3 ForceスイッチでConfirmPreference='none'に設定
2. process ブロック（各インスタンスごと）
   └─ 2.1 ShareNameとlevel < 2 の検証
   └─ 2.2 Connect-DbaInstanceで接続
   └─ 2.3 現在のFilestreamAccessLevel取得
   └─ 2.4 ShouldProcess確認
   └─ 2.5 クラスター判定
   └─ 2.6 各ノードまたは単一サーバーにSet-FileSystemSetting実行
   └─ 2.7 インスタンスレベル設定（level=3の場合は2に調整）
   └─ 2.8 Set-DbaSpConfigureでFilestreamAccessLevel設定
   └─ 2.9 Forceの場合はRestart-DbaService実行
   └─ 2.10 Get-DbaFilestreamで最新状態を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[FileStreamLevel数値変換]
    B --> C[foreach instance]
    C --> D{ShareName && level < 2?}
    D -->|Yes| E[エラー: level 2以上必要]
    D -->|No| F[Connect-DbaInstance]
    F --> G{接続成功?}
    G -->|No| H[Stop-Function]
    H --> C
    G -->|Yes| I{ShouldProcess確認}
    I -->|No| C
    I -->|Yes| J{クラスター?}
    J -->|Yes| K[各ノードにSet-FileSystemSetting]
    J -->|No| L[単一サーバーにSet-FileSystemSetting]
    K --> M{level == 3?}
    L --> M
    M -->|Yes| N[level = 2に調整]
    M -->|No| O[そのまま]
    N --> P[Set-DbaSpConfigure]
    O --> P
    P --> Q{Force?}
    Q -->|Yes| R[Restart-DbaService]
    Q -->|No| S[警告: 再起動必要]
    R --> T[Get-DbaFilestream出力]
    S --> T
    T --> C
    C --> U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ShareName制約 | ShareNameはFileStreamLevel 2以上でのみ使用可能 | ShareName指定時 |
| BR-002 | インスタンスレベル調整 | インスタンスレベルは最大2（level 3はサービスレベルのみ） | level=3時 |
| BR-003 | サービス再起動 | FILESTREAMの変更にはSQL Serverサービスの再起動が必要 | 常時 |
| BR-004 | Force自動再起動 | Forceスイッチで確認なしに自動再起動 | Force指定時 |
| BR-005 | クラスター対応 | クラスター環境では全ノードに設定を適用 | クラスター環境 |
| BR-006 | デフォルトレベル | 未指定時はlevel 1（T-SQL only） | FileStreamLevel未指定時 |

### 計算ロジック

- FileStreamLevel変換: "TSql"=1, "TSqlIoStreaming"=2, "TSqlIoStreamingRemoteClient"=3
- インスタンスレベル最大値: 2（level 3指定時は2に調整）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| sp_configure | sys.configurations | UPDATE | FilestreamAccessLevel設定変更 |

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

#### sys.configurations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | value | 1 or 2 | FilestreamAccessLevel |
| UPDATE | value_in_use | 1 or 2 | サービス再起動後に反映 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | ShareNameでlevel < 2 | FileStreamLevel 2以上を指定 |
| - | Stop-Function | 接続失敗 | 接続情報を確認 |
| - | Stop-Function | Set-DbaSpConfigure失敗 | 権限を確認 |
| - | Warning | 再起動未実行 | 手動でサービス再起動 |

### リトライ仕様

リトライ機能なし

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

sp_configureは即時反映。ただし、value_in_useへの反映にはサービス再起動が必要。

## パフォーマンス要件

特に定義なし。ただし、サービス再起動時は一時的なサービス停止が発生。

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

- sysadmin権限が必要
- Windows管理者権限が必要（サービス再起動時）
- ConfirmImpact='Medium'による確認
- ShareNameはリモートアクセスを許可するため慎重に設定

## 備考

- サービス再起動なしでは設定は完全に有効にならない
- クラスター環境ではGet-DbaWsfcNodeで全ノードを取得
- パイプラインからGet-DbaFilestream出力を受け取り可能
- FileStreamLevel 3はサービスレベルのみ、インスタンスレベルは2に設定

---

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

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

### 推奨読解順序

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

FileStreamLevelの値と意味を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Enable-DbaFilestream.ps1 | `public/Enable-DbaFilestream.ps1` | beginブロックのルックアップテーブル |

**読解のコツ**:
- Level 0: Disabled
- Level 1: T-SQL access only
- Level 2: T-SQL and I/O streaming
- Level 3: Full access including remote clients

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Enable-DbaFilestream.ps1 | `public/Enable-DbaFilestream.ps1` | パラメータ定義とbeginブロック |

**主要処理フロー**:
1. **89-102行目**: パラメータ定義（ValidateSetでレベル制約）
2. **103-127行目**: beginブロック - レベル変換、ルックアップテーブル
3. **128-176行目**: processブロック - メイン処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Enable-DbaFilestream.ps1 | `public/Enable-DbaFilestream.ps1` | 有効化ロジック |

**主要処理フロー**:
- **104-116行目**: FileStreamLevel文字列から数値への変換
- **129-132行目**: ShareName + level < 2 のバリデーション
- **145-152行目**: クラスター/単一サーバー分岐とSet-FileSystemSetting
- **155-157行目**: level=3の場合のインスタンスレベル調整（2に変更）
- **159-163行目**: Set-DbaSpConfigure
- **165-168行目**: Force時のRestart-DbaService

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

```
Enable-DbaFilestream
    │
    ├─ [begin] FileStreamLevel変換
    │      └─ "TSql"→1, "TSqlIoStreaming"→2, "TSqlIoStreamingRemoteClient"→3
    │
    ├─ Connect-DbaInstance (SQL接続)
    │
    ├─ Get-DbaWsfcNode (クラスターノード取得)
    │      └─ クラスター環境のみ
    │
    ├─ Set-FileSystemSetting (サービスレベル設定)
    │      └─ 各ノードまたは単一サーバー
    │
    ├─ Set-DbaSpConfigure (インスタンスレベル設定)
    │      └─ FilestreamAccessLevel = 1 or 2
    │
    ├─ Restart-DbaService (サービス再起動)
    │      └─ Force時のみ
    │
    └─ Get-DbaFilestream (状態取得・出力)
```

### データフロー図

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

SqlInstance ────────────────▶ Connect-DbaInstance
                                   │
FileStreamLevel ────────────▶ 数値変換（1/2/3）
                                   │
ShareName ──────────────────▶ Set-FileSystemSetting
                            (サービスレベル)
                                   │
                                   ▼
                            Set-DbaSpConfigure
                            (インスタンスレベル=1or2)
                                   │
                                   ▼
                            Restart-DbaService (Force時)
                                   │
                                   ▼
                            Get-DbaFilestream ───────────▶ PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Enable-DbaFilestream.ps1 | `public/Enable-DbaFilestream.ps1` | ソース | メインコマンドレット |
| Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | ソース | FILESTREAM状態取得 |
| Disable-DbaFilestream.ps1 | `public/Disable-DbaFilestream.ps1` | ソース | FILESTREAM無効化（対機能） |
| Set-DbaSpConfigure.ps1 | `public/Set-DbaSpConfigure.ps1` | ソース | sp_configure設定変更 |
| Restart-DbaService.ps1 | `public/Restart-DbaService.ps1` | ソース | サービス再起動 |
| Get-DbaWsfcNode.ps1 | `public/Get-DbaWsfcNode.ps1` | ソース | クラスターノード取得 |
