# 機能設計書 318-Install-DbaFirstResponderKit

## 概要

本ドキュメントは、Brent Ozar氏のFirst Responder Kit診断ストアドプロシージャをインストールするInstall-DbaFirstResponderKit機能の設計仕様を記載する。

### 本機能の処理概要

Install-DbaFirstResponderKitは、GitHubのFirst Responder Kitリポジトリからヘルスチェック、パフォーマンス分析、トラブルシューティング用のストアドプロシージャ群をダウンロードし、指定されたデータベースにインストールする機能である。

**業務上の目的・背景**：SQL Serverの診断とトラブルシューティングにおいて、First Responder Kit（FRK）は業界標準のツールとして広く採用されている。sp_Blitz（総合ヘルスチェック）、sp_BlitzCache（クエリパフォーマンス分析）、sp_BlitzIndex（インデックス推奨）、sp_BlitzFirst（リアルタイムパフォーマンス監視）などの専門的なストアドプロシージャは、SQL Server DBAの日常業務に不可欠である。本機能は、これらのツールを複数のSQL Serverインスタンスに簡単かつ一貫した方法でインストール・更新することを可能にする。

**機能の利用シーン**：本機能は以下のような場面で利用される。
- 新規SQL Server環境への診断ツールセットアップ
- 既存環境のFirst Responder Kit更新
- パフォーマンス問題の調査準備
- 複数インスタンスへの一括インストール
- Azure SQL Databaseへのインストール
- オフライン環境へのインストール（LocalFile使用）

**主要な処理内容**：
1. GitHubからFirst Responder Kitリポジトリのダウンロード（またはローカルファイル使用）
2. 対象SQL Serverインスタンスへの接続
3. バージョン互換性チェック
4. ストアドプロシージャの作成または更新
5. インストール結果の出力

**関連システム・外部連携**：GitHub（BrentOzarULTD/SQL-Server-First-Responder-Kit）からのダウンロード。Save-DbaCommunitySoftware内部関数を使用。

**権限による制御**：対象データベースへのCREATE PROCEDURE権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コミュニティツール管理 | 主機能 | First Responder Kitのインストール |

## 機能種別

インストール / コミュニティツール

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | インストール先SQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 | Windows/SQL/AD認証サポート |
| Branch | string | No | リポジトリブランチ（main/dev） | ValidateSet |
| Database | object | No | インストール先データベース（デフォルト: master） | - |
| LocalFile | string | No | ローカルZIPファイルパス | - |
| OnlyScript | string[] | No | インストール対象スクリプト | ValidateSet |
| Force | switch | No | キャッシュを無視して再ダウンロード | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- GitHubリポジトリ（https://github.com/BrentOzarULTD/SQL-Server-First-Responder-Kit）
- ローカルZIPファイル（LocalFile指定時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Database | string | インストール先データベース名 |
| Name | string | スクリプト名（拡張子なし） |
| Status | string | Installed/Updated/Skipped/Error |

### 出力先

- PowerShellパイプライン（PSCustomObject形式）

## 処理フロー

### 処理シーケンス

