# 機能設計書 274-Invoke-DbaDbMirroring

## 概要

本ドキュメントは、SQL Serverインスタンス間でデータベースミラーリングを作成・構成するdbatools PowerShellコマンド`Invoke-DbaDbMirroring`の機能設計書です。

### 本機能の処理概要

`Invoke-DbaDbMirroring`は、SQL Serverインスタンス間でデータベースミラーリングを構成する包括的なエンドツーエンドのセットアッププロセスを処理します。通常は数十のT-SQLコマンドと慎重な検証ステップが必要な複雑な作業を自動化し、手動構成の複雑さとエラーの可能性を排除します。

**業務上の目的・背景**：データベースミラーリングの設定は複雑で、エンドポイントの作成、ログインの設定、バックアップ/リストア、パートナーシップの確立など多くのステップが必要です。本コマンドにより、DBAは高可用性ソリューションを迅速かつ確実に構成でき、設定エラーによるミラーリング失敗のリスクを軽減できます。

**機能の利用シーン**：
- 新規データベースミラーリングの構成
- 災害復旧環境の構築
- テスト環境でのミラーリング検証
- 既存ミラーリングの再構成

**主要な処理内容**：
1. ミラーリング可能性の検証（エディション、状態等）
2. リカバリモデルのFull設定
3. バックアップの作成とミラーサーバーへの復元
4. データベースミラーリングエンドポイントの設定
5. サービスアカウントへのログインとCONNECT権限付与
6. エンドポイントの起動
7. プライマリとミラー間のパートナーシップ確立
8. ウィットネスサーバーの構成（指定時）

**関連システム・外部連携**：SMO、バックアップ/リストア機能（Backup-DbaDatabase、Restore-DbaDatabase）、エンドポイント管理（New-DbaEndpoint、Start-DbaEndpoint）、ログイン管理（New-DbaLogin）など多数のdbatools関数に依存します。

**権限による制御**：sysadmin権限が推奨されます。各サーバーでのエンドポイント作成、ログイン作成、GRANT CONNECT権限が必要です。

## 関連画面

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

## 機能種別

構成操作（CREATE/ALTER/GRANT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Primary | DbaInstanceParameter | No | プライマリSQL Serverインスタンス | - |
| PrimarySqlCredential | PSCredential | No | プライマリサーバーの認証情報 | - |
| Mirror | DbaInstanceParameter[] | Yes | ミラーSQL Serverインスタンス | Mandatory |
| MirrorSqlCredential | PSCredential | No | ミラーサーバーの認証情報 | - |
| Witness | DbaInstanceParameter | No | ウィットネスSQL Serverインスタンス | - |
| WitnessSqlCredential | PSCredential | No | ウィットネスサーバーの認証情報 | - |
| Database | string[] | No | 対象データベース名 | Primary指定時は必須 |
| EndpointEncryption | string | No | エンドポイント暗号化設定 | ValidateSet: Disabled/Required/Supported |
| EncryptionAlgorithm | string | No | 暗号化アルゴリズム | ValidateSet: Aes/AesRC4/None/RC4/RC4Aes |
| SharedPath | string | No | バックアップ用共有パス | - |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | パイプライン入力データベース | ValueFromPipeline |
| UseLastBackup | switch | No | 既存バックアップを使用 | - |
| Force | switch | No | 既存ミラーDBを再作成 | - |
| EnableException | switch | No | 例外処理の有効化 | - |
| WhatIf | switch | No | 実行シミュレーション | SupportsShouldProcess |
| Confirm | switch | No | 確認プロンプト | ConfirmImpact='High' |

### 入力データソース

- プライマリ/ミラー/ウィットネスSQL Serverインスタンス
- バックアップファイル（SharedPathまたは既存バックアップ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Primary | string | プライマリサーバー名 |
| Mirror | string | ミラーサーバー名 |
| Witness | string | ウィットネスサーバー名（指定時） |
| Database | string | データベース名 |
| ServiceAccount | string[] | CONNECT権限を付与したサービスアカウント |
| Status | string | 設定結果（Success） |

### 出力先

パイプライン出力（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ Primary指定時はDatabase必須、Force時はSharedPathまたはUseLastBackup必須
2. ミラーセットアップの検証（Invoke-DbMirrorValidation）
   └─ エディションマッチ、共有パスアクセス、ミラーリング状態
3. リカバリモデルをFullに設定
   └─ UseLastBackup使用不可の場合
4. ミラーデータベースへのコピー
   └─ バックアップ作成またはUseLastBackup使用
   └─ ミラーサーバーへの復元（NoRecovery）
5. エンドポイント設定
   └─ プライマリ/ミラー/ウィットネスにエンドポイント作成
   └─ 暗号化設定適用
6. サービスアカウント権限設定
   └─ ログイン作成、GRANT CONNECT ON ENDPOINT
7. エンドポイント起動
   └─ Start-DbaEndpoint
