# 機能設計書 271-Get-DbaDbMirror

## 概要

本ドキュメントは、SQL Serverデータベースミラーリングの構成と状態を取得するdbatools PowerShellコマンド`Get-DbaDbMirror`の機能設計書です。

### 本機能の処理概要

`Get-DbaDbMirror`は、SQL Serverインスタンス上で構成されているデータベースミラーリングの詳細情報を収集し、パートナーサーバー、ウィットネスサーバー、安全性レベル、同期状態などの包括的なミラーリングトポロジ情報を提供します。

**業務上の目的・背景**：データベースミラーリングは高可用性ソリューションの一つであり、DBAはミラーリング構成の監査、トラブルシューティング、構成確認を頻繁に行う必要があります。SSMSで各データベースのミラーリングプロパティを個別に確認する代わりに、本コマンドを使用することで複数インスタンスのミラーリング状態を効率的に一括確認できます。

**機能の利用シーン**：
- ミラーリング構成の監査・文書化
- ミラーリングセッションの健全性確認
- 障害発生時のトラブルシューティング
- 複数インスタンス間のミラーリング状態の一括確認

**主要な処理内容**：
1. Get-DbaDatabaseを使用してデータベース情報を取得
2. MirroringPartnerプロパティを持つデータベースをフィルタリング
3. sys.database_mirroring_witnessesシステムビューからウィットネス情報を取得
4. ミラーリング構成プロパティを整形して出力

**関連システム・外部連携**：SMO (SQL Server Management Objects) を使用してSQL Serverに接続し、データベースオブジェクトのプロパティとシステムビューからデータを取得します。

**権限による制御**：SQL Serverへの接続権限とデータベースメタデータの参照権限が必要です。sys.database_mirroring_witnessesビューの参照にはサーバーレベルの権限が必要な場合があります。

## 関連画面

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

## 機能種別

データ取得（SELECT操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可能 |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証対応 |
| Database | string[] | No | 対象データベース名 | ワイルドカード対応 |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SQL Serverインスタンスへの接続情報
- SMOを通じたデータベースオブジェクト
- sys.database_mirroring_witnessesシステムビュー

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Name | string | データベース名 |
| MirroringSafetyLevel | string | 安全性レベル（OFF/FULL/HIGH） |
| MirroringStatus | string | ミラーリング状態 |
| MirroringPartner | string | パートナーサーバー名 |
| MirroringPartnerInstance | string | パートナーインスタンス名 |
| MirroringFailoverLogSequenceNumber | int | フェイルオーバーLSN |
| MirroringID | Guid | ミラーリングID |
| MirroringRedoQueueMaxSize | int | REDOキュー最大サイズ（KB） |
| MirroringRoleSequence | int | ロールシーケンス番号 |
| MirroringSafetySequence | int | 安全性シーケンス番号 |
| MirroringTimeout | int | タイムアウト（秒） |
| MirroringWitness | string | ウィットネスサーバー名 |
| MirroringWitnessStatus | string | ウィットネス接続状態 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. SqlInstanceパラメータのループ処理
   └─ 各インスタンスに対して処理を実行
2. Get-DbaDatabaseでデータベース情報取得
   └─ SqlCredentialとDatabaseフィルタを適用
3. MirroringPartnerを持つデータベースをフィルタリング
   └─ ミラーリング構成されたデータベースのみ抽出
4. Select-DefaultViewでプロパティを選択して出力
   └─ 16個のミラーリング関連プロパティを表示
5. sys.database_mirroring_witnessesからウィットネス情報を取得
   └─ SQLクエリでウィットネステーブルを参照
6. ウィットネス情報をデータベースオブジェクトに追加
   └─ Add-Memberでプロパティを動的に追加
7. 拡張されたオブジェクトを出力
   └─ ウィットネス情報を含むオブジェクトを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SqlInstanceループ]
    B --> C[Get-DbaDatabase実行]
    C --> D{MirroringPartner<br/>あり?}
    D -->|Yes| E[Select-DefaultViewで出力]
    D -->|No| F[スキップ]
    E --> G[sys.database_mirroring_witnesses<br/>クエリ実行]
    G --> H{ウィットネス<br/>情報あり?}
    H -->|Yes| I[Add-Memberでプロパティ追加]
    H -->|No| J[次のインスタンス]
    I --> K[拡張オブジェクト出力]
    K --> J
    F --> J
    J --> L{次のインスタンス<br/>あり?}
    L -->|Yes| B
    L -->|No| M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-271-01 | ミラーリングフィルタ | MirroringPartnerプロパティを持つデータベースのみ返却 | 常時 |
