# 機能設計書 8-Compare-DbaAgReplicaSync

## 概要

本ドキュメントは、dbatools PowerShellモジュールのCompare-DbaAgReplicaSync機能の設計仕様を定義する。本機能は、可用性グループ（AG）の全レプリカ間でサーバーレベルオブジェクトの同期状態を包括的に比較し、フェイルオーバー準備状況を評価する。

### 本機能の処理概要

Compare-DbaAgReplicaSyncは、可用性グループに参加しているすべてのレプリカ間で複数種類のサーバーレベルオブジェクトを一括比較し、同期差異を検出するPowerShellコマンドである。可用性グループはデータベースのみを同期するため、サーバーレベルオブジェクトは手動管理が必要である。本機能は、これらの不整合を包括的に検出する。

**業務上の目的・背景**：可用性グループ環境でのフェイルオーバー後、アプリケーションが正常に動作するためには、データベースだけでなく、ログイン、ジョブ、資格情報、リンクサーバーなど多くのサーバーレベルオブジェクトが必要である。これらが欠落していると、フェイルオーバー後に様々な問題が発生する。本機能は、1回の実行で複数種類のオブジェクトを比較し、フェイルオーバー準備状況を総合的に評価する。

**機能の利用シーン**：
- フェイルオーバー前の総合準備状況確認
- 定期的な構成ドリフト監視
- DR訓練前の事前チェック
- 運用監査レポートの生成

**主要な処理内容**：
1. 可用性グループとレプリカの取得
2. 各種オブジェクトの比較（Exclude指定可能）：
   - Logins（ログイン）
   - AgentJob（ジョブ）
   - Credentials（資格情報）
   - LinkedServers（リンクサーバー）
   - AgentOperator（オペレーター）
   - AgentAlert（アラート）
   - AgentProxy（プロキシ）
   - CustomErrors（カスタムエラー）
3. 各オブジェクトについて欠落・差異を検出
4. 差異の出力

**関連システム・外部連携**：
- SQL Server SMO (Server Management Objects)
- SQL Server Agent
- リンクサーバー接続先

**権限による制御**：
- 各レプリカへの接続権限
- 各種オブジェクトの参照権限

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | AGレプリカ管理 | 補助機能 | レプリカ間のサーバーレベルオブジェクト同期比較 |

## 機能種別

比較/検証処理 / 総合構成監査

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | パイプライン対応 |
| SqlCredential | PSCredential | No | SQL Server接続用認証情報 | - |
| AvailabilityGroup | string[] | No | 可用性グループ名フィルタ | - |
| Exclude | string[] | No | 除外するオブジェクト種別 | ValidateSet |
| EnableException | switch | No | 例外有効化 | - |

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

- SpConfigure
- CustomErrors
- Credentials
- DatabaseMail
- LinkedServers
- Logins
- SystemTriggers
- AgentCategory
- AgentOperator
- AgentAlert
- AgentProxy
- AgentSchedule
- AgentJob

### 入力データソース

- SQL Serverインスタンスへの直接接続
- 各レプリカへの個別接続

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AvailabilityGroup | string | 可用性グループ名 |
| Replica | string | レプリカインスタンス名 |
| ObjectType | string | オブジェクト種別 |
| ObjectName | string | オブジェクト名 |
| Status | string | 状態（Missing/Different） |
| PropertyDifferences | string | プロパティ差異詳細（Login時） |

### 出力先

- PowerShellパイプライン（PSCustomObject）
- 差異がある場合のみ出力

## 処理フロー

### 処理シーケンス

