# 画面設計書 209-First Responder Kit

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるFirst Responder Kitインストール機能の設計仕様を定義するものである。

### 本画面の処理概要

First Responder Kit機能は、Brent Ozar Unlimited社が提供するSQL Server診断ストアドプロシージャ群をダウンロードしてインストールする機能を提供する。SQL Serverのヘルスチェック、パフォーマンス分析、トラブルシューティングに広く使用されるコミュニティツールである。

**業務上の目的・背景**：First Responder Kit（FRK）は、SQL Serverの健全性評価（sp_Blitz）、クエリパフォーマンス分析（sp_BlitzCache）、インデックス推奨（sp_BlitzIndex）、リアルタイムモニタリング（sp_BlitzFirst）などの診断ツールを含む。これらは商用ツールに匹敵する機能を無償で提供し、DBAの日常業務やインシデント対応に不可欠である。本機能は、GitHubからの自動ダウンロードとインストールを提供し、複数サーバーへの一括展開を可能にする。

**画面へのアクセス方法**：PowerShellコンソールから`Install-DbaFirstResponderKit`コマンドを実行する。

**主要な操作・処理内容**：
1. GitHubから最新版またはdev版のダウンロード
2. ローカルキャッシュへの保存
3. 指定データベースへのストアドプロシージャインストール
4. SQL Serverバージョン互換性チェック
5. 既存プロシージャの更新

**画面遷移**：
- 入力元：管理者またはスクリプトからのコマンド実行
- 出力先：SQL Serverデータベースにインストールされたストアドプロシージャ
- 関連機能：Invoke-DbaWhoIsActive、Save-DbaCommunitySoftware

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 318 | Install-DbaFirstResponderKit | 主機能 | First Responder Kitのインストール |
| - | Save-DbaCommunitySoftware | 補助機能 | ソフトウェアのダウンロード |
| - | Invoke-DbaWhoIsActive | 関連機能 | sp_WhoIsActiveの実行 |

## 画面種別

コマンドラインインターフェース（CLI）/ インストール

## URL/ルーティング

```powershell
# 基本インストール
Install-DbaFirstResponderKit -SqlInstance <インスタンス> -Database <DB名>

# 特定スクリプトのみインストール
Install-DbaFirstResponderKit -SqlInstance <インスタンス> -OnlyScript sp_Blitz.sql, sp_BlitzCache.sql
```

## 入出力項目

| パラメータ名 | 型 | 必須 | 既定値 | 説明 |
|-------------|-----|------|--------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | - | SQL認証用資格情報 |
| Database | object | No | master | インストール先データベース |
| Branch | string | No | main | GitHubブランチ（main/dev） |
| LocalFile | string | No | - | ローカルZIPファイルパス |
| OnlyScript | string[] | No | - | インストールするスクリプト限定 |
| Force | switch | No | $false | キャッシュの強制更新 |
| EnableException | switch | No | $false | 例外の有効化 |
| WhatIf | switch | No | - | 実行内容のプレビュー |
| Confirm | switch | No | - | 実行確認プロンプト |

### OnlyScript パラメータの有効値

| スクリプト名 | 説明 |
|-------------|------|
| 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 | アンインストール |

## 表示項目

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

## イベント仕様

### 1-インストールイベント

1. ローカルキャッシュの確認・更新（Save-DbaCommunitySoftware）
2. スクリプトファイルの取得（OnlyScript指定時はフィルタリング）
3. SQLインスタンスへの接続
4. 既存プロシージャの確認
5. SQL Serverバージョン互換性チェック
6. スクリプト実行（Invoke-DbaQuery）
7. ステータス判定と結果返却

### 2-バージョン互換性チェックイベント

| スクリプト | 必要バージョン | 非対応時の動作 |
|-----------|--------------|--------------|
| sp_BlitzQueryStore.sql | SQL Server 2016以上 | Skipped |
| sp_BlitzInMemoryOLTP.sql | SQL Server 2014以上 | Skipped |

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| インストール | sys.procedures | INSERT | ストアドプロシージャの作成 |
| 更新 | sys.procedures | UPDATE | ストアドプロシージャの変更 |
| アンインストール | sys.procedures | DELETE | ストアドプロシージャの削除 |
| SqlServerVersions | dbo.SqlServerVersions | INSERT/UPDATE | バージョン情報テーブル |

### テーブル別更新項目詳細

#### ストアドプロシージャ（sys.procedures）

