# 機能設計書 270-Add-DbaDbMirrorMonitor

## 概要

本ドキュメントは、SQL Serverにデータベースミラーリングモニタージョブを作成するAdd-DbaDbMirrorMonitorコマンドレットの機能設計を記述する。

### 本機能の処理概要

Add-DbaDbMirrorMonitorは、SQL Serverインスタンス上のすべてのミラーリングされたデータベースのミラーリング状態を定期的に更新するデータベースミラーリングモニタージョブを作成するPowerShellコマンドレットである。内部的にはsp_dbmmonitoraddmonitoringストアドプロシージャを実行し、SQL Server Agentジョブを作成してミラーリング状態の監視を自動化する。

**業務上の目的・背景**：データベースミラーリングは高可用性ソリューションとして使用されるが、ミラーリング状態の継続的な監視が重要である。本コマンドは、ミラーリング環境のセットアップ後の監視設定、複数サーバーへの一括監視設定、ミラーリング状態の履歴記録といった業務課題を解決する。モニタージョブにより、ミラーリング状態がmsdb.dbo.dbm_monitor_dataテーブルに定期的に記録される。

**機能の利用シーン**：
- データベースミラーリング環境の初期セットアップ時
- 複数のミラーリングサーバーへの一括監視設定
- ミラーリング監視の再設定（誤削除後の復旧）
- 環境構築自動化スクリプトでの使用

**主要な処理内容**：
1. SQL Serverインスタンスへの接続（SQL Server 2005以降が必要）
2. ShouldProcess確認
3. sp_dbmmonitoraddmonitoringストアドプロシージャの実行
4. 作成結果をパイプライン出力

**関連システム・外部連携**：msdbデータベースのsp_dbmmonitoraddmonitoringストアドプロシージャを実行する。このプロシージャはSQL Server Agentジョブを作成し、定期的にミラーリング状態を更新する。

**権限による制御**：モニタージョブ作成には、sysadminサーバーロールのメンバーシップが必要。SQL Server 2005以降のバージョンが必要（MinimumVersion 9）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 35 | ミラーリング管理 | 補助機能 | ミラーリングモニターの追加 |

## 機能種別

実行処理（EXECUTE）/ 監視設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス | パイプライン入力対応、SQL Server 2005以降 |
| SqlCredential | PSCredential | No | 代替認証用資格情報 | Windows/SQL認証対応 |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- SqlInstance: ユーザー指定（パイプライン入力対応）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホスト名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| MonitorStatus | string | 操作結果（"Added"） |

### 出力先

パイプライン出力（PSCustomObject型）

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータの検証
   └─ SqlInstanceが必須

2. 各インスタンスへの接続
   └─ Connect-DbaInstance（MinimumVersion 9 = SQL Server 2005以降）

3. ShouldProcess確認
   └─ WhatIf/Confirm対応

4. ストアドプロシージャ実行
   └─ EXEC msdb.dbo.sp_dbmmonitoraddmonitoring

5. 結果の出力
   └─ MonitorStatus = "Added"を含むオブジェクト出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[foreachインスタンスループ]
    B --> C[Connect-DbaInstance MinVersion 9]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function継続]
    D -->|Yes| F[ShouldProcess確認]
    F --> G{確認OK?}
    G -->|No| H[スキップ]
    G -->|Yes| I[sp_dbmmonitoraddmonitoring実行]
    I --> J{成功?}
    J -->|Yes| K[結果オブジェクト作成]
    J -->|No| L[Stop-Function継続]
    K --> M[結果出力]
    M --> N{次のインスタンス?}
    E --> N
    H --> N
    L --> N
    N -->|Yes| B
    N -->|No| O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン要件 | SQL Server 2005以降が必要（MinimumVersion 9） | 常時 |
| BR-002 | ジョブ作成 | 既にモニタージョブが存在する場合はエラー | ジョブ重複時 |
| BR-003 | Agent必須 | SQL Server Agentが実行中である必要がある | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| ジョブ作成 | msdb.dbo.sysjobs | INSERT | ミラーリングモニタージョブの作成 |
| テーブル作成 | msdb.dbo.dbm_monitor_data | CREATE | モニターデータ格納テーブル（存在しない場合） |

### ストアドプロシージャ

#### sp_dbmmonitoraddmonitoring

実行されるストアドプロシージャ:
```sql
EXEC msdb.dbo.sp_dbmmonitoraddmonitoring
```