```
1. インスタンス接続
   └─ Connect-DbaInstance（MinimumVersion 11）

2. HADR有効確認
   └─ IsHadrEnabledチェック

3. 可用性グループ取得
   └─ AvailabilityGroupパラメータでフィルタ

4. 各AGについてレプリカ一覧取得
   └─ 2レプリカ未満は比較スキップ

5. 各オブジェクト種別について比較（Exclude除外）
   5a. Logins比較
       └─ 存在チェック + プロパティ比較
   5b. AgentJob比較
       └─ 存在チェック
   5c. Credentials比較
       └─ 存在チェック
   5d. LinkedServers比較
       └─ 存在チェック
   5e. AgentOperator比較
       └─ 存在チェック
   5f. AgentAlert比較
       └─ 存在チェック
   5g. AgentProxy比較
       └─ 存在チェック
   5h. CustomErrors比較
       └─ 存在チェック

6. 結果出力
   └─ Missing または Different の場合
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{HADR有効?}
    C -->|No| Z1[エラー]
    C -->|Yes| D[AG取得]
    D --> E[各AGをループ]
    E --> F{レプリカ>=2?}
    F -->|No| G[スキップ]
    F -->|Yes| H{Logins除外?}
    G --> E
    H -->|No| I[Logins比較]
    H -->|Yes| J{AgentJob除外?}
    I --> J
    J -->|No| K[AgentJob比較]
    J -->|Yes| L{Credentials除外?}
    K --> L
    L -->|No| M[Credentials比較]
    L -->|Yes| N{LinkedServers除外?}
    M --> N
    N -->|No| O[LinkedServers比較]
    N -->|Yes| P{AgentOperator除外?}
    O --> P
    P -->|No| Q[AgentOperator比較]
    P -->|Yes| R{AgentAlert除外?}
    Q --> R
    R -->|No| S[AgentAlert比較]
    R -->|Yes| T{AgentProxy除外?}
    S --> T
    T -->|No| U[AgentProxy比較]
    T -->|Yes| V{CustomErrors除外?}
    U --> V
    V -->|No| W[CustomErrors比較]
    V -->|Yes| X[次のAG]
    W --> X
    X --> E
    E --> Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | SQLバージョン要件 | SQL Server 2012以上が必要 | 常時 |
| BR-02 | HADR必須 | HADRが有効でない場合はエラー | 常時 |
| BR-03 | 最小レプリカ数 | 2レプリカ未満は比較対象外 | 常時 |
| BR-04 | Exclude制御 | 指定種別は比較しない | Exclude指定時 |
| BR-05 | Login詳細比較 | Missingだけでなくプロパティ差異も検出 | Logins比較時 |

### 計算ロジック

- ログインプロパティ比較: IsDisabled, DenyWindowsLogin, DefaultDatabase, Language, PasswordExpirationEnabled, PasswordPolicyEnforced, ServerRoles

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ログイン取得 | master.sys.server_principals | SELECT | ログイン一覧 |
| ジョブ取得 | msdb.dbo.sysjobs | SELECT | ジョブ一覧 |
| 資格情報取得 | master.sys.credentials | SELECT | 資格情報一覧 |
| リンクサーバー取得 | master.sys.servers | SELECT | リンクサーバー一覧 |
| オペレーター取得 | msdb.dbo.sysoperators | SELECT | オペレーター一覧 |
| アラート取得 | msdb.dbo.sysalerts | SELECT | アラート一覧 |
| プロキシ取得 | msdb.dbo.sysproxies | SELECT | プロキシ一覧 |
| カスタムエラー取得 | master.sys.messages | SELECT | ユーザー定義メッセージ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | 接続情報確認 |
| - | HADRError | HADRが有効でない | HADR有効化確認 |
| - | NoAGError | 指定AGが見つからない | AG名確認 |
| - | ReplicaError | レプリカ接続失敗 | レプリカ接続確認 |

### リトライ仕様

- 本機能にリトライロジックは実装されていない

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

- 読み取り専用処理のためトランザクション不要

## パフォーマンス要件

- 複数種類のオブジェクトを比較するため処理時間を要する
- 大規模環境ではオブジェクト数に比例

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

- 各種オブジェクトの参照権限が必要
- パスワード、秘密情報は比較しない

## 備考

- Loginsは存在チェックに加えてプロパティ詳細比較を実行
- サーバーロールメンバーシップも比較対象
- Compare-Objectを使用したロール比較

---

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

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

### 推奨読解順序

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

パラメータ構造とExcludeのValidateSetを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | param()ブロック（97-106行目） |
| 1-2 | Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | ValidateSetによるExclude値（103行目） |

#### Step 2: Logins比較ロジックを理解する

最も詳細な比較を行うLogins処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | Logins比較ブロック（143-287行目） |

**主要処理フロー**:
- **155行目**: Get-DbaLoginでログイン取得
- **181-196行目**: ログイン構成の構築（IsDisabled, DefaultDatabase等）
- **199-212行目**: サーバーロール取得
- **238-272行目**: プロパティ差異検出とPropertyDifferences生成
- **262-272行目**: Compare-Objectでロール比較

#### Step 3: 他オブジェクト比較を理解する

ジョブ、資格情報、リンクサーバー等の比較を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | AgentJob比較（289-329行目） |
| 3-2 | Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | Credentials比較（331-371行目） |
| 3-3 | Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | LinkedServers比較（373-413行目） |
| 3-4 | Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | AgentOperator比較（415-455行目） |
| 3-5 | Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | AgentAlert比較（457-497行目） |
| 3-6 | Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | AgentProxy比較（499-539行目） |
| 3-7 | Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | CustomErrors比較（541-581行目） |

**主要処理フロー**:
- 各比較ブロックはExclude判定から開始
- オブジェクト収集→全名前ユニオン→存在チェック→Missing出力

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

```
Compare-DbaAgReplicaSync
    │
    ├─ Connect-DbaInstance (初期接続)
    │
    ├─ server.AvailabilityGroups (AG取得)
    │
    ├─ ag.AvailabilityReplicas (レプリカ取得)
    │
    └─ 各オブジェクト種別について
           │
           ├─ Logins
           │     ├─ Get-DbaLogin
           │     ├─ server.Roles.EnumMemberNames()
           │     └─ Compare-Object (ロール比較)
           │
           ├─ AgentJob
           │     └─ Get-DbaAgentJob
           │
           ├─ Credentials
           │     └─ server.Credentials
           │
           ├─ LinkedServers
           │     └─ server.LinkedServers
           │
           ├─ AgentOperator
           │     └─ Get-DbaAgentOperator
           │
           ├─ AgentAlert
           │     └─ Get-DbaAgentAlert
           │
           ├─ AgentProxy
           │     └─ Get-DbaAgentProxy
           │
           └─ CustomErrors
                 └─ server.UserDefinedMessages