| 操作 | プロシージャ名 | 処理内容 | 備考 |
|-----|--------------|---------|------|
| CREATE/ALTER | sp_Blitz | 総合ヘルスチェック | メインプロシージャ |
| CREATE/ALTER | sp_BlitzFirst | リアルタイム分析 | 待機統計等を分析 |
| CREATE/ALTER | sp_BlitzIndex | インデックス分析 | 推奨・問題検出 |
| CREATE/ALTER | sp_BlitzCache | キャッシュ分析 | プラン分析 |
| CREATE/ALTER | sp_BlitzWho | 実行中クエリ | sp_who代替 |

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| 警告 | "$instance found to be below SQL Server 2016, skipping sp_BlitzQueryStore.sql" | SQL 2016未満 |
| 警告 | "$instance found to be below SQL Server 2014, skipping sp_BlitzInMemoryOLTP.sql" | SQL 2014未満 |
| 警告 | "Script $script not found in $LocalCachedCopy, skipping." | スクリプト未検出 |
| 警告 | "Could not execute at least one portion of $scriptName..." | 実行エラー時 |
| エラー | "Error occurred while establishing connection to $instance" | 接続失敗時 |
| エラー | "Failed to update local cached copy" | ダウンロード失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ダウンロード失敗 | Stop-Functionでエラー |
| 接続失敗 | Stop-Functionでエラー記録、Continue |
| スクリプト実行失敗 | 警告メッセージ、Status=Error |
| バージョン非対応 | 警告メッセージ、Status=Skipped |

## 備考

- GitHubリポジトリ: https://github.com/BrentOzarULTD/SQL-Server-First-Responder-Kit
- 公式サイト: http://FirstResponderKit.org
- ローカルキャッシュはdbatoolsデータディレクトリに保存
- devブランチで最新の開発版を取得可能

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaFirstResponderKit.ps1 | `public/Install-DbaFirstResponderKit.ps1` | 出力オブジェクト構造（行206-213） |

**読解のコツ**: Statusプロパティが4種類（Installed/Updated/Skipped/Error）ある点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaFirstResponderKit.ps1 | `public/Install-DbaFirstResponderKit.ps1` | パラメータ定義（行135-152） |

**主要処理フロー**:
1. **行153-167**: beginブロックでキャッシュ更新
2. **行169-182**: スクリプトファイル取得
3. **行185-195**: SQLインスタンス接続
4. **行196-246**: インストールループ

#### Step 3: キャッシュ管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Install-DbaFirstResponderKit.ps1 | `public/Install-DbaFirstResponderKit.ps1` | キャッシュ処理（行153-167） |

**主要処理フロー**:
- **行157-158**: キャッシュパス決定
- **行159**: Force/LocalFile/キャッシュ不存在時に更新
- **行162**: Save-DbaCommunitySoftware呼び出し

#### Step 4: バージョン互換性チェックを理解する

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

**主要処理フロー**:
- **行215-220**: sp_BlitzQueryStore.sql（SQL 2016以上）
- **行221-226**: sp_BlitzInMemoryOLTP.sql（SQL 2014以上）

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

```
Install-DbaFirstResponderKit
    |
    +-- begin{}
    |      +-- キャッシュパス決定
    |      +-- Save-DbaCommunitySoftware
    |      +-- スクリプトファイル取得
    |             +-- OnlyScript指定時: フィルタリング
    |             +-- 未指定時: sp_*.sql + SqlServerVersions.sql
    |
    +-- process{}
           +-- Connect-DbaInstance
           +-- 既存プロシージャ確認
           |      +-- sys.procedures クエリ
           |
           +-- foreach スクリプト
                  +-- バージョン互換性チェック
                  +-- Invoke-DbaQuery (スクリプト実行)
                  +-- ステータス判定
                         +-- エラー時: Error
                         +-- 既存時: Updated
                         +-- 新規時: Installed
                         +-- 非対応時: Skipped
```

### データフロー図

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

SqlInstance --------+
                    |
Database -----------+----> 接続確認 ----> 既存プロシージャ確認
                    |           |
Branch -------------+           v
                          キャッシュ確認/更新
LocalFile (オプション) -----> |
                              v
OnlyScript (オプション) --> スクリプト選択
                              |
                              v
                         バージョン互換性チェック
                              |
                              v
                         Invoke-DbaQuery ----> PSCustomObject
                         (スクリプト実行)       (Name, Status)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaFirstResponderKit.ps1 | `public/Install-DbaFirstResponderKit.ps1` | ソース | メインコマンド実装 |
| Save-DbaCommunitySoftware.ps1 | `public/Save-DbaCommunitySoftware.ps1` | ソース | ダウンロード処理 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | SQLクエリ実行 |