```
1. 前処理（beginブロック）
   └─ Force指定時のConfirmPreference設定
   └─ ローカルキャッシュ有無確認
   └─ 必要に応じてSave-DbaCommunitySoftwareでダウンロード
   └─ スクリプトファイル選択（OnlyScript指定またはsp_*.sql + SqlServerVersions.sql）
2. インスタンスループ開始
   └─ foreach $SqlInstance
3. SQL Server接続
   └─ Connect-DbaInstance実行（NonPooledConnection）
4. 既存プロシージャ取得
   └─ sys.proceduresから一覧取得
5. スクリプト実行ループ
   └─ バージョンチェック（sp_BlitzQueryStore: SQL 2016+, sp_BlitzInMemoryOLTP: SQL 2014+）
   └─ Invoke-DbaQueryでスクリプト実行
6. 結果出力
   └─ Status判定（Installed/Updated/Skipped/Error）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{キャッシュ存在?}
    B -->|No| C[Save-DbaCommunitySoftware]
    B -->|Yes| D{Force?}
    D -->|Yes| C
    D -->|No| E{OnlyScript指定?}
    C --> E
    E -->|Yes| F[指定スクリプトのみ取得]
    E -->|No| G[sp_*.sql + SqlServerVersions.sql取得]
    F --> H[foreach SqlInstance]
    G --> H
    H --> I[Connect-DbaInstance]
    I --> J{接続成功?}
    J -->|No| K[エラー出力, Continue]
    J -->|Yes| L[既存プロシージャ取得]
    L --> M[foreach script]
    M --> N{sp_BlitzQueryStore?}
    N -->|Yes| O{Version >= 13?}
    O -->|No| P[Status = Skipped]
    N -->|No| Q{sp_BlitzInMemoryOLTP?}
    Q -->|Yes| R{Version >= 12?}
    R -->|No| P
    R -->|Yes| S[Invoke-DbaQuery実行]
    Q -->|No| S
    O -->|Yes| S
    P --> T[結果出力]
    S --> U{実行成功?}
    U -->|No| V[Status = Error]
    U -->|Yes| W{既存?}
    W -->|Yes| X[Status = Updated]
    W -->|No| Y[Status = Installed]
    V --> T
    X --> T
    Y --> T
    T --> M
    K --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン制限（QueryStore） | sp_BlitzQueryStoreはSQL Server 2016（バージョン13）以上が必要 | sp_BlitzQueryStore実行時 |
| BR-002 | バージョン制限（InMemoryOLTP） | sp_BlitzInMemoryOLTPはSQL Server 2014（バージョン12）以上が必要 | sp_BlitzInMemoryOLTP実行時 |
| BR-003 | デフォルトデータベース | Database未指定時はmasterを使用 | 常時 |
| BR-004 | ブランチ選択 | main（安定版）またはdev（開発版）から選択 | 常時 |
| BR-005 | キャッシュ使用 | Force未指定時はローカルキャッシュを使用 | ダウンロード時 |
| BR-006 | ステータス判定 | 既存プロシージャはUpdated、新規はInstalled | インストール完了時 |
| BR-007 | デフォルトスクリプト | OnlyScript未指定時はsp_*.sql + SqlServerVersions.sqlをインストール | 常時 |

### インストール可能スクリプト一覧

| スクリプト名 | 用途 | バージョン要件 |
|-------------|------|---------------|
| Install-All-Scripts.sql | 公式一括インストール | - |
| Install-Azure.sql | Azure SQL Database用 | - |
| sp_Blitz.sql | 総合ヘルスチェック | - |
| sp_BlitzFirst.sql | リアルタイム監視 | - |
| sp_BlitzIndex.sql | インデックス分析 | - |
| sp_BlitzCache.sql | クエリキャッシュ分析 | - |
| sp_BlitzWho.sql | 現在の接続分析 | - |
| sp_BlitzAnalysis.sql | 分析レポート | - |
| sp_BlitzBackups.sql | バックアップ分析 | - |
| sp_BlitzLock.sql | ロック分析 | - |
| sp_DatabaseRestore.sql | リストア自動化 | - |
| sp_ineachdb.sql | 各DB実行ユーティリティ | - |
| SqlServerVersions.sql | バージョン情報テーブル | - |
| Uninstall.sql | アンインストール | - |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 既存プロシージャ確認 | sys.procedures | SELECT | is_ms_shipped = 0の一覧取得 |
| プロシージャ作成/更新 | - | CREATE/ALTER PROCEDURE | ストアドプロシージャのインストール |

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

#### sys.procedures

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name | is_ms_shipped = 0 | ユーザー定義プロシージャのみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverへの接続失敗 | 接続情報と権限を確認 |
| - | DownloadFailure | GitHubからのダウンロード失敗 | ネットワーク接続確認、LocalFile使用 |
| - | ScriptNotFound | OnlyScript指定のスクリプトが見つからない | スクリプト名を確認 |
| - | ScriptError | スクリプト実行エラー | 権限と互換性を確認 |

### リトライ仕様

リトライ機能は実装されていない。ダウンロード失敗時はLocalFileパラメータを使用。

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

各スクリプトは独立して実行される。スクリプト内でのトランザクション管理はスクリプト自身に依存。

## パフォーマンス要件

- ローカルキャッシュによりダウンロード回数を最小化
- NonPooledConnectionで接続プール問題を回避
- Invoke-DbaQuery -Fileでスクリプト実行

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

- SqlCredentialによる認証情報の安全な受け渡し
- GitHubからの信頼されたソースのみ使用
- CREATE PROCEDURE権限が必要

## 備考

- First Responder KitはBrent Ozar Unlimited（brentozar.com）が提供するコミュニティツール
- mainブランチは安定版、devブランチは最新機能を含む
- SupportsShouldProcess対応（WhatIf/Confirm）
- Azure SQL Database用の専用インストールスクリプトあり

---

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

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

### 推奨読解順序

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

出力されるオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaFirstResponderKit.ps1 | `public/Install-DbaFirstResponderKit.ps1` | .OUTPUTSコメント（68-79行目）で出力プロパティを確認 |

**読解のコツ**: Statusプロパティの4つの状態（Installed/Updated/Skipped/Error）を理解する。

#### Step 2: ダウンロードとキャッシュ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaFirstResponderKit.ps1 | `public/Install-DbaFirstResponderKit.ps1` | 153-183行目のbeginブロック |

**主要処理フロー**:
- **157行目**: Path.DbatoolsDataから設定取得
- **158行目**: ローカルキャッシュパス構築
- **159行目**: キャッシュ有無判定
- **162行目**: Save-DbaCommunitySoftware呼び出し
- **169-182行目**: スクリプトファイル選択

#### Step 3: バージョンチェックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Install-DbaFirstResponderKit.ps1 | `public/Install-DbaFirstResponderKit.ps1` | 215-226行目のバージョンチェック |

**主要処理フロー**:
- **215-220行目**: sp_BlitzQueryStoreのSQL 2016チェック
- **221-226行目**: sp_BlitzInMemoryOLTPのSQL 2014チェック

#### Step 4: インストール処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Install-DbaFirstResponderKit.ps1 | `public/Install-DbaFirstResponderKit.ps1` | 227-243行目のスクリプト実行処理 |

**主要処理フロー**:
- **229行目**: Invoke-DbaQuery -Fileでスクリプト実行
- **235-241行目**: Status判定ロジック

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

```
Install-DbaFirstResponderKit
    │
    ├─ begin
    │      ├─ Get-DbatoolsConfigValue
    │      ├─ Save-DbaCommunitySoftware
    │      │      └─ GitHub API / LocalFile展開
    │      └─ Get-ChildItem
    │             └─ スクリプトファイル取得
    │
    └─ process
           ├─ Connect-DbaInstance
           │      └─ NonPooledConnection
           │
           ├─ Server.Query()
           │      └─ sys.procedures取得
           │
           └─ Invoke-DbaQuery -File
                  └─ スクリプト実行
