# 機能設計書 275-Remove-DbaDbMirror

## 概要

本ドキュメントは、データベースミラーリングパートナーシップを解除し、ミラーリングセッションを停止するdbatools PowerShellコマンド`Remove-DbaDbMirror`の機能設計書です。

### 本機能の処理概要

`Remove-DbaDbMirror`は、プリンシパルとミラーデータベース間のミラーリングセッションをパートナーシップを解除することで終了します。ミラーリング関係を完全に停止し、ミラーの廃止、パートナーシップ解除が必要なメンテナンス、または独立してデータベースをオンラインにする必要がある災害復旧シナリオで使用します。

**業務上の目的・背景**：ミラーリング構成の廃止、サーバー移行、災害復旧時にミラーリングパートナーシップの解除が必要になります。本コマンドにより、手動でALTER DATABASE文を実行することなく、安全かつ一貫した方法でミラーリングを解除できます。

**機能の利用シーン**：
- ミラーリング構成の廃止・解除
- サーバー移行時のミラーリング停止
- 災害復旧時のデータベース独立化
- ミラーリング再構成前のクリーンアップ

**主要な処理内容**：
1. SqlInstanceまたはInputObjectからデータベースオブジェクト取得
2. SMOのChangeMirroringStateメソッドでミラーリングOff
3. 失敗時はALTER DATABASE SET PARTNER OFFを実行
4. 結果をPSCustomObjectで出力

**関連システム・外部連携**：SMO (SQL Server Management Objects) を使用し、ALTER DATABASE SET PARTNER OFF文を内部で実行します。

**権限による制御**：データベースのALTER権限が必要です。

## 関連画面

| 画面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 |
| EnableException | switch | No | 例外処理の有効化 | - |
| WhatIf | switch | No | 実行シミュレーション | SupportsShouldProcess |
| Confirm | switch | No | 確認プロンプト | ConfirmImpact='High' |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| Status | string | 操作結果（"Removed"） |

### 出力先

パイプライン出力（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance指定時はDatabaseが必須
2. データベースオブジェクト取得
   └─ Get-DbaDatabaseを使用
3. 各データベースに対してループ処理
   └─ ShouldProcess確認
4. SMOでミラーリング解除試行
   └─ ChangeMirroringState(Off) + Alter()
5. 失敗時はT-SQLでリトライ
   └─ IsMirroringEnabled確認後、ALTER DATABASE