8. パートナーシップ確立
   └─ ミラーにプライマリエンドポイントを設定
   └─ プライマリにミラーエンドポイントを設定
9. ウィットネス設定（指定時）
   └─ プライマリにウィットネスエンドポイントを設定
10. 結果出力
    └─ PSCustomObjectで成功ステータス出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{パラメータ検証}
    B -->|NG| C[エラー終了]
    B -->|OK| D[Invoke-DbMirrorValidation]
    D --> E{検証OK?}
    E -->|No| F[Stop-Function]
    E -->|Yes| G[リカバリモデル設定]
    G --> H{ミラーDB<br/>存在確認}
    H -->|新規/Force| I[バックアップ作成]
    H -->|既存| J[スキップ]
    I --> K[ミラーへ復元]
    K --> L[エンドポイント設定]
    J --> L
    L --> M[プライマリエンドポイント]
    M --> N[ミラーエンドポイント]
    N --> O{ウィットネス<br/>指定?}
    O -->|Yes| P[ウィットネスエンドポイント]
    O -->|No| Q[権限設定]
    P --> Q
    Q --> R[エンドポイント起動]
    R --> S[ミラーにパートナー設定]
    S --> T[プライマリにパートナー設定]
    T --> U{ウィットネス<br/>指定?}
    U -->|Yes| V[ウィットネス設定]
    U -->|No| W[結果出力]
    V --> W
    W --> X[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-274-01 | Database必須 | Primary指定時はDatabaseパラメータ必須 | Primary使用時 |
| BR-274-02 | Force要件 | Force使用時はSharedPathまたはUseLastBackup必須 | Force=true |
| BR-274-03 | エディションマッチ | プライマリとミラーのエディションが一致 | 常時 |
| BR-274-04 | リカバリモデル | ミラーリングにはFullリカバリモデル必須 | 常時 |
| BR-274-05 | ミラーリング状態 | 既存ミラーリング状態が"none"以外はエラー | 常時 |
| BR-274-06 | 暗号化デフォルト | EndpointEncryption='Required'、EncryptionAlgorithm='Aes' | パラメータ省略時 |

### 計算ロジック

エンドポイント暗号化設定:
```powershell
$EndpointEncryption = 'Required'  # デフォルト
$EncryptionAlgorithm = 'Aes'      # デフォルト
```

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-------------|---------|------|
| リカバリモデル変更 | Database | ALTER DATABASE | SET RECOVERY FULL |
| バックアップ作成 | Database | BACKUP DATABASE | Full + Log |
| 復元 | Mirror Database | RESTORE DATABASE | WITH NORECOVERY |
| エンドポイント作成 | Endpoint | CREATE ENDPOINT | DatabaseMirroring |
| ログイン作成 | Login | CREATE LOGIN | サービスアカウント |
| 権限付与 | Endpoint | GRANT CONNECT | ON ENDPOINT |
| パートナー設定 | Database | ALTER DATABASE | SET PARTNER |
| ウィットネス設定 | Database | ALTER DATABASE | SET WITNESS |

### 主要SQL文

#### エンドポイント権限付与
```sql
GRANT CONNECT ON ENDPOINT::Mirroring TO [ServiceAccount]
```

#### パートナー設定
```sql
ALTER DATABASE [dbname] SET PARTNER = N'TCP://server:port'
ALTER DATABASE [dbname] SET WITNESS = N'TCP://witness:port'
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | インスタンス接続失敗 | 接続情報確認 |
| - | AccessError | 共有パスアクセス不可 | 権限/パス確認 |
| - | EditionMismatch | エディション不一致 | 同一エディション使用 |
| - | MirroringState | ミラーリング状態エラー | 既存ミラーリング解除 |
| - | BackupError | バックアップ失敗 | ストレージ/権限確認 |
| - | RestoreError | 復元失敗 | ファイルパス/権限確認 |
| - | EndpointError | エンドポイント設定失敗 | ポート/権限確認 |

### リトライ仕様

リトライ処理なし。各ステップでStop-Functionによる処理停止。

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

- 各操作は個別にSQL Serverによってトランザクション管理
- 途中失敗時は手動での後始末が必要
- バックアップファイルは共有パスに残存

## パフォーマンス要件

- バックアップ/リストアはデータベースサイズに依存
- Write-ProgressHelperでステップ進捗を表示

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

- エンドポイント暗号化（デフォルトRequired/Aes）
- サービスアカウントへの最小権限付与
- PSCredentialによる安全な認証情報管理
- ConfirmImpact='High'による確認プロンプト

## 備考

- バックアップファイルは共有パスに残存する
- SQL Server 2005以降で利用可能
- ミラーリングはSQL Server 2012以降では非推奨（Always On推奨）

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造と各パラメータの関係を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDbMirroring.ps1 | `public/Invoke-DbaDbMirroring.ps1` | 413-420行目: PSCustomObject出力構造 |
| 1-2 | Invoke-DbaDbMirroring.ps1 | `public/Invoke-DbaDbMirroring.ps1` | 191-209行目: パラメータ定義 |

**読解のコツ**: この関数は多くのサブ関数を呼び出す長大な関数（430行）です。主要なステップをWrite-ProgressHelperで追跡しながら読み進めることを推奨します。

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

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

**主要処理フロー**:
1. **190行目**: CmdletBinding - SupportsShouldProcess, ConfirmImpact='High'
2. **191-209行目**: パラメータ定義（15個）
3. **211-218行目**: beginブロック - Force時の設定
4. **220-229行目**: パラメータ検証
5. **235-277行目**: ミラーセットアップ検証
6. **279-287行目**: リカバリモデル設定
7. **289-320行目**: バックアップ/リストア処理
8. **322-348行目**: エンドポイント設定
9. **350-380行目**: サービスアカウント権限設定
10. **382-387行目**: エンドポイント起動
11. **389-409行目**: パートナーシップ確立
12. **411-426行目**: 結果出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbMirrorValidation | 内部関数 | ミラーリング検証ロジック |
| 3-2 | Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | バックアップ機能 |
| 3-3 | Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | リストア機能 |
| 3-4 | New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | エンドポイント作成 |
| 3-5 | Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | パートナー設定 |

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

```
Invoke-DbaDbMirroring
    │
    ├─ begin ブロック
    │      └─ パラメータ準備
    │
    ├─ パラメータ検証
    │      ├─ Primary/Database必須チェック
    │      └─ Force/SharedPath/UseLastBackup チェック
    │
    ├─ Get-DbaDatabase (Primary→InputObject)
    │
    └─ foreach ($primarydb in $InputObject)
           │
           ├─ Connect-DbaInstance (Mirror)
           │
           ├─ Connect-DbaInstance (Witness) [オプション]
           │
           ├─ Invoke-DbMirrorValidation
           │
           ├─ Set-DbaDbRecoveryModel -RecoveryModel Full
           │
           ├─ Backup-DbaDatabase (Full + Log)
           │
           ├─ Restore-DbaDatabase -NoRecovery
           │
           ├─ Get-DbaEndpoint | New-DbaEndpoint (Primary)
           │
           ├─ Get-DbaEndpoint | New-DbaEndpoint (Mirror)
           │
           ├─ Get-DbaEndpoint | New-DbaEndpoint (Witness) [オプション]
           │
           ├─ New-DbaLogin (サービスアカウント)
           │
           ├─ GRANT CONNECT ON ENDPOINT
           │
           ├─ Start-DbaEndpoint
           │
           ├─ Set-DbaDbMirror -Partner (Mirror→Primary)
           │
           ├─ Set-DbaDbMirror -Partner (Primary→Mirror)
           │
           ├─ Set-DbaDbMirror -Witness [オプション]
           │
           └─ PSCustomObject 出力
```

### データフロー図

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

Primary ──────────▶ Get-DbaDatabase ──────▶ Database Objects
Database ────────────────┤
     or                  │
InputObject ─────────────┤
                         ▼
                 Invoke-DbMirrorValidation
                         │
                         ▼
                 Set-DbaDbRecoveryModel
                         │
                         ▼
SharedPath ────▶ Backup-DbaDatabase ──────▶ Backup Files
     or                  │
UseLastBackup ───────────┤
                         ▼
Mirror ────────▶ Restore-DbaDatabase ─────▶ Mirror Database
                         │
                         ▼
                 New-DbaEndpoint ──────────▶ Endpoints
                         │
                         ▼
                 New-DbaLogin + GRANT ─────▶ Permissions
                         │
                         ▼
                 Set-DbaDbMirror ──────────▶ Partnership
                         │
                         ▼
Witness ───────▶ Set-DbaDbMirror -Witness ─▶ Auto-Failover
                         │
                         ▼
                 PSCustomObject ───────────▶ 結果出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbMirroring.ps1 | `public/Invoke-DbaDbMirroring.ps1` | ソース | メイン機能実装（430行） |
| Invoke-DbaDbMirroring.Tests.ps1 | `tests/Invoke-DbaDbMirroring.Tests.ps1` | テスト | 単体テスト |
| Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | ソース | パートナー設定 |
| Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | ソース | バックアップ機能 |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | リストア機能 |
| New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | ソース | エンドポイント作成 |
| Start-DbaEndpoint.ps1 | `public/Start-DbaEndpoint.ps1` | ソース | エンドポイント起動 |
| Stop-DbaEndpoint.ps1 | `public/Stop-DbaEndpoint.ps1` | ソース | エンドポイント停止 |
| New-DbaLogin.ps1 | `public/New-DbaLogin.ps1` | ソース | ログイン作成 |
| Get-DbaLogin.ps1 | `public/Get-DbaLogin.ps1` | ソース | ログイン確認 |
| Set-DbaDbRecoveryModel.ps1 | `public/Set-DbaDbRecoveryModel.ps1` | ソース | リカバリモデル設定 |