```

### データフロー図

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

GitHub/LocalFile ─────▶ Save-DbaCommunitySoftware ───▶ ローカルキャッシュ
        │                                                    │
        ▼                                                    ▼
Branch (main/dev) ──────────────────────────────────▶ キャッシュパス選択
        │                                                    │
        ▼                                                    ▼
OnlyScript ────────────▶ Get-ChildItem ─────────────▶ スクリプト一覧
        │                                                    │
        ▼                                                    ▼
SqlInstance ───────────▶ Connect-DbaInstance ───────▶ Server オブジェクト
        │                                                    │
        ▼                                                    ▼
Database ──────────────▶ 既存プロシージャ確認 ────▶ allprocedures
        │                                                    │
        ▼                                                    ▼
                                              バージョンチェック
                                                       │
                                                       ▼
                                              Invoke-DbaQuery -File
                                                       │
                                                       ▼
                                              PSCustomObject（Status付き）
                                                       │
                                                       ▼
                                              パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaFirstResponderKit.ps1 | `public/Install-DbaFirstResponderKit.ps1` | ソース | メイン機能実装 |
| Save-DbaCommunitySoftware.ps1 | `private/functions/Save-DbaCommunitySoftware.ps1` | ソース | ダウンロード処理（依存先） |
| Install-DbaDarlingData.ps1 | `public/Install-DbaDarlingData.ps1` | ソース | 関連機能（類似パターン） |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | スクリプト実行（依存先） |
