# 機能設計書 323-Install-DbaSqlWatch

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Install-DbaSqlWatch` 機能の設計書である。SqlWatch監視ソリューションをSQL Serverインスタンスにデプロイし、パフォーマンスメトリクス収集と履歴分析を可能にする機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのパフォーマンス監視は、データベース管理者にとって重要な業務である。高価なサードパーティ監視ツールを導入せずに、オープンソースのSqlWatchを活用することで、待機統計、パフォーマンスメトリクス、システム情報を継続的に収集し、履歴分析やアラート機能を実現できる。本機能は、SqlWatchのインストールを自動化し、複数インスタンスへの一括展開を可能にする。

**機能の利用シーン**：新規SQL Server環境での監視基盤構築、既存監視ソリューションからの移行、開発・テスト環境でのパフォーマンス分析、オフライン環境でのSqlWatchデプロイ、SqlWatchのバージョンアップグレードなどで利用される。

**主要な処理内容**：
1. GitHubから最新版のSqlWatchをダウンロード（またはローカルファイルを使用）
2. ローカルキャッシュに保存
3. 指定されたSQL Serverインスタンスに接続
4. DACPACを使用してSqlWatchデータベースオブジェクトをデプロイ
5. デプロイ結果と ダッシュボードパスを返却

**関連システム・外部連携**：
- GitHub（SqlWatchリポジトリ: https://github.com/marcingminski/sqlwatch）
- Save-DbaCommunitySoftware（ダウンロード処理）
- New-DbaDacProfile / Publish-DbaDacPackage（DACPACデプロイ）

**権限による制御**：ターゲットデータベースでのDACPACデプロイ権限が必要。通常はdb_owner、db_ddladmin、またはsysadmin権限で実行される。

## 関連画面

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

## 機能種別

インストール処理 / DACPACデプロイ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | ターゲットSQL Serverインスタンス | パイプラインから受け取り可能 |
| SqlCredential | PSCredential | No | 認証用資格情報 | Windows/SQL認証対応 |
| Database | string | No | インストール先データベース（デフォルト: SQLWATCH） | tempdb不可 |
| LocalFile | string | No | ローカルZIPファイルパス | - |
| PreRelease | switch | No | プレリリース版をインストール | - |
| Force | switch | No | キャッシュを無視して再ダウンロード | - |
| EnableException | switch | No | 例外を有効化 | - |
| Confirm | switch | No | 確認プロンプト表示 | SupportsShouldProcess |
| WhatIf | switch | No | 実行内容の表示のみ | SupportsShouldProcess |

### 入力データソース

- GitHub: SqlWatchリリースから最新版を取得
- ローカルファイル: LocalFileパラメータで指定されたZIPファイル
- ローカルキャッシュ: dbatoolsデータディレクトリ内のキャッシュ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | インストール先データベース名 |
| Status | object | DACPACデプロイ結果のステータス |
| DashboardPath | string | SqlWatchダッシュボードのローカルパス |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. beginブロック：初期検証とキャッシュ更新
   └─ tempdbインストール不可チェック
   └─ Force/PreRelease/キャッシュ状態に応じてダウンロード
2. processブロック：PowerShell Core非対応チェック
   └─ PS Coreでは処理中断
3. 各インスタンスに対してConnect-DbaInstanceで接続
4. DACPACファイルの検索
   └─ SqlWatch.dacpacをキャッシュから取得
5. DACプロファイル作成
   └─ New-DbaDacProfileでPublishOptionsを設定
6. DACPACデプロイ
   └─ Publish-DbaDacPackageで実行
7. 結果解析と出力
   └─ Select-Stringで結果を解析、オブジェクト出力
8. クリーンアップ
   └─ 一時プロファイルファイル削除
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Database=tempdb?}
    B -->|Yes| C[エラー終了]
    B -->|No| D{Force/PreRelease/<br>キャッシュ不在?}
    D -->|Yes| E[Save-DbaCommunitySoftwareで<br>ダウンロード]
    D -->|No| F[キャッシュを使用]
    E --> F
    F --> G{PowerShell Core?}
    G -->|Yes| H[エラー：非対応]
    G -->|No| I[各SqlInstanceをループ]
    I --> J[Connect-DbaInstance]
    J --> K{接続成功?}
    K -->|No| L[エラー出力して次へ]
    K -->|Yes| M[SqlWatch.dacpac検索]
    M --> N[New-DbaDacProfile]
    N --> O[Publish-DbaDacPackage]
    O --> P{デプロイ成功?}
    P -->|No| Q[エラー出力]
    P -->|Yes| R[結果解析]
    R --> S[結果オブジェクト出力]
    Q --> T{次のインスタンス?}
    S --> U[プロファイルファイル削除]
    U --> T
    L --> T
    T -->|Yes| I
    T -->|No| V[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-323-01 | tempdb除外 | tempdbへのインストール不可 | Database=tempdb指定時 |
| BR-323-02 | PS Core非対応 | PowerShell Coreでは実行不可 | $PSEdition='Core'時 |
| BR-323-03 | DAC登録 | RegisterDataTierApplication=trueで登録 | 常時 |
| BR-323-04 | プレリリース | PreRelease指定でプレリリース版を使用 | PreRelease指定時 |

### 計算ロジック

キャッシュパス決定ロジック：
- PreRelease指定: `{dbatoolsData}/SQLWATCH-prerelease`
- 通常: `{dbatoolsData}/SQLWATCH`

ブランチ決定ロジック：
- PreRelease指定: 'prerelease'
- 通常: 'release'

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DACPACデプロイ | SqlWatch関連テーブル | DDL/DML | テーブル、ビュー、プロシージャ等の作成/更新 |

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

SqlWatchによって多数のテーブル、ビュー、ストアドプロシージャが作成される。詳細はSqlWatch公式ドキュメントを参照。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ValidationError | tempdb指定 | Stop-Functionで処理中断 |
| - | PlatformError | PowerShell Core使用 | Stop-Functionで処理中断 |
| - | ConnectionError | インスタンス接続失敗 | Stop-Functionで処理継続 |
| - | DownloadError | GitHubダウンロード失敗 | Stop-Functionで処理中断 |
| - | DeployError | DACPACデプロイ失敗 | Stop-Functionで処理継続 |

### リトライ仕様

明示的なリトライ機能は実装されていない。Forceパラメータで再ダウンロードを試行可能。

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

DACPACデプロイはPublish-DbaDacPackageによって管理される。失敗時はデプロイが中断され、部分的な変更がロールバックされる可能性がある。

## パフォーマンス要件

特に定義されていない。Write-ProgressHelperで進捗表示を行う。

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

- Windows認証およびSQL認証に対応
- MFAサポートはConnect-DbaInstanceを事前に使用
- Azure Active Directory認証対応
- 資格情報はPSCredentialオブジェクトとして安全に管理

## 備考

- SqlWatch公式サイト: https://sqlwatch.io
- 作者: Ken K (github.com/koglerk)
- PowerShell Coreは非対応（Windows PowerShellが必要）

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を把握することから始める。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaSqlWatch.ps1 | `public/Install-DbaSqlWatch.ps1` | 183-190行目のPSCustomObject定義 |

**読解のコツ**: DashboardPathプロパティはローカルキャッシュパスにダッシュボードサブディレクトリを追加したもの。

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

パラメータ定義と初期検証を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaSqlWatch.ps1 | `public/Install-DbaSqlWatch.ps1` | 104-114行目のparam定義 |
| 2-2 | Install-DbaSqlWatch.ps1 | `public/Install-DbaSqlWatch.ps1` | 115-143行目のbeginブロック |

**主要処理フロー**:
1. **104-114行目**: パラメータ定義（Database=SQLWATCH がデフォルト）
2. **119-126行目**: キャッシュパスとブランチ決定（PreRelease考慮）
3. **139-142行目**: tempdbチェック

#### Step 3: DACPACデプロイ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Install-DbaSqlWatch.ps1 | `public/Install-DbaSqlWatch.ps1` | 165-191行目のDACPAC処理 |

**主要処理フロー**:
- **167行目**: Get-ChildItemでSqlWatch.dacpac検索
- **168-170行目**: PublishOptionsでRegisterDataTierApplication設定
- **173行目**: New-DbaDacProfileでプロファイル生成
- **174行目**: Publish-DbaDacPackageでデプロイ
- **175行目**: Remove-Itemでプロファイル削除

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

```
Install-DbaSqlWatch
    │
    ├─ Get-DbatoolsConfigValue
    │      └─ dbatools設定からデータディレクトリパス取得
    │
    ├─ Join-DbaPath
    │      └─ キャッシュパスの構築
    │
    ├─ Save-DbaCommunitySoftware
    │      └─ GitHubからのダウンロードとキャッシュ保存
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Serverへの接続（SMOオブジェクト作成）
    │
    ├─ Get-ChildItem
    │      └─ DACPACファイルの検索
    │
    ├─ New-DbaDacProfile
    │      └─ DAC発行プロファイル生成
    │
    └─ Publish-DbaDacPackage
           └─ DACPACデプロイ実行
```

### データフロー図

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

GitHubリポジトリ ───▶ Save-DbaCommunitySoftware ───▶ ローカルキャッシュ
       or                     │
ローカルZIPファイル           │
                              ▼
                    Get-ChildItem（DACPAC取得）
                              │
                              ▼
                    New-DbaDacProfile
                        （プロファイル生成）
                              │
SqlInstance ───────▶ Connect-DbaInstance
                              │
                              ▼
                    Publish-DbaDacPackage
                       （DACPACデプロイ）
                              │
                              ▼
                        PSCustomObject
                    （デプロイ結果）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaSqlWatch.ps1 | `public/Install-DbaSqlWatch.ps1` | ソース | メイン関数の実装 |
| Save-DbaCommunitySoftware.ps1 | `private/functions/Save-DbaCommunitySoftware.ps1` | ソース | コミュニティソフトウェアのダウンロード |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| New-DbaDacProfile.ps1 | `public/New-DbaDacProfile.ps1` | ソース | DACプロファイル生成 |
| Publish-DbaDacPackage.ps1 | `public/Publish-DbaDacPackage.ps1` | ソース | DACPACデプロイ |
