# 画面設計書：AGレプリカ管理

## 1. 基本情報

| 項目 | 内容 |
|------|------|
| 画面ID | 4 |
| 画面名 | AGレプリカ管理 |
| 画面種別 | CLI（コマンドラインインターフェース） |
| カテゴリ | AvailabilityGroup |
| 関連ファイル | public/Get-DbaAgReplica.ps1, public/Add-DbaAgReplica.ps1, public/Remove-DbaAgReplica.ps1, public/Set-DbaAgReplica.ps1 |

## 2. 概要・目的

AGレプリカ管理は、SQL Server AlwaysOn可用性グループ内のレプリカを管理するためのPowerShellコマンド群です。可用性グループのレプリカ構成を取得、追加、削除、変更する機能を提供します。

レプリカは可用性グループの中核要素であり、プライマリレプリカとセカンダリレプリカの構成により高可用性とディザスタリカバリを実現します。本コマンド群により、レプリカの同期モード、フェイルオーバーモード、バックアップ優先度、読み取り専用ルーティングなどの詳細な設定を管理できます。

## 3. 主要機能

### 3.1 Get-DbaAgReplica

可用性グループレプリカの構成情報とステータスを取得します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | - | 対象SQL Serverインスタンス（SQL Server 2012以降） |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| AvailabilityGroup | string[] | いいえ | - | 対象可用性グループ名（ワイルドカード対応） |
| Replica | string[] | いいえ | - | フィルタするレプリカ名 |
| InputObject | AvailabilityGroup[] | 条件付き | - | パイプライン入力用AGオブジェクト |
| EnableException | switch | いいえ | false | 例外を有効化 |

**出力プロパティ：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| AvailabilityGroup | string | 可用性グループ名 |
| Name | string | レプリカ名 |
| Role | string | 現在の役割（Primary/Secondary） |
| ConnectionState | string | 接続状態 |
| RollupSynchronizationState | string | 同期状態 |
| AvailabilityMode | string | 可用性モード |
| BackupPriority | int | バックアップ優先度（0-100） |
| EndpointUrl | string | エンドポイントURL |
| SessionTimeout | int | セッションタイムアウト（秒） |
| FailoverMode | string | フェイルオーバーモード |
| ReadonlyRoutingList | string[] | 読み取り専用ルーティングリスト |

### 3.2 Add-DbaAgReplica

可用性グループに新しいレプリカを追加します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | はい | - | 追加するレプリカのインスタンス |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| Name | string | いいえ | サーバー名 | レプリカ表示名 |
| ClusterType | string | いいえ | Wsfc | クラスタータイプ（Wsfc/External/None） |
| AvailabilityMode | string | いいえ | SynchronousCommit | 可用性モード |
| FailoverMode | string | いいえ | Automatic | フェイルオーバーモード |
| BackupPriority | int | いいえ | 50 | バックアップ優先度 |
| ConnectionModeInPrimaryRole | string | いいえ | AllowAllConnections | プライマリ時接続モード |
| ConnectionModeInSecondaryRole | string | いいえ | AllowNoConnections | セカンダリ時接続モード |
| SeedingMode | string | いいえ | - | シーディングモード（SQL Server 2016以降） |
| Endpoint | string | いいえ | hadr_endpoint | エンドポイント名 |
| EndpointUrl | string[] | いいえ | - | カスタムエンドポイントURL |
| ReadOnlyRoutingList | string[] | いいえ | - | 読み取り専用ルーティングリスト |
| ReadonlyRoutingConnectionUrl | string | いいえ | - | ルーティング接続URL |
| Certificate | string | いいえ | - | 証明書名 |
| ConfigureXESession | switch | いいえ | false | AlwaysOn_healthセッション構成 |
| SessionTimeout | int | いいえ | - | セッションタイムアウト |
| Passthru | switch | いいえ | false | 作成前のオブジェクト返却 |
| InputObject | AvailabilityGroup | はい | - | 対象可用性グループ |
| EnableException | switch | いいえ | false | 例外を有効化 |

### 3.3 Remove-DbaAgReplica

