# 機能設計書 273-Invoke-DbaDbMirrorFailover

## 概要

本ドキュメントは、データベースミラーリングのフェイルオーバーを実行するdbatools PowerShellコマンド`Invoke-DbaDbMirrorFailover`の機能設計書です。

### 本機能の処理概要

`Invoke-DbaDbMirrorFailover`は、プライマリサーバーとミラーサーバー間でデータベースミラーリングのフェイルオーバーを実行し、ロールを切り替えます。同期ミラーリングの場合は安全レベルをFullに設定してデータ損失なしのクリーンフェイルオーバーを実行し、非同期ミラーリングや緊急時には-Forceを使用してデータ損失を許容した強制フェイルオーバーを実行できます。

**業務上の目的・背景**：計画メンテナンス、災害復旧シナリオ、高可用性構成のテストにおいて、データベースミラーリングのフェイルオーバーは必須の操作です。本コマンドにより、複雑なALTER DATABASE文を手動で実行することなく、安全かつ一貫したフェイルオーバー操作が可能になります。

**機能の利用シーン**：
- 計画メンテナンス時のロール切り替え
- 災害復旧時の緊急フェイルオーバー
- 高可用性構成のフェイルオーバーテスト
- プライマリサーバーの更新・パッチ適用前の切り替え

**主要な処理内容**：
1. SqlInstanceまたはInputObjectからデータベースオブジェクト取得
2. 同期/非同期モードの判定
3. Set-DbaDbMirrorを使用してフェイルオーバー実行
4. 結果のデータベースオブジェクト出力

**関連システム・外部連携**：Set-DbaDbMirrorコマンドに依存し、SQL ServerのALTER DATABASE SET PARTNER FAILOVER文を内部で実行します。

**権限による制御**：データベースのALTER権限とミラーリングエンドポイントへのCONNECT権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンド実行・結果表示 |

## 機能種別

状態変更操作（ALTER DATABASE）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証対応 |
| Database | string[] | No | 対象データベース名 | SqlInstance指定時は必須 |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | パイプライン入力データベース | ValueFromPipeline |
| Force | switch | No | 強制フェイルオーバー（データ損失許容） | - |
| EnableException | switch | No | 例外処理の有効化 | - |
| WhatIf | switch | No | 実行シミュレーション | SupportsShouldProcess |
| Confirm | switch | No | 確認プロンプト | ConfirmImpact='High' |

### 入力データソース

- SQL Serverインスタンスへの接続情報
- Get-DbaDatabaseからのデータベースオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 出力なし | - | Set-DbaDbMirrorからの出力（Database オブジェクト） |

### 出力先

パイプライン出力（Microsoft.SqlServer.Management.Smo.Database オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. Forceパラメータ確認
   └─ Force指定時はConfirmPreferenceを'none'に設定
2. パラメータ検証
   └─ SqlInstance指定時はDatabaseが必須
3. データベースオブジェクト取得
   └─ Get-DbaDatabaseを使用
4. 各データベースに対してループ処理
   └─ フェイルオーバーモードの判定と実行
5. フェイルオーバー実行
   └─ Force: ForceFailoverAndAllowDataLoss
   └─ 通常: SafetyLevel=Full → Failover
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Force指定?}
    B -->|Yes| C[ConfirmPreference='none']
    B -->|No| D[通常処理]
    C --> D
    D --> E{SqlInstance指定<br/>かつ<br/>Database未指定?}
    E -->|Yes| F[エラー終了]
    E -->|No| G[Get-DbaDatabase実行]
    G --> H[データベースループ]
    H --> I{Force指定?}
    I -->|Yes| J{ShouldProcess確認}
    I -->|No| K{ShouldProcess確認}
    J -->|Yes| L[Set-DbaDbMirror<br/>-State ForceFailoverAndAllowDataLoss]
    J -->|No| M[スキップ]
    K -->|Yes| N[Set-DbaDbMirror<br/>-SafetyLevel Full]
    K -->|No| M
    N --> O[Set-DbaDbMirror<br/>-State Failover]
    L --> P[次のDB]
    O --> P
    M --> P
    P --> Q{次のDB<br/>あり?}
    Q -->|Yes| H
    Q -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-273-01 | Database必須 | SqlInstance指定時はDatabaseパラメータ必須 | SqlInstance使用時 |
| BR-273-02 | 同期フェイルオーバー | Force未指定時は安全レベルをFullに設定後フェイルオーバー | Force=false |
| BR-273-03 | 強制フェイルオーバー | Force指定時はデータ損失を許容して即座にフェイルオーバー | Force=true |
| BR-273-04 | 高確認レベル | ConfirmImpact='High'で確認プロンプト表示 | Confirm未指定時 |

### 計算ロジック