6. 結果出力
   └─ PSCustomObjectで"Removed"ステータス
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定<br/>かつ<br/>Database未指定?}
    B -->|Yes| C[エラー終了]
    B -->|No| D[SqlInstanceループ]
    D --> E[Get-DbaDatabase実行]
    E --> F[データベースループ]
    F --> G{ShouldProcess確認}
    G -->|No| H[スキップ]
    G -->|Yes| I[ChangeMirroringState Off]
    I --> J[db.Alter]
    J --> K{成功?}
    K -->|Yes| L[PSCustomObject作成]
    K -->|No| M[db.Refresh]
    M --> N{IsMirroringEnabled?}
    N -->|Yes| O[ALTER DATABASE<br/>SET PARTNER OFF]
    N -->|No| L
    O --> P{成功?}
    P -->|Yes| L
    P -->|No| Q[Stop-Function]
    L --> R[オブジェクト出力]
    R --> S[次のDB]
    H --> S
    Q --> S
    S --> T{次のDB<br/>あり?}
    T -->|Yes| F
    T -->|No| U{次のインスタンス<br/>あり?}
    U -->|Yes| D
    U -->|No| V[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-275-01 | Database必須 | SqlInstance指定時はDatabaseパラメータ必須 | SqlInstance使用時 |
| BR-275-02 | SMO優先 | まずSMOのChangeMirroringStateを試行 | 常時 |
| BR-275-03 | T-SQLフォールバック | SMO失敗時はALTER DATABASEを実行 | SMO失敗時 |
| BR-275-04 | 高確認レベル | ConfirmImpact='High'で確認プロンプト表示 | Confirm未指定時 |

### 計算ロジック

ミラーリング解除の2段階処理:
```powershell
# 第1段階: SMO
$db.ChangeMirroringState([Microsoft.SqlServer.Management.Smo.MirroringOption]::Off)
$db.Alter()

# 第2段階: T-SQL（SMO失敗時）
$db.Parent.Query("ALTER DATABASE $db SET PARTNER OFF")
```

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ミラーリング解除 | Database | ALTER DATABASE | SET PARTNER OFF |

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

#### ミラーリング解除
```sql
ALTER DATABASE [dbname] SET PARTNER OFF
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | SqlInstance指定でDatabase未指定 | Stop-Function実行 |
| - | SMOエラー | ChangeMirroringState失敗 | T-SQLでリトライ |
| - | T-SQLエラー | ALTER DATABASE失敗 | Stop-Function実行 |

### リトライ仕様

- SMOメソッド失敗時に自動的にT-SQL実行でリトライ
- db.Refresh()後にIsMirroringEnabled確認

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

- ALTER DATABASE文はSQL Serverによって自動的にトランザクション管理
- ミラーリング解除後、ミラーデータベースは"Restoring"状態のまま残る

## パフォーマンス要件

- 単一のALTER DATABASE文のため即座に完了

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

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

## 備考

- ミラーリング解除後、ミラーデータベースは"Restoring"状態で残る
- データベースを使用可能にするには手動でRECOVERY復元が必要
- 重要: この関数はミラーリングパートナーシップのみを解除し、データベースの復旧は行わない

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Remove-DbaDbMirror.ps1 | `public/Remove-DbaDbMirror.ps1` | 116-122行目: PSCustomObject出力構造 |

**読解のコツ**: MirroringOptionの列挙値（Off）とIsMirroringEnabledプロパティの関係を理解することが重要です。

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

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

**主要処理フロー**:
1. **79行目**: CmdletBinding - SupportsShouldProcess, ConfirmImpact='High'
2. **80-87行目**: パラメータ定義（7個）
3. **88-92行目**: パラメータ検証
4. **93-95行目**: SqlInstanceループとGet-DbaDatabase
5. **97-127行目**: データベースループとミラーリング解除処理
6. **98行目**: ShouldProcess確認
7. **101-103行目**: SMOによるミラーリング解除試行
8. **104-115行目**: 失敗時のT-SQLフォールバック
9. **116-122行目**: 成功時のPSCustomObject出力

#### Step 3: エラーハンドリングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Remove-DbaDbMirror.ps1 | `public/Remove-DbaDbMirror.ps1` | 104-115行目: 2段階エラーハンドリング |

**エラーハンドリングのコツ**:
- **104-107行目**: db.Refresh()後にIsMirroringEnabledを確認
- **108-114行目**: ミラーリングがまだ有効な場合はT-SQL実行

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

```
Remove-DbaDbMirror
    │
    ├─ Test-Bound (パラメータ検証)
    │      └─ SqlInstance指定時はDatabase必須
    │
    ├─ foreach ($instance in $SqlInstance)
    │      └─ Get-DbaDatabase
    │             └─ Connect-DbaInstance
    │
    └─ foreach ($db in $InputObject)
           │
           ├─ ShouldProcess確認
           │
           ├─ [第1段階] SMO
           │      ├─ ChangeMirroringState(Off)
           │      └─ db.Alter()
           │
           ├─ [第2段階] T-SQL (SMO失敗時)
           │      ├─ db.Refresh()
           │      ├─ IsMirroringEnabled確認
           │      └─ ALTER DATABASE SET PARTNER OFF
           │
           └─ PSCustomObject出力
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaDatabase ──────▶ Database Objects
      +                     │
Database ──────────────────┤
      or                    ▼
InputObject ─────────▶ ShouldProcess確認
                            │
                            ▼
                    ChangeMirroringState(Off)
                            │
                    ┌───────┴───────┐
                    ▼               ▼
                [成功]          [失敗]
                    │               │
                    │               ▼
                    │       ALTER DATABASE
                    │       SET PARTNER OFF
                    │               │
                    └───────┬───────┘
                            ▼
                    PSCustomObject
                    (Status: "Removed") ──────▶ 出力
```

### 関連ファイル一覧

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