可用性グループからセカンダリレプリカを削除します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| AvailabilityGroup | string[] | いいえ | - | 対象可用性グループ名 |
| Replica | string[] | 条件付き | - | 削除するレプリカ名 |
| InputObject | AvailabilityReplica[] | 条件付き | - | パイプライン入力用レプリカオブジェクト |
| EnableException | switch | いいえ | false | 例外を有効化 |

**出力プロパティ：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| AvailabilityGroup | string | 可用性グループ名 |
| Replica | string | 削除されたレプリカ名 |
| Status | string | 操作ステータス（Removed） |

### 3.4 Set-DbaAgReplica

既存のレプリカ構成を変更します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| AvailabilityGroup | string | 条件付き | - | 対象可用性グループ名 |
| Replica | string | 条件付き | - | 変更するレプリカ名 |
| AvailabilityMode | string | いいえ | - | 可用性モード |
| FailoverMode | string | いいえ | - | フェイルオーバーモード |
| BackupPriority | int | いいえ | - | バックアップ優先度 |
| ConnectionModeInPrimaryRole | string | いいえ | - | プライマリ時接続モード |
| ConnectionModeInSecondaryRole | string | いいえ | - | セカンダリ時接続モード |
| EndpointUrl | string | いいえ | - | エンドポイントURL |
| ReadonlyRoutingConnectionUrl | string | いいえ | - | ルーティング接続URL |
| ReadOnlyRoutingList | object[] | いいえ | - | ルーティングリスト |
| SeedingMode | string | いいえ | - | シーディングモード |
| SessionTimeout | int | いいえ | - | セッションタイムアウト |
| InputObject | AvailabilityReplica | 条件付き | - | パイプライン入力用レプリカ |
| EnableException | switch | いいえ | false | 例外を有効化 |

## 4. 処理フロー

### 4.1 Get-DbaAgReplica

```
[開始]
   ↓
[パラメータ検証]
   ├── SqlInstanceまたはInputObjectの必須チェック
   ↓
[SqlInstanceが指定された場合]
   ├── Get-DbaAvailabilityGroupでAGオブジェクト取得
   ↓
[レプリカ取得]
   ├── InputObject.AvailabilityReplicasを取得
   ├── Replicaパラメータでフィルタリング
   ↓
[出力プロパティ追加]
   ├── ComputerName, InstanceName, SqlInstance, AvailabilityGroup追加
   ↓
[レプリカ情報出力]
   ↓
[終了]
```

### 4.2 Add-DbaAgReplica

```
[開始]
   ↓
[パラメータ検証]
   ├── EndpointUrl形式チェック（TCP://host:port）
   ├── ReadonlyRoutingConnectionUrl形式チェック
   ↓
[インスタンス接続]
   ├── Connect-DbaInstance（MinimumVersion 11）
   ├── 証明書存在確認（Certificate指定時）
   ↓
[エンドポイント確認/作成]
   ├── Get-DbaEndpointでDatabaseMirroringエンドポイント確認
   ├── 存在しない場合はNew-DbaEndpointで作成
   ├── Start-DbaEndpointでエンドポイント開始
   ↓
[レプリカオブジェクト作成]
   ├── New-Object AvailabilityReplica
   ├── EndpointUrl, FailoverMode, AvailabilityMode設定
   ├── ConnectionMode設定（Standardエディション以外）
   ├── BackupPriority設定
   ├── ReadonlyRoutingList設定（SQL Server 2016以降）
   ├── SeedingMode設定（SQL Server 2016以降）
   ├── SessionTimeout設定
   ↓
[クラスター権限設定]（WSFCの場合）
   ├── NT AUTHORITY\SYSTEMログイン確認/作成
   ├── AlterAnyAvailabilityGroup, ConnectSql, ViewServerState権限付与
   ↓
[XEセッション設定]（ConfigureXESession指定時）
   ├── AlwaysOn_healthセッションの自動開始設定
   ↓
[レプリカ追加]
   ├── AvailabilityReplicas.Add()
   ├── Invoke-Create()（既存AGの場合）
   ├── Join-DbaAvailabilityGroup実行
   ├── Alter()
   ↓
[権限付与]（自動シーディングの場合）
   ├── Grant-DbaAgPermission（CreateAnyDatabase）
   ├── Grant-DbaAgPermission（エンドポイントConnect権限）
   ↓
[レプリカ情報出力]
   ↓
[終了]
```

