# 画面設計書 212-SqlWatch

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける「SqlWatch」機能（Install-DbaSqlWatch、Uninstall-DbaSqlWatch）の画面設計書です。SqlWatchはオープンソースのSQL Serverパフォーマンス監視ツールで、パフォーマンスメトリクス、待機統計、システム情報を継続的に収集し、履歴分析やアラートを可能にします。

### 本画面の処理概要

**業務上の目的・背景**：SQL Server管理者は、サードパーティエージェントや高価な監視ソリューションなしで継続的なパフォーマンス監視を行うツールを必要としています。SqlWatchは、SQL Agentジョブを通じて自律的に実行され、定期的にパフォーマンスデータを収集・保存します。Webダッシュボードでメトリクスを可視化でき、特定の監視要件に合わせてカスタマイズ可能です。

**画面へのアクセス方法**：PowerShellコンソールから `Install-DbaSqlWatch` または `Uninstall-DbaSqlWatch` コマンドを実行します。

**主要な操作・処理内容**：
1. **Install-DbaSqlWatch**:
   - GitHubから最新のSqlWatchリリースをダウンロード
   - DACPAC技術を使用して指定データベースにデプロイ
   - パフォーマンスデータ収集用のデータベースオブジェクトを作成
   - SQL Agentジョブによる自動データ収集の設定
2. **Uninstall-DbaSqlWatch**:
   - SqlWatch関連のSQL Agentジョブを削除
   - ストアドプロシージャ、ビュー、関数、テーブルを削除
   - 拡張イベントセッション、Service Brokerコンポーネントを削除
   - アセンブリ、ユーザー定義テーブル型を削除
   - DACPACの登録を解除

**画面遷移**：CLIコマンドのため画面遷移はありません。内部的にSave-DbaCommunitySoftware、New-DbaDacProfile、Publish-DbaDacPackageを呼び出します。

**権限による表示制御**：SQL Serverへの接続には適切な認証が必要です。DACPACのデプロイおよびオブジェクトの作成/削除にはデータベースへの管理権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 323 | Install-DbaSqlWatch | 主機能 | SqlWatchのインストール |
| 326 | Uninstall-DbaSqlWatch | 主機能 | SqlWatchのアンインストール |

## 画面種別

コマンドライン（CLI）実行画面

## URL/ルーティング

```powershell
# インストール
Install-DbaSqlWatch -SqlInstance <インスタンス名> [-Database <データベース名>]

# アンインストール
Uninstall-DbaSqlWatch -SqlInstance <インスタンス名> [-Database <データベース名>]
```

## 入出力項目

### Install-DbaSqlWatch パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | ターゲットSQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 代替認証情報 |
| Database | string | No | SQLWATCH | インストール先データベース |
| LocalFile | string | No | - | ローカルzipファイルパス |
| PreRelease | switch | No | $false | プレリリース版をインストール |
| Force | switch | No | $false | キャッシュを無視して強制ダウンロード |
| EnableException | switch | No | $false | 例外を有効化 |

### Uninstall-DbaSqlWatch パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | ターゲットSQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 代替認証情報 |
| Database | string | No | master | 削除対象データベース |
| EnableException | switch | No | $false | 例外を有効化 |

## 表示項目

### Install-DbaSqlWatch 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverホストコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | インストール先データベース名 |
| Status | string | デプロイメントステータス |
| DashboardPath | string | SqlWatch Dashboardディレクトリへのパス |

### Uninstall-DbaSqlWatch 出力

このコマンドは出力オブジェクトを返しません。

## イベント仕様

### 1-Install-DbaSqlWatch実行時

1. Forceパラメータまたはキャッシュが存在しない場合、Save-DbaCommunitySoftwareを呼び出してSqlWatchをダウンロード
2. tempdbへのインストールは拒否（Stop-Function）
3. PowerShell Coreでの実行は拒否
4. SQL Serverインスタンスに接続
5. DACPACファイルを検索
6. New-DbaDacProfileでパブリッシュプロファイルを作成
7. Publish-DbaDacPackageでDACPACをパブリッシュ
8. パブリッシュ結果をパースして出力

### 2-Uninstall-DbaSqlWatch実行時

1. SQL Serverインスタンスに接続
2. SqlWatch関連オブジェクトを検索
   - テーブル: sqlwatch_*, dbachecks*, __RefactorLog
   - ビュー: vw_sqlwatch_*
   - ストアドプロシージャ: usp_sqlwatch_*, Stream*
   - 関数: ufn_sqlwatch_*, Get*, Read*
   - SQL Agentジョブ: SqlWatch-*
   - XEセッション: SQLWATCH_*
   - アセンブリ: SqlWatch*
   - テーブル型: utype_*
   - Service Broker: sqlwatch_*
