# 機能設計書 12-Get-DbaAgDatabaseReplicaState

## 概要

本ドキュメントは、SQL Server可用性グループに参加しているデータベースの全レプリカにわたるランタイム状態情報を取得するGet-DbaAgDatabaseReplicaStateコマンドの機能設計書です。

### 本機能の処理概要

Get-DbaAgDatabaseReplicaStateは、SQL Server可用性グループのデータベースに関する包括的なヘルスモニタリング情報を取得するPowerShellコマンドレットです。SSMS AG Dashboardと同様の詳細なデータベースレプリカ状態情報を、可用性グループ内のすべてのレプリカについて返します。

**業務上の目的・背景**：可用性グループ環境では、各レプリカ上でのデータベースの状態を監視することが重要です。データ損失リスクの評価、同期遅延の検出、フェイルオーバー準備状況の確認など、運用上の意思決定に必要な詳細情報を提供します。SSMSのAG Dashboardで確認できる情報をPowerShellから取得可能にすることで、自動化やレポート生成を容易にします。

**機能の利用シーン**：
- 可用性グループ全体のヘルスモニタリング
- 同期問題の詳細なトラブルシューティング
- データ損失リスクの評価（EstimatedDataLoss）
- レプリカ間のログ送信・再実行キューの監視
- コンプライアンスレポートの生成
- フェイルオーバー前の準備状況確認

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続し、可用性グループを取得
2. 各可用性グループ内のレプリカを走査
3. 各レプリカのDatabaseReplicaStatesコレクションを取得
4. データベースごとにレプリカ状態情報を収集
5. 詳細な同期・パフォーマンス情報を含むカスタムオブジェクトを出力

**関連システム・外部連携**：
- SQL Server SMO (Server Management Objects)
- SQL Server可用性グループインフラストラクチャ
- Windows Server Failover Clustering (WSFC)
- DMV: sys.dm_hadr_database_replica_states

**権限による制御**：VIEW SERVER STATE権限またはsysadmin固定サーバーロールのメンバーシップが必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | PowerShellコンソール/ISE | 主画面 | コマンド実行とパイプライン処理 |
| - | SSMS AG Dashboard | 参照画面 | 同等機能の視覚的表示 |

## 機能種別

SELECT（データ取得）/ 監視・レポート出力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス（SQL Server 2012以上） | インスタンス接続可能性検証 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なPSCredentialオブジェクト |
| AvailabilityGroup | string[] | No | 取得対象の可用性グループ名 | なし（存在しない場合は結果なし） |
| Database | string[] | No | 取得対象のデータベース名 | なし（存在しない場合は結果なし） |
| InputObject | AvailabilityGroup[] | No | パイプライン入力用AGオブジェクト | Microsoft.SqlServer.Management.Smo.AvailabilityGroup型 |
| EnableException | switch | No | 例外を有効化（詳細エラー表示） | なし |

### 入力データソース

