# 画面設計書 35-ミラーリング管理

## 概要

本ドキュメントは、dbatoolsにおけるデータベースミラーリング管理機能の設計仕様を定義する。

### 本画面の処理概要

データベースミラーリング管理機能は、SQL Serverのデータベースミラーリング設定の取得・設定・解除・フェイルオーバーを行うPowerShellコマンド群を提供する。ミラーリングはプリンシパルデータベースとミラーデータベース間でトランザクションログを転送し、高可用性を実現する機能である。

**業務上の目的・背景**：データベースミラーリングは、SQL Server 2005以降で利用可能な高可用性ソリューションである。プリンシパルサーバーからミラーサーバーへリアルタイムでデータを同期し、障害時の迅速なフェイルオーバーを可能にする。本機能は、ミラーリング構成の管理、状態監視、フェイルオーバー操作を自動化し、高可用性環境の運用を支援する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする。
- `Get-DbaDbMirror` - ミラーリング構成の取得
- `Set-DbaDbMirror` - ミラーリング設定の変更
- `Remove-DbaDbMirror` - ミラーリングの解除
- `Invoke-DbaDbMirrorFailover` - フェイルオーバーの実行

**主要な操作・処理内容**：
1. ミラーリング構成の取得：パートナー、ウィットネス、安全性レベル、同期状態の取得
2. ミラーリング設定の変更：パートナー、ウィットネス、安全性レベル、状態の変更
3. ミラーリングの解除：ミラーリングパートナーシップの終了
4. フェイルオーバー：プリンシパルとミラーの役割を入れ替える

**画面遷移**：本機能はCLIベースのため画面遷移は存在しないが、以下のコマンド間で連携が可能。
- `Get-DbaDatabase` から `Set-DbaDbMirror` または `Remove-DbaDbMirror` へパイプライン入力
- `Get-DbaDbMirror` による監視から `Invoke-DbaDbMirrorFailover` への操作
- Always On可用性グループへの移行前の構成確認

**権限による表示制御**：ミラーリングの設定・変更にはデータベースのALTER権限またはsysadmin固定サーバーロールのメンバーシップが必要。フェイルオーバーにはdb_owner固定データベースロールのメンバーシップまたは同等の権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 196 | Get-DbaDbMirror | 主機能 | ミラーリング構成情報の取得 |
| 197 | Set-DbaDbMirror | 主機能 | ミラーリング設定の変更 |
| 198 | Remove-DbaDbMirror | 主機能 | ミラーリングの解除 |
| 199 | Invoke-DbaDbMirrorFailover | 主機能 | フェイルオーバーの実行 |

## 画面種別

CLI（コマンドラインインターフェース）- PowerShellコマンド

## URL/ルーティング

N/A（PowerShellモジュールのコマンドとして提供）

## 入出力項目

### Get-DbaDbMirror

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 必須 | 対象SQLインスタンス |
| SqlCredential | PSCredential | - | 代替認証情報 |
| Database | string[] | - | 対象データベース名フィルター |
| EnableException | switch | - | 例外処理の有効化 |

### Set-DbaDbMirror

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | - | 代替認証情報 |
| Database | string[] | - | 対象データベース名 |
| Partner | string | - | パートナーエンドポイント（TCP://server:port） |
| Witness | string | - | ウィットネスエンドポイント（TCP://server:port） |
| SafetyLevel | string | - | 安全性レベル（Full/Off/None） |
| State | string | - | ミラーリング状態（Suspend/Resume/Failover/RemoveWitness） |
| InputObject | Database[] | - | パイプライン入力用データベースオブジェクト |
| EnableException | switch | - | 例外処理の有効化 |

### Remove-DbaDbMirror

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | - | 代替認証情報 |
| Database | string[] | - | 対象データベース名 |
| InputObject | Database[] | - | パイプライン入力用データベースオブジェクト |
| EnableException | switch | - | 例外処理の有効化 |

