# 機能設計書 238-Test-DbaAvailabilityGroup

## 概要

本ドキュメントは、dbatools PowerShellモジュールのTest-DbaAvailabilityGroup関数に関する機能設計書です。この関数は可用性グループのレプリカ接続性とデータベース追加の前提条件を検証します。

### 本機能の処理概要

**業務上の目的・背景**：可用性グループの全てのレプリカが正常に接続・通信していることを確認し、フェイルオーバー能力やデータ同期に影響する接続問題を特定します。また、Add-DbaAgDatabaseでデータベースを追加する前に、包括的な前提条件検証を行い、構成問題を早期に発見してAG設定の失敗を防止します。

**機能の利用シーン**：可用性グループのヘルスチェック時、データベースをAGに追加する前の検証時、フェイルオーバーテストの準備時、AG構成のトラブルシューティング時に使用されます。

**主要な処理内容**：
1. プライマリレプリカへの接続
2. 可用性グループの取得と検証
3. 全レプリカの接続状態（ConnectionState）確認
4. AddDatabase指定時：データベースの前提条件検証
   - 完全復旧モデルの確認
   - データベースステータスの確認
   - バックアップ履歴の確認（UseLastBackup時）
   - セカンダリレプリカへの接続テスト
   - シード方式の検証

**関連システム・外部連携**：SQL Server Management Objects (SMO)、Get-DbaAvailabilityGroup、Get-DbaDbBackupHistoryを使用します。

**権限による制御**：可用性グループの参照権限が必要です。

## 関連画面

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

## 機能種別

検証処理（Validation / Test）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | Yes | プライマリレプリカのインスタンス | 必須 |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 | - |
| AvailabilityGroup | string | Yes | 可用性グループ名 | 必須 |
| Secondary | DbaInstanceParameter[] | No | セカンダリレプリカ（カスタムポート等用） | - |
| SecondarySqlCredential | PSCredential | No | セカンダリ接続用資格情報 | - |
| AddDatabase | string[] | No | AGに追加検証するデータベース名 | - |
| SeedingMode | string | No | シード方式（Automatic/Manual） | ValidateSet |
| SharedPath | string | No | 手動シード用の共有パス | - |
| UseLastBackup | switch | No | 最新バックアップを使用 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数
- SQL Serverインスタンスからの可用性グループ構成情報

## 出力仕様

### 出力データ（AddDatabase未指定時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| AvailabilityGroup | string | 可用性グループ名 |

### 出力データ（AddDatabase指定時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| AvailabilityGroupName | string | 可用性グループ名 |
| DatabaseName | string | データベース名 |
| AvailabilityGroupSMO | AvailabilityGroup | AGのSMOオブジェクト |
| DatabaseSMO | Database | データベースのSMOオブジェクト |
| PrimaryServerSMO | Server | プライマリのSMOオブジェクト |
| ReplicaServerSMO | Hashtable | セカンダリのSMOオブジェクト（辞書） |
| RestoreNeeded | Hashtable | リストア必要フラグ（辞書） |
| Backups | object[] | バックアップ履歴（UseLastBackup時） |

### 出力先

- パイプラインにPSCustomObjectとして出力

## 処理フロー

### 処理シーケンス

