# 機能設計書 24-Set-DbaAgReplica

## 概要

本ドキュメントは、SQL Server可用性グループレプリカの構成プロパティを変更するSet-DbaAgReplica機能の設計仕様を記述する。

### 本機能の処理概要

Set-DbaAgReplicaは、既存の可用性グループレプリカの構成プロパティ（可用性モード、フェイルオーバーモード、バックアップ優先度、読み取り専用ルーティング設定等）を変更するPowerShellコマンドレットである。

**業務上の目的・背景**：可用性グループの運用において、パフォーマンス要件、可用性要件、またはワークロード分散要件に応じてレプリカの構成を調整する必要がある。例えば、同期レプリカを非同期に変更してパフォーマンスを向上させたり、バックアップ優先度を調整してバックアップ実行場所を制御したり、読み取り専用ルーティングを設定してレポーティングワークロードを分散させることができる。本機能は、これらの構成変更を再構築なしで実行可能にする。

**機能の利用シーン**：
- 同期/非同期レプリカモードの切り替え
- 自動/手動フェイルオーバー設定の変更
- バックアップ優先度の調整によるバックアップ実行場所の制御
- 読み取り専用ルーティングの設定による負荷分散
- セカンダリレプリカへの接続モード変更
- セッションタイムアウトの調整
- シーディングモードの変更

**主要な処理内容**：
1. SqlInstanceまたはInputObjectパラメータから対象レプリカを特定
2. Get-DbaAgReplicaを使用してレプリカオブジェクトを取得
3. 各プロパティパラメータに応じてレプリカオブジェクトのプロパティを更新
4. Alter()メソッドを呼び出して変更を適用
5. 更新されたレプリカオブジェクトを返却

**関連システム・外部連携**：SQL Server Management Objects (SMO) のAvailabilityReplicaクラスを使用してSQL Serverと連携する。

**権限による制御**：可用性グループに対するALTER権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | AGレプリカ管理 | 補助機能 | 可用性グループレプリカの構成プロパティ変更 |

## 機能種別

構成変更（可用性グループレプリカのプロパティ変更）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効なPSCredential |
| AvailabilityGroup | string | No | 対象可用性グループ名 | SqlInstance使用時は必須 |
| Replica | string | No | 対象レプリカ名 | SqlInstance使用時は必須 |
| AvailabilityMode | string | No | 可用性モード | AsynchronousCommit/SynchronousCommit |
| FailoverMode | string | No | フェイルオーバーモード | Automatic/Manual/External |
| BackupPriority | int | No | バックアップ優先度 | 0-100 |
| ConnectionModeInPrimaryRole | string | No | プライマリ時の接続モード | AllowAllConnections/AllowReadWriteConnections |
| ConnectionModeInSecondaryRole | string | No | セカンダリ時の接続モード | AllowAllConnections/AllowNoConnections/AllowReadIntentConnectionsOnly/No/Read-intent only/Yes |
| SeedingMode | string | No | シーディングモード | Automatic/Manual |
| SessionTimeout | int | No | セッションタイムアウト（秒） | 10秒以上推奨 |
| EndpointUrl | string | No | エンドポイントURL | TCP://server:port形式 |
| ReadonlyRoutingConnectionUrl | string | No | 読み取り専用ルーティングURL | TCP://server:port形式 |
| ReadOnlyRoutingList | object[] | No | 読み取り専用ルーティングリスト | レプリカ名の配列またはネスト配列 |
| InputObject | AvailabilityReplica | No | パイプラインからのレプリカオブジェクト | SqlInstanceまたはInputObjectいずれか必須 |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- SqlInstanceパラメータ：SQL Serverインスタンス名の直接指定
- InputObjectパラメータ：Get-DbaAgReplicaからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | レプリカ名（サーバーインスタンス名） |
| AvailabilityGroup | string | 親可用性グループ名 |
| AvailabilityMode | string | 可用性モード |
| FailoverMode | string | フェイルオーバーモード |
| BackupPriority | int | バックアップ優先度 |
| ConnectionModeInPrimaryRole | string | プライマリ時接続モード |
| ConnectionModeInSecondaryRole | string | セカンダリ時接続モード |
| EndpointUrl | string | エンドポイントURL |
| ReadonlyRoutingConnectionUrl | string | 読み取り専用ルーティングURL |
| SeedingMode | string | シーディングモード |
| SessionTimeout | int | セッションタイムアウト |
| Parent | object | 親AvailabilityGroupオブジェクトへの参照 |