### Invoke-DbaDbMirrorFailover

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| SqlInstance | DbaInstanceParameter | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | - | 代替認証情報 |
| Database | string[] | - | 対象データベース名 |
| InputObject | Database[] | - | パイプライン入力用データベースオブジェクト |
| Force | switch | - | データ損失を許可した強制フェイルオーバー |
| EnableException | switch | - | 例外処理の有効化 |

## 表示項目

### Get-DbaDbMirror 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| Name | string | データベース名 |
| MirroringSafetyLevel | string | 安全性レベル（OFF/FULL/HIGH） |
| MirroringStatus | string | 同期状態（CONNECTED/DISCONNECTED/SUSPENDED/PENDING_FAILOVER） |
| MirroringPartner | string | パートナーサーバー名 |
| MirroringPartnerInstance | string | パートナーインスタンス名 |
| MirroringFailoverLogSequenceNumber | string | フェイルオーバー用LSN |
| MirroringID | Guid | ミラーリングの一意識別子 |
| MirroringRedoQueueMaxSize | int | 最大REDOキューサイズ（KB） |
| MirroringRoleSequence | int | 現在のロールシーケンス番号 |
| MirroringSafetySequence | int | 安全性レベルシーケンス番号 |
| MirroringTimeout | int | ミラーリングタイムアウト（秒） |
| MirroringWitness | string | ウィットネスサーバー名 |
| MirroringWitnessStatus | string | ウィットネス状態（CONNECTED/DISCONNECTED/UNKNOWN/SUSPENDED） |

### Set-DbaDbMirror 出力

Set-DbaDbMirrorは-State指定時のみDatabaseオブジェクトを返却する。Partner、Witness、SafetyLevel指定時は出力なし。

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| Name | string | データベース名 |
| Status | string | データベース状態 |
| RecoveryModel | string | 回復モデル |
| Owner | string | 所有者 |

### Remove-DbaDbMirror 出力

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

### Invoke-DbaDbMirrorFailover 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | データベース名 |
| Status | string | データベース状態 |
| Owner | string | 所有者 |
| RecoveryModel | string | 回復モデル |
| Size | decimal | データベースサイズ（MB） |

## イベント仕様

### 1-ミラーリング構成取得

Get-DbaDbMirrorコマンド実行時：
1. Get-DbaDatabaseでデータベース一覧を取得
2. MirroringPartnerプロパティを持つデータベースをフィルタリング
3. sys.database_mirroring_witnessesからウィットネス情報を取得
4. ウィットネスの同期状態を数値からテキストに変換（0=None, 1=Suspended, 2=Disconnected, 3=Synchronizing, 4=PendingFailover, 5=Synchronized）
5. データベースオブジェクトにウィットネス情報をNotePropertyとして追加

### 2-ミラーリング設定変更

Set-DbaDbMirrorコマンド実行時：
1. SqlInstance指定時はDatabase必須
2. Partner指定時：ALTER DATABASE SET PARTNER = N'TCP://server:port'を実行
3. Witness指定時：ALTER DATABASE SET WITNESS = N'TCP://server:port'を実行
4. SafetyLevel指定時：ALTER DATABASE SET PARTNER SAFETY {Full|Off}を実行
5. State指定時：ChangeMirroringState()メソッドを実行し、Alter()を呼び出す

### 3-ミラーリング解除

Remove-DbaDbMirrorコマンド実行時：
1. SqlInstance指定時はDatabase必須
2. ShouldProcess確認（-Confirmまたは-WhatIf対応）
3. ChangeMirroringState(Off)とAlter()を実行
4. SMO操作が失敗した場合はALTER DATABASE SET PARTNER OFFを実行
5. 成功時はStatus="Removed"を含むPSCustomObjectを返却

### 4-フェイルオーバー実行