### 4.3 Remove-DbaAgReplica

```
[開始]
   ↓
[パラメータ検証]
   ├── SqlInstanceまたはInputObjectの必須チェック
   ├── SqlInstance使用時はReplica必須
   ↓
[レプリカ取得]
   ├── Get-DbaAgReplicaで対象レプリカ取得
   ↓
[レプリカ削除]
   ├── Drop()メソッド実行
   ↓
[削除結果出力]
   ├── Status="Removed"
   ↓
[終了]
```

### 4.4 Set-DbaAgReplica

```
[開始]
   ↓
[パラメータ検証]
   ├── SqlInstanceまたはInputObjectの必須チェック
   ├── SqlInstance使用時はAvailabilityGroupとReplica必須
   ↓
[レプリカ取得]
   ├── Get-DbaAgReplicaで対象レプリカ取得
   ↓
[プロパティ変更]
   ├── EndpointUrl, FailoverMode, AvailabilityMode設定
   ├── ConnectionModeInPrimaryRole, ConnectionModeInSecondaryRole設定
   ├── BackupPriority, ReadonlyRoutingConnectionUrl設定
   ├── SeedingMode, SessionTimeout設定
   ├── ReadOnlyRoutingList設定（負荷分散対応）
   ↓
[変更適用]
   ├── Alter()メソッド実行
   ↓
[変更後レプリカ出力]
   ↓
[終了]
```

## 5. バリデーションルール

### 5.1 EndpointUrl形式

- フォーマット: `TCP://system-address:port`
- 正規表現: `TCP://.+:\d+`

### 5.2 SessionTimeout

- 推奨値: 10秒以上
- 10秒未満の場合は警告メッセージを表示

### 5.3 SQL Serverバージョン要件

| 機能 | 最小バージョン |
|------|---------------|
| 基本機能 | SQL Server 2012 (Version 11) |
| ReadonlyRoutingList | SQL Server 2016 (Version 13) |
| ReadonlyRoutingConnectionUrl | SQL Server 2016 (Version 13) |
| SeedingMode | SQL Server 2016 (Version 13) |
| ClusterType (External/None) | SQL Server 2017 (Version 14) |

### 5.4 エディション制限

- Standard EditionではConnectionModeInPrimaryRole/ConnectionModeInSecondaryRoleは設定不可

## 6. エラーハンドリング

| エラー条件 | メッセージ | 対処 |
|-----------|----------|------|
| SqlInstanceもInputObjectも未指定 | "You must supply either -SqlInstance or an Input Object" | いずれかを指定 |
| SqlInstance使用時にReplica未指定（Remove） | "You must specify a replica when using the SqlInstance parameter." | Replicaパラメータを指定 |
| EndpointUrl形式エラー | "EndpointUrl '$epUrl' not in correct format 'TCP://system-address:port'" | 正しい形式を使用 |
| EndpointUrl数不一致 | "The number of elements in EndpointUrl is not correct" | SqlInstanceと同数のURLを指定 |
| 証明書不存在 | "Certificate $Certificate does not exist on $instance" | 証明書を作成/確認 |
| SessionTimeout推奨値未満 | 警告メッセージ表示 | 10秒以上を推奨 |
| AvailabilityGroupとReplica未指定（Set） | "You must specify an AvailabilityGroup and replica or pipe in an availability group to continue." | パラメータを指定 |

## 7. 使用例

### 7.1 全レプリカ情報取得

```powershell
Get-DbaAgReplica -SqlInstance sql2017a
```

### 7.2 特定AGのレプリカ取得

```powershell
Get-DbaAgReplica -SqlInstance sql2017a -AvailabilityGroup SharePoint
```

### 7.3 レプリカ追加

```powershell
Get-DbaAvailabilityGroup -SqlInstance sql2017a -AvailabilityGroup SharePoint |
    Add-DbaAgReplica -SqlInstance sql2017b
```