このプロシージャは以下を行う:
- ミラーリングモニタージョブの作成（"Database Mirroring Monitor Job"）
- デフォルトで1分間隔での状態更新設定
- msdb.dbo.dbm_monitor_dataテーブルへの状態記録

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverに接続できない | 接続設定・資格情報を確認 |
| - | バージョンエラー | SQL Server 2000以前 | SQL Server 2005以降にアップグレード |
| - | 既存ジョブエラー | モニタージョブが既に存在 | Remove-DbaDbMirrorMonitorで削除後に再実行 |
| - | Agent停止エラー | SQL Server Agentが停止中 | SQL Server Agentを開始 |

### リトライ仕様

なし（即時エラー終了、-Continue指定で次インスタンスへ継続）

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

sp_dbmmonitoraddmonitoring内部でトランザクション管理される

## パフォーマンス要件

ジョブ作成は即時完了

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

- sysadmin権限が必要
- 資格情報はPSCredentialオブジェクトで安全に受け渡し
- SupportsShouldProcess対応（WhatIf/Confirm）
- ConfirmImpact: Low

## 備考

- Get-DbaDbMirrorMonitorでモニター情報を取得可能
- Remove-DbaDbMirrorMonitorでモニタージョブを削除可能
- モニタージョブはデフォルトで1分間隔で実行される
- Tags: Mirroring, Mirror, HA

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Add-DbaDbMirrorMonitor.ps1 | `public/Add-DbaDbMirrorMonitor.ps1` | .OUTPUTSセクション（43-53行目）で出力プロパティを確認 |
| 1-2 | Add-DbaDbMirrorMonitor.ps1 | `public/Add-DbaDbMirrorMonitor.ps1` | パラメータ定義（59-65行目）を確認 |

**読解のコツ**: パラメータは非常にシンプルで、SqlInstanceのみが必須。出力もMonitorStatusのみが独自プロパティ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Add-DbaDbMirrorMonitor.ps1 | `public/Add-DbaDbMirrorMonitor.ps1` | processブロック（66行目）とCmdletBinding属性（59行目） |

**主要処理フロー**:
1. **61-62行目**: SqlInstanceパラメータ（Mandatory、パイプライン入力対応）
2. **63行目**: SqlCredentialパラメータ（オプション）
3. **64行目**: EnableExceptionパラメータ（オプション）

#### Step 3: 実行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Add-DbaDbMirrorMonitor.ps1 | `public/Add-DbaDbMirrorMonitor.ps1` | ストアドプロシージャ実行処理（67-88行目） |

**主要処理フロー**:
- **68-71行目**: Connect-DbaInstance（MinimumVersion 9）
- **74行目**: ShouldProcess確認
- **76行目**: server.Query()でsp_dbmmonitoraddmonitoring実行
- **77-82行目**: 結果オブジェクト作成（PSCustomObject）
- **83-85行目**: エラー時Stop-Function

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

```
Add-DbaDbMirrorMonitor
    │
    ├─ Connect-DbaInstance（MinimumVersion 9）
    │      └─ SQL Server接続
    │
    ├─ ShouldProcess確認
    │
    ├─ server.Query()
    │      └─ EXEC msdb.dbo.sp_dbmmonitoraddmonitoring
    │             ├─ Database Mirroring Monitor Jobの作成
    │             └─ dbm_monitor_dataテーブルの作成
    │
    └─ 結果オブジェクト出力
           └─ PSCustomObject
```

### データフロー図

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

SqlInstance ────────▶ Connect-DbaInstance
                              │
                              ▼
                        ShouldProcess確認
                              │
                              ▼
                    sp_dbmmonitoraddmonitoring
                              │
                              ▼
                   Database Mirroring Monitor Job
                              │
                              ▼
                     [PSCustomObject]
                     - ComputerName
                     - InstanceName
                     - SqlInstance
                     - MonitorStatus: "Added"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Add-DbaDbMirrorMonitor.ps1 | `public/Add-DbaDbMirrorMonitor.ps1` | ソース | メイン処理ロジック |
| Get-DbaDbMirrorMonitor.ps1 | `public/Get-DbaDbMirrorMonitor.ps1` | ソース | モニター情報取得 |
| Remove-DbaDbMirrorMonitor.ps1 | `public/Remove-DbaDbMirrorMonitor.ps1` | ソース | モニタージョブ削除 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