### 出力先

- PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.AvailabilityReplicaオブジェクト）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstanceまたはInputObjectのいずれかが指定されていることを確認
2. 追加パラメータ検証（SqlInstance指定時）
   └─ AvailabilityGroupおよびReplicaが指定されていることを確認
3. ConnectionModeInSecondaryRole変換
   └─ "No"/"Read-intent only"/"Yes"を標準名に変換
4. レプリカオブジェクト取得
   └─ Get-DbaAgReplicaを使用してレプリカオブジェクトを取得
5. 各プロパティの設定
   └─ 指定されたパラメータに応じてプロパティを更新
6. Alter()実行
   └─ 変更をSQL Serverに適用
7. 結果出力
   └─ 更新されたレプリカオブジェクトを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance or InputObject?}
    B -->|Neither| C[Stop-Function: パラメータエラー]
    B -->|OK| D{InputObject null?}
    D -->|Yes| E{AG and Replica指定?}
    E -->|No| F[Stop-Function: パラメータエラー]
    E -->|Yes| G[Get-DbaAgReplica]
    D -->|No| H[InputObjectを使用]
    G --> I[ConnectionModeInSecondaryRole変換]
    H --> I
    I --> J[foreach agreplica in InputObject]
    J --> K{ShouldProcess?}
    K -->|No| L[スキップ]
    K -->|Yes| M[各プロパティ設定]
    M --> N[ReadOnlyRoutingList処理]
    N --> O{SessionTimeout < 10?}
    O -->|Yes| P[警告メッセージ]
    O -->|No| Q[Alter実行]
    P --> Q
    Q --> R{成功?}
    R -->|Yes| S[オブジェクト出力]
    R -->|No| T[Stop-Function: エラー]
    L --> U{次のレプリカ?}
    S --> U
    T --> U
    U -->|Yes| J
    U -->|No| V[終了]
    C --> V
    F --> V
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | パラメータ相互排他 | SqlInstanceまたはInputObjectのいずれかが必須 | 常時 |
| BR-02 | AG/Replica指定必須 | InputObject未使用時はAvailabilityGroupとReplicaが必須 | InputObject未使用時 |
| BR-03 | SessionTimeout推奨値 | 10秒未満の場合は警告メッセージを表示 | SessionTimeout指定時 |
| BR-04 | ReadOnlyRoutingListの形式 | 単純配列またはネスト配列をサポート | ReadOnlyRoutingList指定時 |
| BR-05 | 確認プロンプト | ConfirmImpactがMediumのため、Confirmパラメータ指定時に確認 | Confirm指定時 |

### 計算ロジック

#### ReadOnlyRoutingList処理ロジック
- 単純配列 `@('Server1', 'Server2')`: 優先順序に従ったルーティング
- ネスト配列 `@(,('Server1', 'Server2'))`: ロードバランス型ルーティング
- `SetLoadBalancedReadOnlyRoutingList()`メソッドを使用

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

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

| 操作 | 対象オブジェクト | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Alter | AvailabilityReplica | UPDATE | レプリカ構成の変更 |

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

#### sys.availability_replicas

SMOのAlter()メソッドにより内部的にALTER AVAILABILITY GROUP ... MODIFY REPLICA文が実行され、各構成プロパティが更新される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | SqlInstanceとInputObjectの両方が未指定 | Stop-Functionでエラーメッセージ出力 |
| - | パラメータエラー | InputObject未使用時にAG/Replicaが未指定 | Stop-Functionでエラーメッセージ出力 |
| - | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionで継続可能エラー |
| - | 操作エラー | Alter失敗 | Stop-Functionで継続可能エラー |
| - | 警告 | SessionTimeout < 10 | Write-Messageで警告出力 |

### リトライ仕様