```

### データフロー図

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

SqlInstance ─────────────▶ Connect-DbaInstance
                                  │
AvailabilityGroup ────────▶ AG取得・フィルタ
                                  │
Exclude ─────────────────▶ オブジェクト種別判定
                                  │
                    ┌─────────────┴─────────────┐
                    │   各オブジェクト比較      │
                    │                           │
                    │  Logins (詳細比較)        │
                    │  AgentJob (存在)          │
                    │  Credentials (存在)       │
                    │  LinkedServers (存在)     │
                    │  AgentOperator (存在)     │
                    │  AgentAlert (存在)        │
                    │  AgentProxy (存在)        │
                    │  CustomErrors (存在)      │
                    └─────────────┬─────────────┘
                                  │
                                  ▼
                          PSCustomObject
                          (Missing/Different)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Compare-DbaAgReplicaSync.ps1 | `public/Compare-DbaAgReplicaSync.ps1` | ソース | メインコマンド実装 |
| Get-DbaLogin.ps1 | `public/Get-DbaLogin.ps1` | ソース | ログイン取得 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ取得 |
| Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | ソース | オペレーター取得 |
| Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | ソース | アラート取得 |
| Get-DbaAgentProxy.ps1 | `public/Get-DbaAgentProxy.ps1` | ソース | プロキシ取得 |