```
1. プライマリレプリカ接続
   └─ Connect-DbaInstanceで接続
2. 可用性グループ取得
   └─ Get-DbaAvailabilityGroupで取得
3. ローカルレプリカロール確認
   └─ Primaryであることを確認
4. レプリカ接続状態確認
   └─ 全レプリカのConnectionStateを確認
5. AddDatabase処理（指定時）
   ├─ データベース存在確認
   ├─ 復旧モデル確認（Full必須）
   ├─ ステータス確認（Normal必須）
   ├─ バックアップ履歴確認（UseLastBackup時）
   ├─ セカンダリ接続テスト
   ├─ シード方式判定
   └─ 結果オブジェクト生成
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[プライマリ接続]
    B --> C{接続成功?}
    C -->|No| D[エラー終了]
    C -->|Yes| E[AG取得]
    E --> F{AG存在?}
    F -->|No| D
    F -->|Yes| G{ローカルロール=Primary?}
    G -->|No| D
    G -->|Yes| H[全レプリカConnectionState確認]
    H --> I{全てConnected?}
    I -->|No| D
    I -->|Yes| J{AddDatabase指定?}
    J -->|No| K[基本情報出力]
    J -->|Yes| L[データベース検証]
    L --> M{DB存在?}
    M -->|No| N[エラー・次のDB]
    M -->|Yes| O{RecoveryModel=Full?}
    O -->|No| N
    O -->|Yes| P{Status=Normal?}
    P -->|No| N
    P -->|Yes| Q[セカンダリ接続テスト]
    Q --> R[シード方式判定]
    R --> S[結果オブジェクト生成]
    K --> T[終了]
    S --> T
    N --> T
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Primary必須 | ローカルレプリカがPrimaryでなければエラー | 常時 |
| BR-002 | Connected必須 | 全レプリカがConnected状態でなければエラー | 常時 |
| BR-003 | Full復旧モデル必須 | データベースがFull復旧モデルでなければエラー | AddDatabase時 |
| BR-004 | Normal状態必須 | データベースがNormal状態でなければエラー | AddDatabase時 |
| BR-005 | ログバックアップ必須 | UseLastBackup時は最後のバックアップがログ必須 | UseLastBackup時 |
| BR-006 | Automaticシード | SQL Server 2016以上でのみ使用可能 | SeedingMode=Automatic時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| AG情報取得 | sys.availability_groups | SELECT | SMO経由で取得 |
| レプリカ情報取得 | sys.availability_replicas | SELECT | SMO経由で取得 |
| DB情報取得 | sys.databases | SELECT | SMO経由で取得 |
| バックアップ履歴 | msdb.dbo.backupset | SELECT | Get-DbaDbBackupHistory経由 |

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

参照のみでデータ変更はありません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | プライマリ/セカンダリ接続失敗 | 接続情報確認 |
| AGNotFound | AG未検出 | 指定AGが存在しない | AG名確認 |
| NotPrimary | ロールエラー | 接続先がPrimaryでない | Primary接続 |
| NotConnected | 接続状態エラー | レプリカがConnectedでない | ネットワーク確認 |
| RecoveryModelError | 復旧モデルエラー | Full以外の復旧モデル | 復旧モデル変更 |
| StatusError | ステータスエラー | Normal以外のステータス | DB状態確認 |

### リトライ仕様

リトライ処理は実装されていません。エラー発生時はStop-Functionで処理を継続（Continue）します。

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

読み取り専用のため、トランザクション管理は不要です。

## パフォーマンス要件

- レプリカ数に比例して接続テスト時間が増加
- バックアップ履歴取得はデータ量に依存

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

- 可用性グループの参照権限が必要
- SqlCredential/SecondarySqlCredential使用時はSecureStringで資格情報を保護

## 備考

- Add-DbaAgDatabaseの前処理として使用することを推奨
- 出力のSMOオブジェクトはAdd-DbaAgDatabaseで再利用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaAvailabilityGroup.ps1 | `public/Test-DbaAvailabilityGroup.ps1` | パラメータ定義（100-114行目） |
| 1-2 | Test-DbaAvailabilityGroup.ps1 | `public/Test-DbaAvailabilityGroup.ps1` | 出力オブジェクト構造（167-173, 321-333行目） |

**読解のコツ**: AddDatabase指定の有無で出力構造が大きく異なります。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaAvailabilityGroup.ps1 | `public/Test-DbaAvailabilityGroup.ps1` | process block - 基本検証（115-173行目） |

**主要処理フロー**:
1. **116-121行目**: プライマリ接続
2. **123-133行目**: AG取得と存在確認
3. **135-138行目**: ローカルレプリカロール確認
4. **151-161行目**: 全レプリカのConnectionState確認
5. **166-173行目**: AddDatabase未指定時の基本情報出力

#### Step 3: AddDatabase検証を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaAvailabilityGroup.ps1 | `public/Test-DbaAvailabilityGroup.ps1` | AddDatabase処理（178-334行目） |

**主要処理フロー**:
- **181-184行目**: Automaticシードのバージョン確認
- **186-188行目**: データベース存在確認
- **192-194行目**: 復旧モデル確認
- **196-198行目**: ステータス確認
- **201-210行目**: バックアップ履歴確認（UseLastBackup時）
- **220-310行目**: セカンダリレプリカ検証ループ
- **314-319行目**: リストア要否判定
- **321-333行目**: 結果オブジェクト生成

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

```
Test-DbaAvailabilityGroup
    │
    ├─ Connect-DbaInstance
    │      └─ プライマリ/セカンダリ接続
    │
    ├─ Get-DbaAvailabilityGroup
    │      └─ AG情報取得
    │
    └─ Get-DbaDbBackupHistory (条件付き)
           └─ バックアップ履歴取得
```

### データフロー図

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

SqlInstance ────────┐
                    │
AvailabilityGroup ──┼──▶ Test-DbaAvailabilityGroup ────────▶ PSCustomObject
                    │         │                              (基本情報 or
Secondary ──────────┤         ├─ Connect-DbaInstance          詳細検証結果)
                    │         ├─ Get-DbaAvailabilityGroup
AddDatabase ────────┤         ├─ ConnectionState確認
                    │         └─ DB前提条件検証
SeedingMode ────────┤
                    │
UseLastBackup ──────┘

[SQL Server AG] ◄───── SMO Query ─────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaAvailabilityGroup.ps1 | `public/Test-DbaAvailabilityGroup.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続ヘルパー |
| Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | ソース | AG情報取得 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得 |
| Add-DbaAgDatabase.ps1 | `public/Add-DbaAgDatabase.ps1` | ソース | 出力を利用する関連機能 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ヘルパー |