- PowerShellパラメータ入力
- パイプラインからのAvailabilityGroupオブジェクト（Get-DbaAvailabilityGroup出力）
- SQL Server SMO経由のDatabaseReplicaStateメタデータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| AvailabilityGroup | string | 可用性グループ名 |
| PrimaryReplica | string | プライマリレプリカのサーバー名 |
| ReplicaServerName | string | 当該レプリカのサーバー名 |
| ReplicaRole | enum | レプリカのロール（Primary/Secondary） |
| ReplicaAvailabilityMode | enum | 可用性モード（Asynchronous/Synchronous） |
| ReplicaFailoverMode | enum | フェイルオーバーモード（Automatic/Manual） |
| ReplicaConnectionState | enum | 接続状態（Connected/Disconnected/Failed） |
| ReplicaJoinState | enum | 参加状態（Joined/NotJoined） |
| ReplicaSynchronizationState | enum | ロールアップ同期状態 |
| DatabaseName | string | データベース名 |
| SynchronizationState | enum | 同期状態 |
| IsFailoverReady | bool | フェイルオーバー準備完了フラグ |
| IsJoined | bool | AGに参加済みフラグ |
| IsSuspended | bool | データ移動中断フラグ |
| SuspendReason | enum | 中断理由 |
| EstimatedRecoveryTime | TimeSpan | 推定リカバリ時間 |
| EstimatedDataLoss | TimeSpan | 推定データ損失時間 |
| SynchronizationPerformance | enum | 同期パフォーマンスレベル |
| LogSendQueueSize | long | ログ送信キューサイズ（KB） |
| LogSendRate | long | ログ送信レート（KB/秒） |
| RedoQueueSize | long | 再実行キューサイズ（KB） |
| RedoRate | long | 再実行レート（KB/秒） |
| FileStreamSendRate | long | FILESTREAM送信レート（KB/秒） |
| EndOfLogLSN | string | ログ終端LSN |
| RecoveryLSN | string | リカバリLSN |
| TruncationLSN | string | 切り捨てLSN |
| LastCommitLSN | string | 最終コミットLSN |
| LastCommitTime | DateTime | 最終コミット日時 |
| LastHardenedLSN | string | 最終ハードニングLSN |
| LastHardenedTime | DateTime | 最終ハードニング日時 |
| LastReceivedLSN | string | 最終受信LSN |
| LastReceivedTime | DateTime | 最終受信日時 |
| LastRedoneLSN | string | 最終再実行LSN |
| LastRedoneTime | DateTime | 最終再実行日時 |
| LastSentLSN | string | 最終送信LSN |
| LastSentTime | DateTime | 最終送信日時 |

### 出力先

- PowerShellパイプライン（標準出力）
- オブジェクト型：PSCustomObject

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstanceまたはInputObjectの少なくとも一方が必須
2. インスタンス接続（SqlInstance指定時）
   └─ Get-DbaAvailabilityGroupを呼び出してAGオブジェクト取得
3. 可用性グループ走査
   └─ InputObjectの各AGをforeachで処理
4. レプリカ走査
   └─ AG.AvailabilityReplicasの各レプリカを処理
5. データベースレプリカ状態取得
   └─ レプリカID別にDatabaseReplicaStatesをフィルタ
6. データベース走査
   └─ AvailabilityDatabasesを走査し、Databaseフィルタ適用
7. 状態オブジェクト生成
   └─ 詳細情報を含むPSCustomObjectを生成して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance or InputObject?}
    B -->|Neither| C[Stop-Function: エラー]
    B -->|SqlInstance| D[Get-DbaAvailabilityGroup呼び出し]
    B -->|InputObject| E[パイプライン入力使用]
    D --> F[InputObjectにAG追加]
    E --> F
    F --> G[各AGをforeach]
    G --> H[各Replicaをforeach]
    H --> I[ReplicaIDでDatabaseReplicaStatesフィルタ]
    I --> J[各AvailabilityDatabaseをforeach]
    J --> K{Databaseフィルタ?}
    K -->|Yes| L{名前マッチ?}
    L -->|No| J
    L -->|Yes| M[DatabaseReplicaState取得]
    K -->|No| M
    M --> N{State存在?}
    N -->|No| J
    N -->|Yes| O[PSCustomObject生成・出力]
    O --> J
    J -->|完了| H
    H -->|完了| G
    G -->|完了| P[終了]
    C --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | パラメータ排他 | SqlInstanceとInputObjectの少なくとも一方が必須 | 常時 |
| BR-02 | バージョン制限 | SQL Server 2012以上が必要 | 接続時 |
| BR-03 | SMOタイポ対応 | AvailabilityDateabaseIdのタイポを使用 | DatabaseReplicaState取得時 |
| BR-04 | 状態なしスキップ | DatabaseReplicaStateがnullの場合はスキップ | 状態取得時 |

### 計算ロジック

特になし（データ取得機能のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| レプリカ状態取得 | sys.dm_hadr_database_replica_states | SELECT | SMO経由でのデータベースレプリカ状態取得 |
| AG情報取得 | sys.availability_groups | SELECT | 可用性グループ情報取得 |
| レプリカ情報取得 | sys.availability_replicas | SELECT | レプリカ設定情報取得 |

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