リトライ機能は実装されていない。エラー発生時は次のレプリカの処理を継続する（-Continueフラグ使用）。

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

SMOのAlter()メソッドは内部的にSQL Serverトランザクションを使用する。変更は即座にコミットされる。

## パフォーマンス要件

特に定義なし。操作自体は軽量で、通常は数秒以内に完了する。

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

- Windows認証、SQL Server認証、Active Directory認証をサポート
- MFA認証にはConnect-DbaInstanceの事前使用が必要
- 可用性グループに対するALTER権限が必要
- ShouldProcess実装によりWhatIfおよびConfirmをサポート

## 備考

- SQL Server 2012以上が必要
- 読み取り専用ルーティングには適切な前提条件が必要（リスナー、接続URL設定等）
- SessionTimeoutの変更は接続障害検出に影響するため、慎重に設定すること
- SeedingMode=Automaticは適切なネットワーク帯域がある環境で使用すること

---

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

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

### 推奨読解順序

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

SMOのAvailabilityReplicaクラスが中心的なデータ構造である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaAgReplica.ps1 | `public/Set-DbaAgReplica.ps1` | パラメータ定義と型（165-188行目）を確認 |

**読解のコツ**: ValidateSetで許可される値を確認。ConnectionModeInSecondaryRoleには互換性エイリアス（No/Yes等）がある。

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

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

**主要処理フロー**:
1. **195-198行目**: パラメータ検証
2. **200-205行目**: InputObject未指定時のAG/Replica必須チェック
3. **207-215行目**: ConnectionModeInSecondaryRoleの値変換
4. **217-219行目**: Get-DbaAgReplicaでレプリカ取得
5. **221-305行目**: 各レプリカに対するプロパティ設定とAlter()実行

#### Step 3: ReadOnlyRoutingList処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaAgReplica.ps1 | `public/Set-DbaAgReplica.ps1` | ReadOnlyRoutingList処理（257-288行目） |

**主要処理フロー**:
- **261-266行目**: ネスト配列かどうかを判定
- **270-285行目**: `List<IList<string>>`を構築
- **287行目**: `SetLoadBalancedReadOnlyRoutingList()`メソッド呼び出し

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

```
Set-DbaAgReplica
    │
    ├─ Test-Bound (パラメータ検証)
    │
    ├─ Stop-Function (エラー処理)
    │
    ├─ Get-DbaAgReplica (レプリカ取得)
    │      └─ Connect-DbaInstance (接続)
    │
    ├─ プロパティ設定処理
    │      ├─ EndpointUrl
    │      ├─ FailoverMode
    │      ├─ AvailabilityMode
    │      ├─ ConnectionModeInPrimaryRole
    │      ├─ ConnectionModeInSecondaryRole
    │      ├─ BackupPriority
    │      ├─ ReadonlyRoutingConnectionUrl
    │      ├─ SeedingMode
    │      ├─ ReadOnlyRoutingList
    │      └─ SessionTimeout
    │
    └─ AvailabilityReplica.Alter() (SMOメソッド)
```

### データフロー図

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

SqlInstance ───────────┐
                       │
SqlCredential ─────────┼──▶ Get-DbaAgReplica ──▶ AvailabilityReplica[]
                       │            │
AvailabilityGroup ─────┤            │
                       │            ▼
Replica ───────────────┤     プロパティ設定
                       │            │
AvailabilityMode ──────┤            │
                       │            │
FailoverMode ──────────┤            ▼
                       │      Alter()
BackupPriority ────────┤            │
                       │            ▼
ReadOnlyRoutingList ───┘

InputObject ──────────────────────────────────────▶ AvailabilityReplica[]
  (パイプライン)                                        (更新済みオブジェクト)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaAgReplica.ps1 | `public/Set-DbaAgReplica.ps1` | ソース | メイン機能実装 |
| Get-DbaAgReplica.ps1 | `public/Get-DbaAgReplica.ps1` | ソース | レプリカ取得 |
| Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | ソース | レプリカ追加 |
| Remove-DbaAgReplica.ps1 | `public/Remove-DbaAgReplica.ps1` | ソース | レプリカ削除 |
