# 機能設計書 277-Repair-DbaDbMirror

## 概要

本ドキュメントは、中断されたデータベースミラーリングセッションをエンドポイントの再起動とミラーリングの再開により修復するdbatools PowerShellコマンド`Repair-DbaDbMirror`の機能設計書です。

### 本機能の処理概要

`Repair-DbaDbMirror`は、ネットワーク接続の問題、ログ領域不足、その他の一時的な障害によってミラーリングセッションが中断された場合に、ミラーリング機能を復元します。DBAが通常手動で実行するトラブルシューティング手順（SQL Serverインスタンス上のデータベースミラーリングエンドポイントの停止と再起動、その後プリンシパルとミラーデータベース間のミラーリングセッションの再開）を自動化します。

**業務上の目的・背景**：データベースミラーリングが中断されると、ミラーデータベースはプリンシパルデータベースからトランザクションログレコードの受信を停止し、潜在的なデータ損失リスクが発生します。本コマンドは一般的なリカバリプロセスを自動化し、手動でエンドポイントを再起動してALTER DATABASEコマンドを発行してミラーリングを再開する必要性を排除します。

**機能の利用シーン**：
- 中断されたミラーリングセッションの復旧
- ネットワーク障害後のミラーリング再開
- エンドポイント問題の自動修復
- ミラーリング接続のリフレッシュ

**主要な処理内容**：
1. データベースミラーリングエンドポイントの停止
2. データベースミラーリングエンドポイントの再起動
3. ミラーリングセッションの再開（Resume）
4. 修復されたデータベースオブジェクトの出力

**関連システム・外部連携**：Stop-DbaEndpoint、Start-DbaEndpoint、Set-DbaDbMirrorコマンドに依存します。

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

## 関連画面

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

## 機能種別

修復操作（STOP/START/RESUME）

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| （SMO Databaseプロパティ） | - | 修復されたデータベースオブジェクト |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance指定時はDatabaseが必須
2. データベースオブジェクト取得
   └─ Get-DbaDatabaseを使用
3. 各データベースに対してループ処理
   └─ 修復処理の実行
4. エンドポイント停止
   └─ Get-DbaEndpoint | Stop-DbaEndpoint
5. エンドポイント起動
   └─ Get-DbaEndpoint | Start-DbaEndpoint
6. ミラーリング再開
   └─ Set-DbaDbMirror -State Resume
7. 結果出力
   └─ ShouldProcessでデータベースオブジェクト出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定<br/>かつ<br/>Database未指定?}
    B -->|Yes| C[エラー終了]
    B -->|No| D[SqlInstanceループ]
    D --> E[Get-DbaDatabase実行]
    E --> F[データベースループ]
    F --> G[Get-DbaEndpoint<br/>DatabaseMirroringフィルタ]
    G --> H[Stop-DbaEndpoint]
    H --> I[Get-DbaEndpoint<br/>DatabaseMirroringフィルタ]
    I --> J[Start-DbaEndpoint]
    J --> K[Set-DbaDbMirror<br/>-State Resume]
    K --> L{ShouldProcess確認}
    L -->|Yes| M[データベースオブジェクト出力]
    L -->|No| N[スキップ]
    M --> O[次のDB]
    N --> O
    O --> P{次のDB<br/>あり?}
    P -->|Yes| F
    P -->|No| Q{次のインスタンス<br/>あり?}
    Q -->|Yes| D
    Q -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-277-01 | Database必須 | SqlInstance指定時はDatabaseパラメータ必須 | SqlInstance使用時 |
| BR-277-02 | エンドポイント再起動 | 停止→起動の順序で実行 | 常時 |
| BR-277-03 | Resume状態 | Set-DbaDbMirror -State Resumeを使用 | 常時 |
| BR-277-04 | 高確認レベル | ConfirmImpact='High'で確認プロンプト表示 | デフォルト |

### 計算ロジック

修復処理の3ステップ:
```powershell
# Step 1: エンドポイント停止
Get-DbaEndpoint -SqlInstance $db.Parent | Where-Object EndpointType -eq DatabaseMirroring | Stop-DbaEndpoint

# Step 2: エンドポイント起動
Get-DbaEndpoint -SqlInstance $db.Parent | Where-Object EndpointType -eq DatabaseMirroring | Start-DbaEndpoint

# Step 3: ミラーリング再開
$db | Set-DbaDbMirror -State Resume
```

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-------------|---------|------|
| エンドポイント停止 | Endpoint | ALTER ENDPOINT | STATE = STOPPED |
| エンドポイント起動 | Endpoint | ALTER ENDPOINT | STATE = STARTED |
| ミラーリング再開 | Database | ALTER DATABASE | SET PARTNER RESUME |

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