### 7.4 手動フェイルオーバーモードでレプリカ追加

```powershell
Get-DbaAvailabilityGroup -SqlInstance sql2017a -AvailabilityGroup SharePoint |
    Add-DbaAgReplica -SqlInstance sql2017b -FailoverMode Manual
```

### 7.5 カスタムエンドポイントURLでレプリカ追加

```powershell
Get-DbaAvailabilityGroup -SqlInstance sql2017a -AvailabilityGroup SharePoint |
    Add-DbaAgReplica -SqlInstance sql2017b -EndpointUrl 'TCP://sql2017b.domain.local:5022'
```

### 7.6 レプリカ削除

```powershell
Remove-DbaAgReplica -SqlInstance sql2017a -AvailabilityGroup SharePoint -Replica sp1
```

### 7.7 バックアップ優先度変更

```powershell
Set-DbaAgReplica -SqlInstance sql2016 -Replica sql2016 -AvailabilityGroup SharePoint -BackupPriority 5000
```

### 7.8 読み取り専用ルーティング設定

```powershell
Get-DbaAgReplica -SqlInstance sql2016 -Replica Replica1 |
    Set-DbaAgReplica -ReadOnlyRoutingList Replica2, Replica3
```

### 7.9 負荷分散型ルーティング設定

```powershell
Get-DbaAgReplica -SqlInstance sql2016 -Replica Replica1 |
    Set-DbaAgReplica -ReadOnlyRoutingList @(,('Replica2','Replica3'))
```

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

### 8.1 理解の順序

1. **Get-DbaAgReplica.ps1** - レプリカ情報取得の基本構造を理解
2. **Add-DbaAgReplica.ps1** - レプリカ追加の複雑なフローを把握
3. **Set-DbaAgReplica.ps1** - プロパティ変更パターンを確認
4. **Remove-DbaAgReplica.ps1** - 削除処理のシンプルな実装

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

```
Get-DbaAgReplica
├── Get-DbaAvailabilityGroup (Line 112)
├── InputObject.AvailabilityReplicas (Line 119)
├── Add-Member (Lines 127-131)
└── Select-DefaultView (Line 133)

Add-DbaAgReplica
├── Connect-DbaInstance (Line 244)
├── Get-DbaDbCertificate (Line 250)
├── Get-DbaEndpoint (Line 261)
├── New-DbaEndpoint (Line 280)
├── Start-DbaEndpoint (Line 281)
├── New-Object AvailabilityReplica (Line 294)
├── New-DbaLogin (Line 335)
├── Get-DbaXESession (Line 357)
├── Start-DbaXESession (Line 366)
├── AvailabilityReplicas.Add() (Line 382)
├── Invoke-Create (Line 385)
├── Join-DbaAvailabilityGroup (Line 386)
├── Alter() (Line 387)
├── Grant-DbaAgPermission (Lines 396, 407)
└── Select-DefaultView (Line 422)

Remove-DbaAgReplica
├── Get-DbaAgReplica (Line 98)
└── Drop() (Line 104)

Set-DbaAgReplica
├── Get-DbaAgReplica (Line 218)
├── SetLoadBalancedReadOnlyRoutingList() (Line 287)
└── Alter() (Line 298)
```

### 8.3 データフロー図

