# 機能設計書 17-Invoke-DbaAgFailover

## 概要

本ドキュメントは、可用性グループの手動フェイルオーバーを実行し、対象インスタンスを新しいプライマリレプリカに昇格させるInvoke-DbaAgFailoverコマンドの機能設計書です。

### 本機能の処理概要

Invoke-DbaAgFailoverは、指定されたSQL Serverインスタンス（セカンダリレプリカ）を新しいプライマリレプリカに昇格させる手動フェイルオーバーを実行するPowerShellコマンドレットです。現在のプライマリはセカンダリに降格されます。

**業務上の目的・背景**：計画的なメンテナンス、ディザスタリカバリシナリオ、またはレプリカ間でのワークロードリバランスにおいて、可用性グループのフェイルオーバーは重要な運用操作です。このコマンドは、SSMSを使用せずにPowerShellから安全にフェイルオーバーを実行することを可能にし、自動化スクリプトやメンテナンスウィンドウでの使用に適しています。

**機能の利用シーン**：
- 計画的メンテナンスウィンドウでのプライマリ切り替え
- ディザスタリカバリシナリオでの緊急フェイルオーバー
- レプリカ間のワークロードリバランス
- データセンター移行時の計画的切り替え
- パッチ適用前後のプライマリ移動

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続
2. 対象可用性グループを取得
3. フェイルオーバータイプを判断（通常/強制）
4. SMOのFailover()またはFailoverWithPotentialDataLoss()メソッドを呼び出し
5. フェイルオーバー後のAG状態をリフレッシュして出力

**関連システム・外部連携**：
- SQL Server SMO (Server Management Objects)
- SQL Server可用性グループインフラストラクチャ
- Windows Server Failover Clustering (WSFC)

**権限による制御**：対象可用性グループに対するALTER AVAILABILITY GROUP権限、またはsysadmin固定サーバーロールのメンバーシップが必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | PowerShellコンソール/ISE | 主画面 | コマンド実行 |
| - | SSMS可用性グループダッシュボード | 参照画面 | フェイルオーバー後の状態確認 |

## 機能種別

フェイルオーバー操作 / 高可用性管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 新しいプライマリになるSQL Serverインスタンス（SQL Server 2012以上） | インスタンス接続可能性検証 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なPSCredentialオブジェクト |
| AvailabilityGroup | string[] | No | フェイルオーバー対象の可用性グループ名 | SqlInstance指定時は必須 |
| InputObject | AvailabilityGroup[] | No | パイプライン入力用AGオブジェクト | Microsoft.SqlServer.Management.Smo.AvailabilityGroup型 |
| Force | switch | No | 強制フェイルオーバー（データ損失の可能性あり） | なし |
| EnableException | switch | No | 例外を有効化 | なし |
| WhatIf | switch | No | 実行シミュレーション | なし |
| Confirm | switch | No | 実行前確認 | なし |

### 入力データソース

- PowerShellパラメータ入力
- パイプラインからのAvailabilityGroupオブジェクト（Get-DbaAvailabilityGroup出力）

## 出力仕様

### 出力データ

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

### 出力先

- PowerShellパイプライン（標準出力）
- オブジェクト型：Microsoft.SqlServer.Management.Smo.AvailabilityGroup

## 処理フロー

### 処理シーケンス