Invoke-DbaDbMirrorFailoverコマンド実行時：
1. SqlInstance指定時はDatabase必須
2. -Force指定時：Set-DbaDbMirror -State ForceFailoverAndAllowDataLossを実行（データ損失許可）
3. -Forceなし：Set-DbaDbMirror -SafetyLevel Fullで安全性レベルを設定後、Set-DbaDbMirror -State Failoverを実行
4. フェイルオーバー後のデータベースオブジェクトを返却

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ミラーリング構成取得 | sys.databases, sys.database_mirroring_witnesses | SELECT | ミラーリング構成の参照 |
| ミラーリング設定変更 | sys.database_mirroring | UPDATE | パートナー/ウィットネス/安全性レベルの変更 |
| ミラーリング解除 | sys.database_mirroring | UPDATE | ミラーリングの無効化 |
| フェイルオーバー | sys.database_mirroring | UPDATE | 役割の入れ替え |

### ALTER DATABASE文詳細

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

#### ウィットネス設定
```sql
ALTER DATABASE [DatabaseName] SET WITNESS = N'TCP://server:port'
```

#### 安全性レベル設定
```sql
ALTER DATABASE [DatabaseName] SET PARTNER SAFETY FULL
-- または
ALTER DATABASE [DatabaseName] SET PARTNER SAFETY OFF
```

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| MSG001 | エラー | Database is required when SqlInstance is specified | SqlInstance指定時にDatabase未指定 |
| MSG002 | 確認 | Setting partner on {database} | パートナー設定確認 |
| MSG003 | 確認 | Setting witness on {database} | ウィットネス設定確認 |
| MSG004 | 確認 | Changing safety level to {level} on {database} | 安全性レベル変更確認 |
| MSG005 | 確認 | Changing mirror state to {state} on {database} | ミラーリング状態変更確認 |
| MSG006 | 確認 | Turning off mirror for {database} | ミラーリング解除確認 |
| MSG007 | エラー | Failure on {instance} for {database} | ミラーリング解除失敗 |
| MSG008 | 確認 | Forcing failover of {database} and allowing data loss | 強制フェイルオーバー確認 |
| MSG009 | 確認 | Setting safety level to full and failing over {database} to partner server | 通常フェイルオーバー確認 |
| MSG010 | 成功 | Removed | ミラーリング解除成功 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SqlInstance指定時にDatabase未指定 | Stop-Functionでエラー出力して終了 |
| ウィットネス情報取得失敗 | 例外をキャッチして続行（ウィットネス情報なしで出力） |
| パートナー設定失敗 | Stop-Functionでエラー出力 |
| ウィットネス設定失敗 | Stop-Functionでエラー出力 |
| 安全性レベル変更失敗 | Stop-Functionでエラー出力 |
| 状態変更失敗 | Stop-Functionでエラー出力 |
| SMOによるミラーリング解除失敗 | ALTER DATABASE SET PARTNER OFFを試行 |
| ALTERコマンド失敗 | Stop-Functionでエラー出力して続行 |

## 備考

- データベースミラーリングはSQL Server 2005以降でサポート（SQL Server 2016以降では非推奨、Always On可用性グループへの移行推奨）
- 同期ミラーリング（FULL）はトランザクションの完全な同期を保証するが、パフォーマンスに影響
- 非同期ミラーリング（OFF）はパフォーマンス重視だが、フェイルオーバー時にデータ損失の可能性
- ウィットネスサーバーは自動フェイルオーバーに必要（同期ミラーリングのみ）
- ミラーリング解除後、ミラーデータベースは「復元中」状態のままとなり、手動でのRECOVERYが必要
- -Forceを使用したフェイルオーバーはデータ損失を許容する緊急時の操作

---

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

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

### 推奨読解順序

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

ミラーリング管理で扱う主要なデータ構造はSMOのDatabaseオブジェクトのミラーリング関連プロパティである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbMirror.ps1 | `public/Get-DbaDbMirror.ps1` | 出力プロパティ一覧（行56-78）を確認 |

**読解のコツ**: MirroringPartnerプロパティがミラーリングデータベースを識別する重要なプロパティ。sys.database_mirroring_witnessesビューからウィットネス情報を追加取得する。

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

