# 画面設計書 210-Darling Data

## 概要

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

### 本画面の処理概要

Darling Data機能は、Erik Darling氏が提供するSQL Serverパフォーマンス監視ストアドプロシージャ群をダウンロードしてインストールする機能を提供する。Extended Events分析、メモリ圧力監視、Query Store分析などの診断ツールを含む。

**業務上の目的・背景**：Darling Dataは、Erik Darling氏がMicrosoft MVPとしての経験から開発したSQL Server診断ツール群である。sp_HumanEvents（Extended Events分析）、sp_PressureDetector（メモリ・CPU圧力監視）、sp_QuickieStore（Query Store分析）など、高度なパフォーマンス分析機能を提供する。これらは無償で利用でき、SQL Serverのパフォーマンス問題の迅速な特定に役立つ。本機能は、GitHubからの自動ダウンロードと複数サーバーへの一括展開を可能にする。

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

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

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 319 | Install-DbaDarlingData | 主機能 | Darling Dataのインストール |
| - | Save-DbaCommunitySoftware | 補助機能 | ソフトウェアのダウンロード |
| 318 | Install-DbaFirstResponderKit | 関連機能 | 類似のコミュニティツール |

## 画面種別

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

## URL/ルーティング

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

# 特定プロシージャのみインストール
Install-DbaDarlingData -SqlInstance <インスタンス> -Procedure Human, Pressure
```

## 入出力項目

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

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

| 値 | 短縮形 | 説明 |
|----|--------|------|
| All | - | 全プロシージャをインストール（デフォルト） |
| HumanEvents | Human | Extended Events分析ツール |
| PressureDetector | Pressure | メモリ・CPU圧力監視 |
| QuickieStore | Quickie | Query Store分析（SQL 2016以上） |
| HumanEventsBlockViewer | Block | ブロッキング分析 |
| LogHunter | Log | エラーログ分析 |
| HealthParser | Health | ヘルス診断 |
| IndexCleanup | Index | インデックスクリーンアップ |
| PerfCheck | Perf | パフォーマンスチェック |

## 表示項目

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

## イベント仕様

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

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

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

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

### 3-プロシージャ選択ロジック

| Procedure値 | 検索ファイル |
|------------|-------------|
| All | DarlingData.sql |
| Human/HumanEvents | sp_HumanEvents.sql |
| Pressure/PressureDetector | sp_PressureDetector.sql |
| Quickie/QuickieStore | sp_QuickieStore.sql |
| Block/HumanEventsBlockViewer | sp_HumanEventsBlockViewer.sql |
| Log/LogHunter | sp_LogHunter.sql |
| Health/HealthParser | sp_HealthParser.sql |
| Index/IndexCleanup | sp_IndexCleanup.sql |
| Perf/PerfCheck | sp_PerfCheck.sql |

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| インストール | sys.procedures | INSERT | ストアドプロシージャの作成 |
| 更新 | sys.procedures | UPDATE | ストアドプロシージャの変更 |

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

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

| 操作 | プロシージャ名 | 処理内容 | 備考 |
|-----|--------------|---------|------|
| CREATE/ALTER | sp_HumanEvents | Extended Events分析 | メインツール |
| CREATE/ALTER | sp_PressureDetector | 圧力検出 | メモリ・CPU分析 |
| CREATE/ALTER | sp_QuickieStore | Query Store分析 | SQL 2016以上 |
| CREATE/ALTER | sp_HumanEventsBlockViewer | ブロッキング分析 | Extended Events連携 |
| CREATE/ALTER | sp_LogHunter | ログ分析 | エラーログ検索 |
| CREATE/ALTER | sp_HealthParser | ヘルス分析 | 総合診断 |
| CREATE/ALTER | sp_IndexCleanup | インデックス整理 | メンテナンス |
| CREATE/ALTER | sp_PerfCheck | パフォーマンス確認 | 総合チェック |

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| 警告 | "$instance found to be below SQL Server 2016, skipping sp_QuickieStore.sql" | SQL 2016未満 |
| 警告 | "Could not execute at least one portion of $scriptName in $Database on $instance." | 実行エラー時 |
| エラー | "Failure" | 接続失敗時（ConnectionError） |
| エラー | "Database $Database not found on $instance. Skipping." | データベース未検出時 |
| エラー | "Failed to update local cached copy" | ダウンロード失敗時 |

## 例外処理

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

## 備考

- GitHubリポジトリ: https://github.com/erikdarlingdata/DarlingData
- 公式サイト: https://www.erikdarling.com
- ローカルキャッシュはdbatoolsデータディレクトリに「DarlingData-{Branch}」として保存
- devブランチで最新の開発版を取得可能
- Procedure=Allの場合はDarlingData.sql（統合スクリプト）を使用

---

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

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

### 推奨読解順序

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

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

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

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

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

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

**主要処理フロー**:
1. **行142-157**: beginブロックでキャッシュ更新
2. **行162-169**: SQLインスタンス接続
3. **行171-174**: データベース存在確認
4. **行181-211**: スクリプトファイル取得（Procedure指定に応じて）
5. **行213-251**: インストールループ

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

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

**主要処理フロー**:
- **行146**: キャッシュパス決定（DarlingData-{Branch}）
- **行147**: キャッシュパス構築
- **行148**: Force/LocalFile/キャッシュ不存在時に更新
- **行151**: Save-DbaCommunitySoftware呼び出し

#### Step 4: Procedure選択ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Install-DbaDarlingData.ps1 | `public/Install-DbaDarlingData.ps1` | プロシージャ選択（行181-211） |

**主要処理フロー**:
- **行181-183**: All指定時はDarlingData.sql
- **行184-210**: 個別プロシージャ指定時の各ファイル検索

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

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

**主要処理フロー**:
- **行227-232**: sp_QuickieStore.sql（SQL 2016以上、VersionMajor >= 13）

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

```
Install-DbaDarlingData
    |
    +-- begin{}
    |      +-- キャッシュパス決定
    |      +-- Save-DbaCommunitySoftware
    |
    +-- process{}
           +-- foreach SqlInstance
                  +-- Connect-DbaInstance
                  +-- データベース存在確認
                  |      +-- $server.Databases[$Database]
                  |
                  +-- 既存プロシージャ確認
                  |      +-- sys.procedures クエリ
                  |
                  +-- スクリプト取得
                  |      +-- All: DarlingData.sql
                  |      +-- 個別: sp_*.sql
                  |
                  +-- foreach スクリプト
                         +-- バージョン互換性チェック
                         +-- Invoke-DbaQuery (スクリプト実行)
                         +-- ステータス判定
                                +-- エラー時: Error
                                +-- 既存時: Updated
                                +-- 新規時: Installed
                                +-- 非対応時: Skipped
```

### データフロー図

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

SqlInstance --------+
                    |
Database -----------+----> 接続確認 ----> データベース存在確認
                    |           |
Branch -------------+           v
                          キャッシュ確認/更新
LocalFile (オプション) -----> |
                              v
Procedure ----------> スクリプト選択
                         |
                         +-- All: DarlingData.sql
                         +-- 個別: sp_*.sql
                              |
                              v
                         バージョン互換性チェック
                              |
                              v
                         Invoke-DbaQuery ----> PSCustomObject
                         (スクリプト実行)       (Name, Status)
```

### 関連ファイル一覧

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