#### エンドポイント停止/起動
```sql
ALTER ENDPOINT [Mirroring] STATE = STOPPED
ALTER ENDPOINT [Mirroring] STATE = STARTED
```

#### ミラーリング再開
```sql
ALTER DATABASE [dbname] SET PARTNER RESUME
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | SqlInstance指定でDatabase未指定 | Stop-Function実行 |
| - | エンドポイントエラー | Stop/Start失敗 | try-catchでキャッチ |
| - | ミラーリングエラー | Resume失敗 | Stop-Function実行 |

### リトライ仕様

リトライ処理なし。エラー発生時はStop-Functionで処理停止。

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

- 各操作はSQL Serverによって個別にトランザクション管理

## パフォーマンス要件

- エンドポイント再起動は即座に完了
- ミラーリング再開後は同期状態に戻るまで時間がかかる場合がある

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

- ConfirmImpact='High'による確認プロンプト
- -WhatIfによる事前シミュレーション

## 備考

- 中断されたミラーリングセッションの修復に特化
- エンドポイントの完全な再起動が必要な場合に有効

---

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

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

### 推奨読解順序

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

入出力オブジェクトの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Repair-DbaDbMirror.ps1 | `public/Repair-DbaDbMirror.ps1` | 93-94行目: パラメータ定義と出力オブジェクト |

**読解のコツ**: この関数は3つのサブ関数（Stop-DbaEndpoint、Start-DbaEndpoint、Set-DbaDbMirror）を組み合わせた修復ワークフローです。

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

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

**主要処理フロー**:
1. **87行目**: CmdletBinding - SupportsShouldProcess, ConfirmImpact='High'
2. **88-95行目**: パラメータ定義（7個）
3. **96-100行目**: パラメータ検証
4. **101-103行目**: SqlInstanceループとGet-DbaDatabase
5. **105-116行目**: 修復処理ループ
6. **107行目**: エンドポイント停止
7. **108行目**: エンドポイント起動
8. **109行目**: ミラーリング再開
9. **110-112行目**: ShouldProcessでオブジェクト出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Stop-DbaEndpoint.ps1 | `public/Stop-DbaEndpoint.ps1` | エンドポイント停止 |
| 3-2 | Start-DbaEndpoint.ps1 | `public/Start-DbaEndpoint.ps1` | エンドポイント起動 |
| 3-3 | Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | ミラーリング再開 |

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

```
Repair-DbaDbMirror
    │
    ├─ Test-Bound (パラメータ検証)
    │      └─ SqlInstance指定時はDatabase必須
    │
    ├─ foreach ($instance in $SqlInstance)
    │      └─ Get-DbaDatabase
    │             └─ Connect-DbaInstance
    │
    └─ foreach ($db in $InputObject)
           │
           ├─ Get-DbaEndpoint (DatabaseMirroringフィルタ)
           │      └─ Stop-DbaEndpoint
           │
           ├─ Get-DbaEndpoint (DatabaseMirroringフィルタ)
           │      └─ Start-DbaEndpoint
           │
           ├─ Set-DbaDbMirror -State Resume
           │
           └─ ShouldProcess → $db 出力
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaDatabase ──────▶ Database Objects
      +                     │
Database ──────────────────┤
      or                    ▼
InputObject ─────────▶ Get-DbaEndpoint
                            │
                            ▼
                    Stop-DbaEndpoint ─────────▶ Endpoint停止
                            │
                            ▼
                    Start-DbaEndpoint ────────▶ Endpoint起動
                            │
                            ▼
                    Set-DbaDbMirror
                    -State Resume ────────────▶ ミラーリング再開
                            │
                            ▼
                    Database Object ──────────▶ 出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Repair-DbaDbMirror.ps1 | `public/Repair-DbaDbMirror.ps1` | ソース | メイン機能実装（118行） |
| Repair-DbaDbMirror.Tests.ps1 | `tests/Repair-DbaDbMirror.Tests.ps1` | テスト | 単体テスト |
| Stop-DbaEndpoint.ps1 | `public/Stop-DbaEndpoint.ps1` | ソース | エンドポイント停止 |
| Start-DbaEndpoint.ps1 | `public/Start-DbaEndpoint.ps1` | ソース | エンドポイント起動 |
| Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | ソース | ミラーリング状態変更 |
| Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | ソース | エンドポイント取得 |