| BR-271-02 | ウィットネス状態変換 | partner_sync_stateを文字列に変換（0:None, 1:Suspended等） | ウィットネス情報取得時 |

### 計算ロジック

ウィットネス同期状態の変換:
- 0 → "None"
- 1 → "Suspended"
- 2 → "Disconnected"
- 3 → "Synchronizing"
- 4 → "PendingFailover"
- 5 → "Synchronized"

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ウィットネス情報取得 | master.sys.database_mirroring_witnesses | SELECT | ウィットネス構成情報の取得 |

### テーブル別操作詳細

#### sys.database_mirroring_witnesses

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | database_name | - | ミラーリング対象データベース名 |
| SELECT | principal_server_name | - | プリンシパルサーバー名 |
| SELECT | safety_level | - | 安全性レベル数値 |
| SELECT | safety_level_desc | - | 安全性レベル説明 |
| SELECT | partner_sync_state | - | パートナー同期状態 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverへの接続失敗 | 接続情報・ネットワークを確認 |
| - | QueryError | ウィットネスクエリ失敗 | try-catchでcontinue |

### リトライ仕様

リトライ処理なし。エラー発生時は次のインスタンスの処理を継続。

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

読み取り専用操作のためトランザクション不要。

## パフォーマンス要件

- SMOオブジェクトのキャッシュを活用
- パイプライン処理による即座のオブジェクト出力

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

- PSCredentialによる安全な認証情報管理
- Windows認証、SQL認証、AD認証をサポート
- MFA対応はConnect-DbaInstanceを使用

## 備考

- SQL Server 2005以降で利用可能
- ミラーリングはSQL Server 2012以降では非推奨（Always On可用性グループを推奨）

---

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

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

### 推奨読解順序

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

まず、ミラーリング関連のSMOプロパティ構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbMirror.ps1 | `public/Get-DbaDbMirror.ps1` | 92行目: Select-DefaultViewで選択されるプロパティ一覧を確認 |

**読解のコツ**: Microsoft.SqlServer.Management.Smo.Databaseクラスには、Mirroring*プレフィックスを持つ多数のプロパティがあります。これらはSMOによって自動的に取得されます。

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

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

**主要処理フロー**:
1. **81-87行目**: パラメータ定義（SqlInstance, SqlCredential, Database, EnableException）
2. **88行目**: process ブロック開始
3. **89-92行目**: インスタンスループとGet-DbaDatabase呼び出し
4. **90行目**: Get-DbaDatabaseでデータベース取得
5. **91行目**: MirroringPartnerでフィルタリング
6. **92行目**: Select-DefaultViewで出力
7. **94-97行目**: ウィットネス情報のSQLクエリ実行
8. **99-115行目**: ウィットネス情報のプロパティ追加処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | データベースオブジェクト取得の基盤 |
| 3-2 | Select-DefaultView | 内部関数 | 出力プロパティの選択 |

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

```
Get-DbaDbMirror
    │
    ├─ Get-DbaDatabase
    │      └─ Connect-DbaInstance
    │             └─ SMO Server オブジェクト
    │
    ├─ Where-Object (MirroringPartnerフィルタ)
    │
    ├─ Select-DefaultView (プロパティ選択)
    │
    ├─ $dbs[0].Parent.Query() (ウィットネスクエリ)
    │      └─ sys.database_mirroring_witnesses
    │
    └─ Add-Member (プロパティ動的追加)
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaDatabase ──────▶ Database Objects
                            │
                            ▼
                    MirroringPartnerフィルタ
                            │
                            ▼
                    Select-DefaultView ──────▶ ミラーリングプロパティ
                            │
                            ▼
                    sys.database_mirroring_witnesses
                            │
                            ▼
                    Add-Member ──────────────▶ 拡張済みDatabase Objects
```

### 関連ファイル一覧

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