3. 各オブジェクトを順次削除
4. DACPACの登録を解除

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Install | 多数のsqlwatch_*テーブル | INSERT | SqlWatchテーブル作成 |
| Install | sys.procedures | INSERT | ストアドプロシージャ作成 |
| Install | msdb.dbo.sysjobs | INSERT | SQL Agentジョブ作成 |
| Uninstall | sqlwatch_*テーブル | DELETE/DROP | テーブル削除 |
| Uninstall | sys.procedures | DELETE | プロシージャ削除 |
| Uninstall | msdb.dbo.sysjobs | DELETE | ジョブ削除 |

## メッセージ仕様

| 種別 | メッセージ | 発生条件 |
|------|----------|---------|
| エラー | Installation to tempdb not supported | tempdbへのインストール試行時 |
| エラー | PowerShell Core is not supported, please use Windows PowerShell | PowerShell Core使用時 |
| 警告 | Failed to update local cached copy | ダウンロード失敗時 |
| エラー | DACPAC failed to publish to {database} on {instance} | DACPACパブリッシュ失敗時 |
| Verbose | Removing {object type} from {database} on {server} | アンインストール時の各オブジェクト削除 |

## 例外処理

| 例外条件 | 動作 |
|---------|------|
| tempdbへのインストール | Stop-Functionで処理を中断 |
| PowerShell Core使用 | Stop-Functionで処理を中断 |
| 接続エラー | Stop-Functionでエラーを報告し、次のインスタンスに継続 |
| DACPACパブリッシュ失敗 | Stop-Functionでエラーを報告 |
| オブジェクト削除失敗 | Stop-Functionでエラーを報告し、次の処理に継続 |

## 備考

- SqlWatchはWindows PowerShellでのみサポートされています（PowerShell Coreは非対応）
- tempdbへのインストールはサポートされていません
- PreReleaseパラメータで開発中のベータ版をインストールできますが、本番環境での使用は推奨されません
- アンインストール時はすべての履歴データも削除されます

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaSqlWatch.ps1 | `public/Install-DbaSqlWatch.ps1` | Install出力オブジェクトの構造（行183-190） |
| 1-2 | Uninstall-DbaSqlWatch.ps1 | `public/Uninstall-DbaSqlWatch.ps1` | Uninstallは出力なし |

**読解のコツ**: Install-DbaSqlWatchのPSCustomObjectでPublishResultsからプロパティを取得している点に注目してください。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaSqlWatch.ps1 | `public/Install-DbaSqlWatch.ps1` | パラメータ定義と前提条件チェック |
| 2-2 | Uninstall-DbaSqlWatch.ps1 | `public/Uninstall-DbaSqlWatch.ps1` | オブジェクト検索と削除順序 |

**主要処理フロー (Install)**:
1. **行115-143**: beginブロックでキャッシュ確認とダウンロード
2. **行144-152**: PowerShell Coreチェックとtempdbチェック
3. **行165-174**: DACPACパブリッシュ処理

**主要処理フロー (Uninstall)**:
1. **行81-92**: SqlWatch関連オブジェクトの検索
2. **行94-208**: 各オブジェクトの順次削除
3. **行210-218**: DACPACの登録解除

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

```
Install-DbaSqlWatch
    │
    ├─ Save-DbaCommunitySoftware
    │      └─ GitHub Releases APIからダウンロード
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ New-DbaDacProfile
    │      └─ パブリッシュプロファイル作成
    │
    └─ Publish-DbaDacPackage
           └─ DACPACデプロイ

Uninstall-DbaSqlWatch
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ Get-DbaDbTable, Get-DbaDbView, Get-DbaDbStoredProcedure, etc.
    │      └─ SqlWatch関連オブジェクト検索
    │
    ├─ Remove-DbaAgentJob
    │      └─ SQL Agentジョブ削除
    │
    ├─ Remove-DbaXESession
    │      └─ 拡張イベントセッション削除
    │
    └─ DacServices.Unregister
           └─ DACPAC登録解除
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───────▶ Server SMO Object
      │
      ▼
GitHub Releases ───▶ Save-DbaCommunitySoftware ──▶ ローカルDACPAC
      │
      ▼
DACPAC ────────────▶ Publish-DbaDacPackage ──────▶ SqlWatchオブジェクト作成
      │
      ▼
                    PSCustomObject生成 ─────────▶ インストール結果出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaSqlWatch.ps1 | `public/Install-DbaSqlWatch.ps1` | ソース | インストールコマンド |
| Uninstall-DbaSqlWatch.ps1 | `public/Uninstall-DbaSqlWatch.ps1` | ソース | アンインストールコマンド |
| Save-DbaCommunitySoftware.ps1 | `public/Save-DbaCommunitySoftware.ps1` | ソース | ダウンロード機能 |
| New-DbaDacProfile.ps1 | `public/New-DbaDacProfile.ps1` | ソース | DACプロファイル作成 |
| Publish-DbaDacPackage.ps1 | `public/Publish-DbaDacPackage.ps1` | ソース | DACPACパブリッシュ |
| Get-DbaDbTable.ps1 | `public/Get-DbaDbTable.ps1` | ソース | テーブル取得 |
| Remove-DbaAgentJob.ps1 | `public/Remove-DbaAgentJob.ps1` | ソース | ジョブ削除 |
