# 画面設計書：AGフェイルオーバー

## 1. 基本情報

| 項目 | 内容 |
|------|------|
| 画面ID | 5 |
| 画面名 | AGフェイルオーバー |
| 画面種別 | CLI（コマンドラインインターフェース） |
| カテゴリ | AvailabilityGroup |
| 関連ファイル | public/Invoke-DbaAgFailover.ps1 |

## 2. 概要・目的

AGフェイルオーバーは、SQL Server AlwaysOn可用性グループの手動フェイルオーバーを実行するPowerShellコマンドです。指定されたSQL Serverインスタンス（セカンダリレプリカ）を新しいプライマリレプリカに昇格させます。

本コマンドは以下のシナリオで使用されます：
- 計画メンテナンス中のプライマリ切り替え
- ディザスタリカバリ対応
- 可用性グループのワークロード再配分

## 3. 主要機能

### 3.1 Invoke-DbaAgFailover

可用性グループの手動フェイルオーバーを実行します。

**フェイルオーバーモード：**

| モード | パラメータ | 説明 | データ損失リスク |
|--------|----------|------|-----------------|
| 安全フェイルオーバー | デフォルト | 全コミット済みトランザクションの同期を待機 | なし |
| 強制フェイルオーバー | -Force | 同期を待機せずに即座にフェイルオーバー | あり |

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | - | 対象SQL Serverインスタンス（SQL Server 2012以降） |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| AvailabilityGroup | string[] | 条件付き | - | フェイルオーバー対象の可用性グループ名 |
| InputObject | AvailabilityGroup[] | 条件付き | - | パイプライン入力用AGオブジェクト |
| Force | switch | いいえ | false | 強制フェイルオーバー（データ損失の可能性あり） |
| EnableException | switch | いいえ | false | 例外を有効化 |
| WhatIf | switch | いいえ | - | 実行せずに結果を表示 |
| Confirm | switch | いいえ | - | 実行前に確認プロンプト |

**出力プロパティ：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Name | string | 可用性グループ名 |
| PrimaryReplicaServerName | string | フェイルオーバー後のプライマリサーバー名 |
| LocalReplicaRole | string | ローカルレプリカの役割（Primary/Secondary） |
| AutomatedBackupPreference | string | バックアップ優先設定 |
| FailureConditionLevel | int | 自動フェイルオーバー条件レベル |
| HealthCheckTimeout | int | ヘルスチェックタイムアウト（ミリ秒） |
| BasicAvailabilityGroup | bool | Basic AGフラグ |
| ClusterType | string | クラスタータイプ（WSFC/External/None） |

**追加プロパティ（Select-Object *で取得可能）：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ID | int | 可用性グループID |
| UniqueId | Guid | グローバル一意識別子 |
| AvailabilityReplicas | Collection | レプリカコレクション |
| AvailabilityDatabases | Collection | データベースコレクション |
| AvailabilityGroupListeners | Collection | リスナーコレクション |
| DatabaseReplicaStates | Collection | データベースレプリカ状態 |
| RequiredSynchronizedSecondariesToCommit | int | コミット前に同期必要なセカンダリ数 |

## 4. 処理フロー

```
[開始]
   ↓
[パラメータ検証]
   ├── SqlInstanceまたはInputObjectの必須チェック
   ├── SqlInstance使用時はAvailabilityGroup必須
   ↓
[Force設定確認]
   ├── Force指定時はConfirmPreference='none'に設定
   ↓
[AGオブジェクト取得]
   ├── SqlInstance指定時はGet-DbaAvailabilityGroupで取得
   ↓
[フェイルオーバー実行]
   ├── [Forceあり]
   │     ├── ShouldProcess確認
   │     ├── FailoverWithPotentialDataLoss()実行
   │     ├── Refresh()で状態更新
   │     └── AGオブジェクト出力
   │
   └── [Forceなし]
         ├── ShouldProcess確認
         ├── Failover()実行
         ├── Refresh()で状態更新
         └── AGオブジェクト出力
   ↓
[終了]
```

## 5. SMOメソッドマッピング

| 操作 | SMOメソッド | 説明 |
|------|------------|------|
| 安全フェイルオーバー | AvailabilityGroup.Failover() | 同期完了後にフェイルオーバー |
| 強制フェイルオーバー | AvailabilityGroup.FailoverWithPotentialDataLoss() | 即座にフェイルオーバー |
| 状態更新 | AvailabilityGroup.Refresh() | SMOオブジェクトの状態を更新 |

## 6. バリデーションルール

### 6.1 パラメータ検証

| 条件 | エラーメッセージ |
|------|----------------|
| SqlInstanceもInputObjectも未指定 | "You must supply either -SqlInstance or an Input Object" |
| SqlInstance使用時にAvailabilityGroup未指定 | "You must specify at least one availability group when using SqlInstance." |

### 6.2 前提条件

- ターゲットインスタンスが可用性グループのセカンダリレプリカであること
- SQL Server 2012以降であること
- 適切なALTER AVAILABILITY GROUP権限があること

## 7. エラーハンドリング