各コマンドのprocess{}ブロックが処理の起点となる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbMirror.ps1 | `public/Get-DbaDbMirror.ps1` | 行88-117のprocessブロック |
| 2-2 | Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | 行119-158のprocessブロック |
| 2-3 | Remove-DbaDbMirror.ps1 | `public/Remove-DbaDbMirror.ps1` | 行88-128のprocessブロック |
| 2-4 | Invoke-DbaDbMirrorFailover.ps1 | `public/Invoke-DbaDbMirrorFailover.ps1` | 行93-115のprocessブロック |

**主要処理フロー（Get-DbaDbMirror）**:
1. **行90**: Get-DbaDatabaseでデータベース取得
2. **行91**: MirroringPartnerでフィルタリング
3. **行96**: sys.database_mirroring_witnessesからウィットネス情報取得
4. **行99-115**: ウィットネス情報をデータベースオブジェクトに追加

#### Step 3: ミラーリング設定変更処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | パートナー設定（行130-134） |
| 3-2 | Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | ウィットネス設定（行135-139） |
| 3-3 | Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | 安全性レベル設定（行141-146） |
| 3-4 | Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | 状態変更（行148-154） |

**主要処理フロー（Set-DbaDbMirror）**:
- **行133**: ALTER DATABASE SET PARTNER = でパートナー設定
- **行137**: ALTER DATABASE SET WITNESS = でウィットネス設定
- **行143**: ALTER DATABASE SET PARTNER SAFETY で安全性レベル設定
- **行150-152**: ChangeMirroringState()とAlter()で状態変更

#### Step 4: フェイルオーバー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Invoke-DbaDbMirrorFailover.ps1 | `public/Invoke-DbaDbMirrorFailover.ps1` | 強制フェイルオーバー（行105-108） |
| 4-2 | Invoke-DbaDbMirrorFailover.ps1 | `public/Invoke-DbaDbMirrorFailover.ps1` | 通常フェイルオーバー（行109-114） |

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

```
Get-DbaDbMirror
    |
    +-- Get-DbaDatabase
    |
    +-- Database.Query() (sys.database_mirroring_witnesses)
    |
    +-- Select-DefaultView (出力整形)

Set-DbaDbMirror
    |
    +-- Get-DbaDatabase
    |
    +-- Server.Query() (ALTER DATABASE SET PARTNER/WITNESS/SAFETY)
    |
    +-- Database.ChangeMirroringState() (状態変更)
    |
    +-- Database.Alter()

Remove-DbaDbMirror
    |
    +-- Get-DbaDatabase
    |
    +-- Database.ChangeMirroringState(Off)
    |
    +-- Database.Alter()
    |
    +-- Server.Query() (ALTER DATABASE SET PARTNER OFF - フォールバック)

Invoke-DbaDbMirrorFailover
    |
    +-- Get-DbaDatabase
    |
    +-- Set-DbaDbMirror -State ForceFailoverAndAllowDataLoss (-Force時)
    |
    +-- Set-DbaDbMirror -SafetyLevel Full (通常時)
    |
    +-- Set-DbaDbMirror -State Failover (通常時)
```

### データフロー図

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

SqlInstance    ----->  Connect-DbaInstance
                            |
Database       ----->  フィルタリング           ----->  ミラーリング対象DB
                            |
                     Get-DbaDatabase
                            |
                     ミラーリングプロパティ取得
                            |
                     sys.database_mirroring_witnesses -----> ウィットネス情報
                            |
                     Select-DefaultView          ----->  Database (ミラーリング情報付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbMirror.ps1 | `public/Get-DbaDbMirror.ps1` | ソース | ミラーリング構成取得コマンド |
| Set-DbaDbMirror.ps1 | `public/Set-DbaDbMirror.ps1` | ソース | ミラーリング設定変更コマンド |
| Remove-DbaDbMirror.ps1 | `public/Remove-DbaDbMirror.ps1` | ソース | ミラーリング解除コマンド |
| Invoke-DbaDbMirrorFailover.ps1 | `public/Invoke-DbaDbMirrorFailover.ps1` | ソース | フェイルオーバー実行コマンド |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得（依存コマンド） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続（依存コマンド） |