```
[ユーザー入力]
     │
     ├─[Get-DbaAgReplica]──────────────────────────────────────┐
     │      │                                                   │
     │      └── Get-DbaAvailabilityGroup                       │
     │              │                                           │
     │              └── AvailabilityReplicas Collection ────────┼─→ [レプリカ情報]
     │                                                          │
     ├─[Add-DbaAgReplica]──────────────────────────────────────┤
     │      │                                                   │
     │      ├── Connect-DbaInstance                            │
     │      │                                                   │
     │      ├── Get-DbaEndpoint / New-DbaEndpoint              │
     │      │                                                   │
     │      ├── New-Object AvailabilityReplica                 │
     │      │                                                   │
     │      ├── AvailabilityReplicas.Add()                     │
     │      │                                                   │
     │      ├── Invoke-Create() → SMO Create                   │
     │      │                                                   │
     │      ├── Join-DbaAvailabilityGroup                      │
     │      │                                                   │
     │      └── Grant-DbaAgPermission ──────────────────────────┼─→ [追加されたレプリカ]
     │                                                          │
     ├─[Set-DbaAgReplica]──────────────────────────────────────┤
     │      │                                                   │
     │      ├── Get-DbaAgReplica                               │
     │      │                                                   │
     │      ├── プロパティ変更                                   │
     │      │                                                   │
     │      └── Alter() → SMO Alter ────────────────────────────┼─→ [変更後レプリカ]
     │                                                          │
     └─[Remove-DbaAgReplica]───────────────────────────────────┤
            │                                                   │
            ├── Get-DbaAgReplica                               │
            │                                                   │
            └── Drop() → SMO Drop ──────────────────────────────┴─→ [削除結果]
```

### 8.4 関連ファイル一覧

| ファイルパス | 役割 | 行数 |
|-------------|------|------|
| public/Get-DbaAgReplica.ps1 | レプリカ情報取得 | 136 |
| public/Add-DbaAgReplica.ps1 | レプリカ追加 | 433 |
| public/Remove-DbaAgReplica.ps1 | レプリカ削除 | 119 |
| public/Set-DbaAgReplica.ps1 | レプリカ設定変更 | 307 |
| public/Get-DbaAvailabilityGroup.ps1 | AG取得（依存） | - |
| public/Join-DbaAvailabilityGroup.ps1 | AG参加（依存） | - |
| public/Grant-DbaAgPermission.ps1 | 権限付与（依存） | - |
| public/Get-DbaEndpoint.ps1 | エンドポイント取得（依存） | - |
| public/New-DbaEndpoint.ps1 | エンドポイント作成（依存） | - |
| public/Start-DbaEndpoint.ps1 | エンドポイント開始（依存） | - |
| public/Get-DbaXESession.ps1 | XEセッション取得（依存） | - |
| public/Start-DbaXESession.ps1 | XEセッション開始（依存） | - |

### 8.5 重要コードポイント

#### エンドポイント自動作成（Add-DbaAgReplica.ps1: Lines 261-286）
```powershell
$ep = Get-DbaEndpoint -SqlInstance $server -Type DatabaseMirroring
if (-not $ep) {
    if (-not $Endpoint) {
        $Endpoint = "hadr_endpoint"
    }
    # エンドポイント作成とURL設定
}
```

#### WSFCクラスター権限設定（Add-DbaAgReplica.ps1: Lines 325-351）
```powershell
if ($ClusterType -eq 'Wsfc') {
    # NT AUTHORITY\SYSTEMにAlterAnyAvailabilityGroup, ConnectSql, ViewServerState権限付与
}
```

#### 読み取り専用ルーティングリスト設定（Set-DbaAgReplica.ps1: Lines 257-288）
```powershell
if ($ReadOnlyRoutingList) {
    # 単純リストと負荷分散リストの両方をサポート
    $rorl = New-Object System.Collections.Generic.List[System.Collections.Generic.IList[string]]
    # SetLoadBalancedReadOnlyRoutingList()を使用
}
```

## 9. 権限要件

| 操作 | 必要な権限 |
|------|----------|
| Get-DbaAgReplica | VIEW ANY DEFINITION または VIEW SERVER STATE |
| Add-DbaAgReplica | ALTER AVAILABILITY GROUP、CREATE ENDPOINT |
| Remove-DbaAgReplica | ALTER AVAILABILITY GROUP |
| Set-DbaAgReplica | ALTER AVAILABILITY GROUP |

## 10. 関連コマンド

- Get-DbaAvailabilityGroup - 可用性グループ取得
- New-DbaAvailabilityGroup - 可用性グループ作成
- Join-DbaAvailabilityGroup - 可用性グループ参加
- Invoke-DbaAgFailover - 手動フェイルオーバー
- Grant-DbaAgPermission - 権限付与
- Get-DbaEndpoint - エンドポイント取得
- New-DbaEndpoint - エンドポイント作成
