# 機能設計書 317-Install-DbaDarlingData

## 概要

本ドキュメントは、Erik Darling氏のパフォーマンス監視ストアドプロシージャをインストールするInstall-DbaDarlingData機能の設計仕様を記載する。

### 本機能の処理概要

Install-DbaDarlingDataは、GitHubのDarlingDataリポジトリからパフォーマンス監視用のストアドプロシージャ群をダウンロードし、指定されたデータベースにインストールする機能である。

**業務上の目的・背景**：SQL Serverのパフォーマンス監視とトラブルシューティングにおいて、Erik Darling氏が開発した診断ツール群は広く利用されている。sp_HumanEvents（拡張イベント分析）、sp_PressureDetector（メモリ圧迫監視）、sp_QuickieStore（Query Store分析）などの専門的なストアドプロシージャは、SQL Serverの問題診断に不可欠である。本機能は、これらのツールを簡単かつ一貫した方法でインストール・更新することを可能にする。

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

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

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- GitHubリポジトリ（https://github.com/erikdarlingdata/DarlingData）
- ローカル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でダウンロード
2. インスタンスループ開始
   └─ foreach $SqlInstance
3. SQL Server接続
   └─ Connect-DbaInstance実行
4. データベース存在確認
   └─ $server.Databases[$Database]
5. 既存プロシージャ取得
   └─ sys.proceduresから一覧取得
6. スクリプトファイル選択
   └─ Procedure指定に基づくフィルタリング
7. スクリプト実行ループ
   └─ バージョンチェック（sp_QuickieStore: SQL 2016+）
   └─ Invoke-DbaQueryでスクリプト実行
8. 結果出力
   └─ 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[foreach SqlInstance]
    C --> E
    E --> F[Connect-DbaInstance]
    F --> G{接続成功?}
    G -->|No| H[エラー出力, Continue]
    G -->|Yes| I{Database存在?}
    I -->|No| J[エラー出力, Continue]
    I -->|Yes| K[既存プロシージャ取得]
    K --> L{Procedure = All?}
    L -->|Yes| M[DarlingData.sql取得]
    L -->|No| N[指定プロシージャのみ取得]
    M --> O[foreach script]
    N --> O
    O --> P{sp_QuickieStore?}
    P -->|Yes| Q{Version >= 13?}
    Q -->|No| R[Status = Skipped]
    Q -->|Yes| S[Invoke-DbaQuery実行]
    P -->|No| S
    R --> 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 --> O
    H --> E
    J --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン制限 | sp_QuickieStoreはSQL Server 2016（バージョン13）以上が必要 | sp_QuickieStore実行時 |
| BR-002 | デフォルトデータベース | Database未指定時はmasterを使用 | 常時 |
| BR-003 | ブランチ選択 | main（安定版）またはdev（開発版）から選択 | 常時 |
| BR-004 | キャッシュ使用 | Force未指定時はローカルキャッシュを使用 | ダウンロード時 |
| BR-005 | プロシージャ省略名 | Human/Pressure/Quickie等の省略名をサポート | Procedure指定時 |
| BR-006 | ステータス判定 | 既存プロシージャはUpdated、新規はInstalled | インストール完了時 |

### インストール可能プロシージャ一覧

| 省略名 | 完全名 | ファイル名 | 用途 |
|--------|--------|------------|------|
| Human | HumanEvents | sp_HumanEvents.sql | 拡張イベント分析 |
| Pressure | PressureDetector | sp_PressureDetector.sql | メモリ圧迫監視 |
| Quickie | QuickieStore | sp_QuickieStore.sql | Query Store分析（SQL 2016+） |
| 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 | SELECT | is_ms_shipped = 0の一覧取得 |
| プロシージャ作成/更新 | - | CREATE/ALTER PROCEDURE | ストアドプロシージャのインストール |

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

#### sys.procedures

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

- ローカルキャッシュによりダウンロード回数を最小化
- Invoke-DbaQueryで長いバッチを効率的に実行

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

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

## 備考

- DarlingDataはErik Darling氏（erikdarling.com）が提供するコミュニティツール
- mainブランチは安定版、devブランチは最新機能を含む
- SupportsShouldProcess対応（WhatIf/Confirm）

---

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

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

### 推奨読解順序

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

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

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

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

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

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

**主要処理フロー**:
- **146行目**: Path.DbatoolsDataから設定取得
- **147行目**: ローカルキャッシュパス構築
- **148行目**: キャッシュ有無判定
- **151行目**: Save-DbaCommunitySoftware呼び出し

#### Step 3: プロシージャ選択を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Install-DbaDarlingData.ps1 | `public/Install-DbaDarlingData.ps1` | 181-211行目のスクリプト選択ロジック |

**主要処理フロー**:
- **181-183行目**: All指定時はDarlingData.sqlのみ
- **187-210行目**: 個別プロシージャ指定時のフィルタリング

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Install-DbaDarlingData.ps1 | `public/Install-DbaDarlingData.ps1` | 213-251行目のスクリプト実行ループ |

**主要処理フロー**:
- **227-232行目**: sp_QuickieStoreのバージョンチェック
- **236行目**: Invoke-DbaQueryでスクリプト実行
- **242-248行目**: Status判定ロジック

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

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

### データフロー図

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

GitHub/LocalFile ─────▶ Save-DbaCommunitySoftware ───▶ ローカルキャッシュ
        │                                                    │
        ▼                                                    ▼
Branch (main/dev) ──────────────────────────────────▶ キャッシュパス選択
        │                                                    │
        ▼                                                    ▼
SqlInstance ───────────▶ Connect-DbaInstance ───────▶ Server オブジェクト
        │                                                    │
        ▼                                                    ▼
Database ──────────────▶ データベース検証 ─────────▶ 対象DB
        │                                                    │
        ▼                                                    ▼
Procedure ─────────────▶ スクリプト選択 ─────────▶ SQLスクリプト一覧
        │                                                    │
        ▼                                                    ▼
                                              Invoke-DbaQuery
                                                       │
                                                       ▼
                                              PSCustomObject（Status付き）
                                                       │
                                                       ▼
                                              パイプライン出力
```

### 関連ファイル一覧

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