| エラー条件 | 処理 |
|-----------|------|
| パラメータ不足 | Stop-Functionで処理中断、エラーメッセージ表示 |
| フェイルオーバー失敗 | Stop-Functionでエラー記録、次のAGへ処理継続 |

## 8. ConfirmImpact

- **ConfirmImpact**: High
- デフォルトで確認プロンプトが表示される
- `-Force`パラメータ使用時は`ConfirmPreference='none'`に設定され、確認をスキップ

## 9. 使用例

### 9.1 安全なフェイルオーバー

```powershell
Invoke-DbaAgFailover -SqlInstance sql2017 -AvailabilityGroup SharePoint
```

確認プロンプトが表示され、SharePoint AGをsql2017にフェイルオーバーします。

### 9.2 パイプラインでの選択フェイルオーバー

```powershell
Get-DbaAvailabilityGroup -SqlInstance sql2017 | Out-GridView -Passthru | Invoke-DbaAgFailover -Confirm:$false
```

GridViewで選択したAGをフェイルオーバーします。確認プロンプトなし。

### 9.3 強制フェイルオーバー（データ損失の可能性あり）

```powershell
Invoke-DbaAgFailover -SqlInstance sql2017 -AvailabilityGroup SharePoint -Force
```

同期を待機せずに即座にフェイルオーバーを実行します。ディザスタリカバリシナリオで使用。

### 9.4 WhatIfでの動作確認

```powershell
Invoke-DbaAgFailover -SqlInstance sql2017 -AvailabilityGroup SharePoint -WhatIf
```

実際にフェイルオーバーを実行せず、実行した場合の動作を表示します。

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

### 10.1 理解の順序

1. **パラメータ定義** (Lines 102-110) - 入力パラメータの構造
2. **beginブロック** (Lines 111-113) - Force時の確認スキップ設定
3. **processブロック** (Lines 114-148) - メイン処理フロー

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

```
Invoke-DbaAgFailover
├── Test-Bound (Line 115)
│     └── パラメータ存在チェック
├── Stop-Function (Lines 116, 121, 146)
│     └── エラー処理
├── Get-DbaAvailabilityGroup (Line 126)
│     └── AG情報取得
├── $ag.Parent (Line 131)
│     └── サーバーオブジェクト取得
├── $Pscmdlet.ShouldProcess (Lines 133, 139)
│     └── WhatIf/Confirm処理
├── $ag.FailoverWithPotentialDataLoss() (Line 134)
│     └── 強制フェイルオーバー
├── $ag.Failover() (Line 140)
│     └── 安全フェイルオーバー
└── $ag.Refresh() (Lines 135, 141)
      └── 状態更新
```

### 10.3 データフロー図

```
[ユーザー入力]
     │
     ├─ SqlInstance + AvailabilityGroup
     │        │
     │        └── Get-DbaAvailabilityGroup ──────┐
     │                                            │
     └─ InputObject (パイプライン) ───────────────┤
                                                  │
                                                  ↓
                                      [AvailabilityGroup オブジェクト]
                                                  │
                    ┌─────────────────────────────┼─────────────────────────────┐
                    │                             │                             │
                [Force=true]                 [Force=false]                [エラー発生]
                    │                             │                             │
      FailoverWithPotentialDataLoss()      Failover()              Stop-Function
                    │                             │                             │
                    └─────────────┬───────────────┘                             │
                                  │                                             │
                            Refresh()                                           │
                                  │                                             │
                    [更新されたAGオブジェクト] ←──────────────────────────────────┘
                                  │
                             [出力]
```

### 10.4 関連ファイル一覧

| ファイルパス | 役割 | 行数 |
|-------------|------|------|
| public/Invoke-DbaAgFailover.ps1 | フェイルオーバー実行 | 150 |
| public/Get-DbaAvailabilityGroup.ps1 | AG情報取得（依存） | - |

### 10.5 重要コードポイント

#### Force時の確認スキップ（Line 112）
```powershell
if ($Force) { $ConfirmPreference = 'none' }
```

#### 安全フェイルオーバー vs 強制フェイルオーバー（Lines 132-143）
```powershell
if ($Force) {
    # 強制フェイルオーバー（データ損失の可能性）
    $ag.FailoverWithPotentialDataLoss()
} else {
    # 安全フェイルオーバー
    $ag.Failover()
}
```

## 11. 権限要件

| 操作 | 必要な権限 |
|------|----------|
| Invoke-DbaAgFailover | ALTER AVAILABILITY GROUP |

## 12. 注意事項

- **データ損失リスク**: `-Force`パラメータ使用時は、同期されていないトランザクションが失われる可能性があります
- **プライマリでの実行不可**: フェイルオーバーはセカンダリレプリカをプライマリに昇格させる操作のため、ターゲットはセカンダリである必要があります
- **ConfirmImpact=High**: 重要な操作のため、デフォルトで確認プロンプトが表示されます

## 13. 関連コマンド

- Get-DbaAvailabilityGroup - 可用性グループ取得
- Get-DbaAgReplica - レプリカ情報取得
- Set-DbaAgReplica - レプリカ設定変更
- Test-DbaAvailabilityGroup - AG状態テスト