フェイルオーバーモードの決定:
```powershell
if ($Force) {
    # 強制フェイルオーバー（データ損失許容）
    $db | Set-DbaDbMirror -State ForceFailoverAndAllowDataLoss
} else {
    # 安全なフェイルオーバー
    $db | Set-DbaDbMirror -SafetyLevel Full
    $db | Set-DbaDbMirror -State Failover
}
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 安全レベル設定 | - | ALTER DATABASE | PARTNER SAFETY FULL |
| フェイルオーバー | - | ALTER DATABASE | PARTNER FAILOVER |
| 強制フェイルオーバー | - | ALTER DATABASE | PARTNER FORCE_SERVICE_ALLOW_DATA_LOSS |

### SQL文（内部で実行）

#### 通常フェイルオーバー
```sql
ALTER DATABASE [dbname] SET PARTNER SAFETY FULL
ALTER DATABASE [dbname] SET PARTNER FAILOVER
```

#### 強制フェイルオーバー
```sql
ALTER DATABASE [dbname] SET PARTNER FORCE_SERVICE_ALLOW_DATA_LOSS
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | SqlInstance指定でDatabase未指定 | Stop-Function実行 |
| - | ミラーリングエラー | フェイルオーバー失敗 | Set-DbaDbMirror内でハンドリング |

### リトライ仕様

リトライ処理なし。フェイルオーバーは一回性の操作。

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

- ALTER DATABASE文はSQL Serverによって自動的にトランザクション管理
- 強制フェイルオーバー時はデータ損失の可能性あり

## パフォーマンス要件

- 同期フェイルオーバーは未送信トランザクションの完了を待機
- 強制フェイルオーバーは即座に実行

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

- ConfirmImpact='High'による確認プロンプト
- -Forceパラメータによるデータ損失リスクの明示
- -WhatIfによる事前シミュレーション

## 備考

- 非同期ミラーリングでは-Forceが必要
- ミラーリングは SQL Server 2012以降では非推奨

---

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

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

### 推奨読解順序

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

フェイルオーバー状態の列挙値を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDbMirrorFailover.ps1 | `public/Invoke-DbaDbMirrorFailover.ps1` | 102-114行目: フェイルオーバーロジックの分岐 |

**読解のコツ**: Force指定の有無で処理が完全に分岐します。同期/非同期ミラーリングの違いを理解することが重要です。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbMirrorFailover.ps1 | `public/Invoke-DbaDbMirrorFailover.ps1` | 関数全体の構造（117行） |

**主要処理フロー**:
1. **80行目**: CmdletBinding - SupportsShouldProcess, ConfirmImpact='High'
2. **81-89行目**: パラメータ定義
3. **90-92行目**: beginブロック - Force時のConfirmPreference設定
4. **93-97行目**: パラメータ検証
5. **99行目**: Get-DbaDatabaseでデータベース取得
6. **101-115行目**: フェイルオーバー実行ロジック
7. **105-108行目**: Force時の強制フェイルオーバー
8. **109-113行目**: 通常のフェイルオーバー（SafetyLevel Full → Failover）

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | フェイルオーバーの実際の実装 |

**主要処理**:
- **148-154行目**: Stateパラメータ処理（Failover, ForceFailoverAndAllowDataLoss等）

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

```
Invoke-DbaDbMirrorFailover
    │
    ├─ begin ブロック
    │      └─ Force時: ConfirmPreference = 'none'
    │
    ├─ Test-Bound (パラメータ検証)
    │      └─ SqlInstance指定時はDatabase必須
    │
    ├─ Get-DbaDatabase
    │      └─ Connect-DbaInstance
    │
    └─ foreach ($db in $InputObject)
           │
           ├─ [Force=true] Set-DbaDbMirror -State ForceFailoverAndAllowDataLoss
           │
           └─ [Force=false]
                  ├─ Set-DbaDbMirror -SafetyLevel Full
                  └─ Set-DbaDbMirror -State Failover
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaDatabase ──────▶ Database Objects
      +                     │
Database ──────────────────┤
      or                    ▼
InputObject ─────────▶ Force判定
                            │
               ┌────────────┴────────────┐
               ▼                         ▼
        [Force=true]              [Force=false]
               │                         │
               ▼                         ▼
    ForceFailoverAndAllowDataLoss   SafetyLevel Full
                                         │
                                         ▼
                                      Failover
               │                         │
               └────────────┬────────────┘
                            ▼
                    Database Object ─────▶ 出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbMirrorFailover.ps1 | `public/Invoke-DbaDbMirrorFailover.ps1` | ソース | メイン機能実装 |
| Invoke-DbaDbMirrorFailover.Tests.ps1 | `tests/Invoke-DbaDbMirrorFailover.Tests.ps1` | テスト | 単体テスト |
| Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | ソース | 依存関数（実際のフェイルオーバー実行） |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | 依存関数 |