```
1. Forceパラメータ処理
   └─ -Force指定時はConfirmPreferenceを'none'に設定
2. パラメータ検証
   └─ SqlInstanceまたはInputObjectの必須チェック
3. AG名検証（SqlInstance指定時）
   └─ AvailabilityGroup必須チェック
4. AGオブジェクト取得
   └─ Get-DbaAvailabilityGroupでAGを取得
5. フェイルオーバー実行
   ├─ Force: FailoverWithPotentialDataLoss()
   └─ 通常: Failover()
6. 状態リフレッシュ
   └─ ag.Refresh()で最新状態取得
7. 結果出力
   └─ AGオブジェクトをパイプライン出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Force指定?}
    B -->|Yes| C[ConfirmPreference = none]
    B -->|No| D{SqlInstance or InputObject?}
    C --> D
    D -->|Neither| E[Stop-Function: エラー]
    D -->|OK| F{SqlInstance & !AG?}
    F -->|Yes| G[Stop-Function: AG必須エラー]
    F -->|No| H{SqlInstance指定?}
    H -->|Yes| I[Get-DbaAvailabilityGroup]
    H -->|No| J[InputObject使用]
    I --> K[AGをInputObjectに追加]
    J --> K
    K --> L[各AGをforeach]
    L --> M{Force指定?}
    M -->|Yes| N{ShouldProcess確認}
    N -->|Yes| O[FailoverWithPotentialDataLoss]
    N -->|No| L
    M -->|No| P{ShouldProcess確認}
    P -->|Yes| Q[Failover]
    P -->|No| L
    O --> R[ag.Refresh]
    Q --> R
    R --> S[AGオブジェクト出力]
    S --> L
    L -->|完了| T[終了]
    E --> T
    G --> T
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | パラメータ排他 | SqlInstanceとInputObjectの少なくとも一方が必須 | 常時 |
| BR-02 | AG名必須 | SqlInstance使用時はAvailabilityGroup必須 | SqlInstance指定時 |
| BR-03 | セーフフェイルオーバー | デフォルトは同期済みトランザクション待機 | -Forceなし時 |
| BR-04 | 強制フェイルオーバー | データ損失の可能性ありで即座にフェイルオーバー | -Force指定時 |
| BR-05 | 高影響確認 | ConfirmImpact = High（確認ダイアログ表示） | 常時 |
| BR-06 | Force時確認スキップ | -Force指定時はConfirmPreferenceを無視 | -Force指定時 |

### 計算ロジック

特になし（フェイルオーバー操作のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| フェイルオーバー | AG内部メタデータ | UPDATE | プライマリレプリカ情報更新 |
| 状態変更 | sys.dm_hadr_availability_replica_states | - | ロール状態変更 |

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

本コマンドはSMOのFailover()およびFailoverWithPotentialDataLoss()メソッドを使用します。これらはWSFCクラスターとSQL Serverの内部メタデータを更新します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | インスタンス接続失敗 | 接続情報・ネットワーク確認 |
| - | ParameterValidation | 必須パラメータ未指定 | パラメータ指定を確認 |
| - | FailoverFailed | フェイルオーバー実行失敗 | AG/レプリカ状態確認 |
| - | NotSecondary | 対象がセカンダリでない | 正しいレプリカを指定 |

### リトライ仕様

リトライ機能なし。失敗時はStop-Function -Continueでエラー出力後継続。

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

- 通常フェイルオーバー：すべてのコミット済みトランザクションが同期されるまで待機
- 強制フェイルオーバー：トランザクション同期を待たずに即座に実行

## パフォーマンス要件

- 通常フェイルオーバー：同期状態に依存（数秒〜数分）
- 強制フェイルオーバー：即座に実行（数秒）

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

- ALTER AVAILABILITY GROUP権限またはsysadmin権限が必要
- Windows認証/SQL認証/AD認証対応
- SqlCredentialによる資格情報の安全な受け渡し
- ConfirmImpact = Highによる実行前確認

## 備考

- 対象インスタンスはセカンダリレプリカである必要がある
- -Force使用時はデータ損失の可能性があるため、ディザスタリカバリ目的でのみ使用推奨
- フェイルオーバー後はクライアント接続が新しいプライマリにリダイレクトされる

---

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

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

### 推奨読解順序

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

SMOのAvailabilityGroupオブジェクトが入出力のデータ構造です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaAgFailover.ps1 | `public/Invoke-DbaAgFailover.ps1` | 出力プロパティ（.OUTPUTSセクション：52-73行目） |

**読解のコツ**: フェイルオーバーにはFailover()とFailoverWithPotentialDataLoss()の2つのメソッドがあり、-Forceパラメータで切り替わります。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaAgFailover.ps1 | `public/Invoke-DbaAgFailover.ps1` | beginブロック（111-113行目）とprocessブロック（114-149行目） |

**主要処理フロー**:
1. **111-113行目**: beginブロックでForce時のConfirmPreference設定
2. **115-123行目**: パラメータ検証
3. **125-127行目**: Get-DbaAvailabilityGroupでAGオブジェクト取得
4. **129-148行目**: foreachループでフェイルオーバー実行
5. **132-137行目**: -Force時のFailoverWithPotentialDataLoss処理
6. **138-144行目**: 通常時のFailover処理

#### Step 3: SMOメソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaAgFailover.ps1 | `public/Invoke-DbaAgFailover.ps1` | Failover()呼び出し（140行目）、FailoverWithPotentialDataLoss()呼び出し（134行目） |

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

```
Invoke-DbaAgFailover
    │
    ├─ [begin] Force時ConfirmPreference設定
    │
    ├─ Test-Bound (パラメータ検証)
    │
    ├─ Get-DbaAvailabilityGroup (SqlInstance指定時)
    │      └─ Connect-DbaInstance
    │
    ├─ ShouldProcess (確認ダイアログ)
    │
    ├─ [Force時]
    │      ├─ ag.FailoverWithPotentialDataLoss()
    │      └─ ag.Refresh()
    │
    └─ [通常時]
           ├─ ag.Failover()
           └─ ag.Refresh()
```

### データフロー図

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

SqlInstance ───▶ Get-DbaAvailabilityGroup ─┐
                                           │
InputObject ───────────────────────────────┼─▶ AGオブジェクト
                                           │
                                    ┌──────┴──────┐
                                    │             │
                             [-Force]      [通常]
                                    │             │
                     FailoverWithPotentialDataLoss  Failover
                                    │             │
                                    └──────┬──────┘
                                           │
                                      ag.Refresh()
                                           │
                                           ▼
                              AvailabilityGroup出力 ───▶ パイプライン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaAgFailover.ps1 | `public/Invoke-DbaAgFailover.ps1` | ソース | メインコマンド実装 |
| Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | ソース | AG情報取得 |
| Get-DbaAgReplica.ps1 | `public/Get-DbaAgReplica.ps1` | ソース | レプリカ状態確認（関連） |
| Sync-DbaAvailabilityGroup.ps1 | `public/Sync-DbaAvailabilityGroup.ps1` | ソース | AG同期コマンド（関連） |