本コマンドはSMOを使用するため、直接T-SQLを発行しません。SMOがDMVやシステムビューにアクセスします。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | インスタンス接続失敗 | 接続情報・ネットワーク確認 |
| - | ParameterValidation | SqlInstance/InputObject両方未指定 | パラメータ指定を確認 |

### リトライ仕様

リトライ機能なし（呼び出し元での制御が必要）

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

読み取り専用操作のため、トランザクション管理なし

## パフォーマンス要件

- 単一インスタンス・単一AGの場合：1秒以内
- 複数レプリカ・複数DBの場合：レプリカ数×DB数に比例

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

- Windows認証/SQL認証/AD認証対応
- SqlCredentialによる資格情報の安全な受け渡し
- VIEW SERVER STATE権限要求

## 備考

- SQL Server 2012以上が必須
- SMOのDatabaseReplicaState.AvailabilityDateabaseIdは公式APIのタイポだが、そのまま使用が必要
- 各データベースが2レプリカのAGにある場合、同一DBについて2つのオブジェクトが返される（プライマリ用とセカンダリ用）

---

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

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

### 推奨読解順序

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

SMOのDatabaseReplicaStateオブジェクトが主要なデータ構造です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgDatabaseReplicaState.ps1 | `public/Get-DbaAgDatabaseReplicaState.ps1` | 出力PSCustomObjectの構造（161-201行目） |

**読解のコツ**: 出力は明示的にPSCustomObjectを構築しており、SMOの複数オブジェクトから情報を集約しています。SMOのDatabaseReplicaStateにはタイポ（AvailabilityDateabaseId）があり、コード内にコメントで説明されています（154-156行目）。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgDatabaseReplicaState.ps1 | `public/Get-DbaAgDatabaseReplicaState.ps1` | processブロック（132-205行目）がメイン処理 |

**主要処理フロー**:
1. **133-136行目**: パラメータ検証（SqlInstanceまたはInputObjectの必須チェック）
2. **138-140行目**: SqlInstance指定時のGet-DbaAvailabilityGroup呼び出し
3. **142-145行目**: AGごとのループ開始、レプリカ走査
4. **146-147行目**: レプリカIDでDatabaseReplicaStatesをフィルタ
5. **149-159行目**: データベース走査とDatabaseReplicaState取得
6. **161-201行目**: PSCustomObject生成と出力

#### Step 3: 依存コマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | AG情報取得の内部呼び出し |

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

```
Get-DbaAgDatabaseReplicaState
    │
    ├─ Test-Bound (パラメータ検証)
    │
    ├─ Get-DbaAvailabilityGroup (SqlInstance指定時)
    │      └─ Connect-DbaInstance
    │
    ├─ AG.AvailabilityReplicas (レプリカ走査)
    │
    ├─ AG.DatabaseReplicaStates (状態取得)
    │
    └─ PSCustomObject (出力生成)
```

### データフロー図

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

SqlInstance ───▶ Get-DbaAvailabilityGroup ─┐
                                           │
InputObject ───────────────────────────────┼─▶ AGごとにforeachループ
                                           │
                                           ├─▶ AvailabilityReplicas走査
                                           │
                                           ├─▶ DatabaseReplicaStates取得
                                           │
Database (filter) ────────────────────────▶ AvailabilityDatabasesフィルタ
                                           │
                                           ▼
                                    PSCustomObject生成 ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgDatabaseReplicaState.ps1 | `public/Get-DbaAgDatabaseReplicaState.ps1` | ソース | メインコマンド実装 |
| Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | ソース | AG情報取得依存コマンド |
| Get-DbaAgDatabaseReplicaState.Tests.ps1 | `tests/Get-DbaAgDatabaseReplicaState.Tests.ps1` | テスト | 単体・統合テスト |
| dbatools.psd1 | `dbatools.psd1` | 設定 | モジュールマニフェスト（コマンド登録） |
| dbatools.psm1 | `dbatools.psm1` | 設定 | モジュール定義（コマンドエクスポート） |
