# 機能設計書 3-Add-DbaAgReplica

## 概要

本ドキュメントは、dbatools PowerShellモジュールのAdd-DbaAgReplica機能の設計仕様を定義する。本機能は、既存のSQL Server可用性グループに対してレプリカ（セカンダリインスタンス）を追加し、データベースミラーリングエンドポイントの自動作成やWSFCクラスタ権限の設定を含む包括的なレプリカ構成を行う。

### 本機能の処理概要

Add-DbaAgReplicaは、Always On可用性グループに新しいレプリカを追加するPowerShellコマンドである。レプリカの追加時に必要なデータベースミラーリングエンドポイントの作成、クラスタサービスアカウントへの権限付与、XEセッション設定など、手動では複数ステップが必要な構成作業を自動化する。

**業務上の目的・背景**：可用性グループの拡張（レプリカ追加）は、高可用性の向上やリードスケールアウト、ディザスタリカバリ対応において重要な操作である。しかし、手動でのレプリカ追加には、エンドポイント作成、権限設定、フェイルオーバーモード設定など多数の構成要素があり、設定漏れやミスが発生しやすい。本機能は、これらの作業を自動化し、一貫性のある構成を保証する。

**機能の利用シーン**：
- 既存可用性グループへのセカンダリレプリカ追加
- DR（ディザスタリカバリ）サイトへのレプリカ展開
- 読み取り専用ルーティング設定を含むレプリカ追加
- SQL Server 2017以降のクラスタレス（External/None）AG構成

**主要な処理内容**：
1. データベースミラーリングエンドポイントの確認/作成
2. AvailabilityReplicaオブジェクトの生成と構成
3. WSFCクラスタ権限の付与（NT AUTHORITY\SYSTEM）
4. XEセッション（AlwaysOn_health）の設定（オプション）
5. 可用性グループへのレプリカ追加とジョイン
6. 自動シーディング権限の付与（SeedingMode=Automatic時）

**関連システム・外部連携**：
- SQL Server SMO (Server Management Objects)
- Windows Server Failover Cluster (WSFC)
- データベースミラーリングエンドポイント
- SQL Server Extended Events

**権限による制御**：
- 対象インスタンスでのsysadmin権限
- ALTER ANY AVAILABILITY GROUP権限
- エンドポイント作成権限
- WSFCクラスタオブジェクト操作権限

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | AGレプリカ管理 | 主機能 | 可用性グループへのレプリカ追加 |

## 機能種別

インフラストラクチャ管理 / 高可用性構成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 追加するレプリカのSQL Serverインスタンス | SQL Server 2012以上 |
| SqlCredential | PSCredential | No | SQL Server接続用認証情報 | - |
| Name | string | No | レプリカ表示名（デフォルト: DomainInstanceName） | 単一インスタンス時のみ |
| ClusterType | string | No | クラスタ種別（Wsfc/External/None、デフォルト: Wsfc） | SQL Server 2017以上 |
| AvailabilityMode | string | No | 可用性モード（SynchronousCommit/AsynchronousCommit、デフォルト: SynchronousCommit） | - |
| FailoverMode | string | No | フェイルオーバーモード（Automatic/Manual/External、デフォルト: Automatic） | - |
| BackupPriority | int | No | バックアップ優先度（0-100、デフォルト: 50） | - |
| Endpoint | string | No | エンドポイント名 | - |
| EndpointUrl | string[] | No | カスタムエンドポイントURL | TCP://format |
| Passthru | switch | No | 作成前にオブジェクト返却 | - |
| InputObject | AvailabilityGroup | Yes | 対象可用性グループ（パイプライン） | - |
| ConnectionModeInPrimaryRole | string | No | プライマリ時接続モード（デフォルト: AllowAllConnections） | - |
| ConnectionModeInSecondaryRole | string | No | セカンダリ時接続モード（デフォルト: AllowNoConnections） | - |
| ReadOnlyRoutingList | string[] | No | 読み取り専用ルーティングリスト | SQL Server 2016以上 |
| ReadonlyRoutingConnectionUrl | string | No | 読み取り専用ルーティングURL | SQL Server 2016以上 |
| SeedingMode | string | No | シーディングモード（Automatic/Manual） | SQL Server 2016以上 |
| Certificate | string | No | エンドポイント認証用証明書名 | - |
| ConfigureXESession | switch | No | AlwaysOn_healthセッション設定 | - |
| SessionTimeout | int | No | セッションタイムアウト秒数 | 10秒以上推奨 |
| EnableException | switch | No | 例外有効化 | - |

### 入力データソース

- Get-DbaAvailabilityGroupからのパイプライン入力
- SQL Serverインスタンスへの直接接続

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| AvailabilityGroup | string | 可用性グループ名 |
| Name | string | レプリカ名 |
| Role | string | レプリカの役割 |
| RollupSynchronizationState | string | 同期状態 |
| AvailabilityMode | string | 可用性モード |
| BackupPriority | int | バックアップ優先度 |
| EndpointUrl | string | エンドポイントURL |
| SessionTimeout | int | セッションタイムアウト |
| FailoverMode | string | フェイルオーバーモード |
| ReadonlyRoutingList | string[] | 読み取り専用ルーティングリスト |

### 出力先

- PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.AvailabilityReplica型）
- Passthru指定時は作成前のオブジェクトを返却

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ EndpointUrl数とSqlInstance数の一致確認
   └─ EndpointUrlフォーマット検証（TCP://system:port）
   └─ ReadonlyRoutingConnectionUrlフォーマット検証
   └─ ConnectionModeInSecondaryRole値の正規化

2. 各インスタンスについてループ処理
   └─ Connect-DbaInstance（MinimumVersion 11）
   └─ 証明書存在確認（Certificate指定時）

3. エンドポイント処理
   └─ 既存エンドポイント確認
   └─ なければNew-DbaEndpointで作成
   └─ Start-DbaEndpointで起動
   └─ EndpointUrl取得（Fqdn）

4. レプリカオブジェクト生成
   └─ AvailabilityReplicaオブジェクト作成
   └─ エンドポイントURL設定
   └─ フェイルオーバーモード設定
   └─ 可用性モード設定
   └─ 接続モード設定（Standard Edition以外）
   └─ バックアップ優先度設定
   └─ 読み取り専用ルーティング設定（2016+）
   └─ シーディングモード設定（2016+）
   └─ セッションタイムアウト設定

5. クラスタ権限付与（Wsfc時）
   └─ NT AUTHORITY\SYSTEMログイン確認/作成
   └─ AlterAnyAvailabilityGroup権限付与
   └─ ConnectSql権限付与
   └─ ViewServerState権限付与

6. XEセッション設定（ConfigureXESession時）
   └─ AlwaysOn_healthセッション取得
   └─ AutoStart設定
   └─ セッション起動

7. レプリカ追加
   └─ Passthru時: オブジェクト返却
   └─ 通常時: Invoke-Create実行
   └─ Join-DbaAvailabilityGroup実行
   └─ 自動シーディング権限付与（SeedingMode=Automatic時）

8. エンドポイント権限付与
   └─ サービスアカウントへConnect権限付与（証明書未使用時）

9. 結果出力
   └─ NotePropertyでメタデータ追加
   └─ Select-DefaultViewで表示
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ検証]
    B --> C{検証OK?}
    C -->|No| Z[エラー終了]
    C -->|Yes| D[Connect-DbaInstance]
    D --> E{証明書指定?}
    E -->|Yes| F{証明書存在?}
    F -->|No| Z
    E -->|No| G[エンドポイント確認]
    F -->|Yes| G
    G --> H{エンドポイント存在?}
    H -->|No| I[New-DbaEndpoint]
    I --> J[Start-DbaEndpoint]
    H -->|Yes| K[Fqdn取得]
    J --> K
    K --> L[Replicaオブジェクト生成]
    L --> M[プロパティ設定]
    M --> N{ClusterType=Wsfc?}
    N -->|Yes| O[クラスタ権限付与]
    N -->|No| P{ConfigureXESession?}
    O --> P
    P -->|Yes| Q[XEセッション設定]
    P -->|No| R{Passthru?}
    Q --> R
    R -->|Yes| S[オブジェクト返却]
    R -->|No| T[Invoke-Create]
    T --> U[Join-DbaAvailabilityGroup]
    U --> V{SeedingMode=Automatic?}
    V -->|Yes| W[CreateAnyDatabase権限付与]
    V -->|No| X{証明書未使用?}
    W --> X
    X -->|Yes| Y[エンドポイント権限付与]
    X -->|No| AA[結果出力]
    Y --> AA
    S --> AB[終了]
    AA --> AB
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | SQLバージョン要件 | SQL Server 2012以上が必要 | 常時 |
| BR-02 | ClusterType制限 | External/NoneはSQL Server 2017以上 | ClusterType指定時 |
| BR-03 | 読み取りルーティング制限 | SQL Server 2016以上が必要 | ReadOnly*パラメータ使用時 |
| BR-04 | シーディングモード制限 | SQL Server 2016以上が必要 | SeedingMode指定時 |
| BR-05 | セッションタイムアウト推奨 | 10秒以上を推奨 | SessionTimeout指定時 |
| BR-06 | Standard Edition制限 | ConnectionModeは設定不可 | Standard Edition時 |
| BR-07 | デフォルトエンドポイント名 | "hadr_endpoint" | Endpoint未指定時 |

### 計算ロジック

- EndpointUrlからIPアドレス抽出: `$epUrl -replace 'TCP://(.+):\d+', '$1'`
- EndpointUrlからポート抽出: `$epUrl -replace 'TCP://.+:(\d+)', '$1'`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| レプリカ追加 | master.sys.availability_replicas | INSERT | レプリカ情報登録 |
| ログイン作成 | master.sys.server_principals | INSERT | SYSTEMログイン作成 |
| 権限付与 | master.sys.server_permissions | INSERT | サーバー権限付与 |
| エンドポイント作成 | master.sys.endpoints | INSERT | ミラーリングエンドポイント |

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

#### master.sys.availability_replicas

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | replica_server_name | インスタンス名 | SMO経由 |
| INSERT | endpoint_url | エンドポイントURL | SMO経由 |
| INSERT | availability_mode | 0/1 | Async/Sync |
| INSERT | failover_mode | 0/1 | Manual/Auto |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ParameterError | EndpointUrl数とSqlInstance数不一致 | 数を合わせる |
| - | ParameterError | EndpointUrlフォーマット不正 | TCP://format確認 |
| - | ConnectionError | SQL Server接続失敗 | 接続情報確認 |
| - | CertificateError | 指定証明書が存在しない | 証明書名確認 |
| - | PermissionError | クラスタ権限付与失敗 | 手動権限確認 |
| - | CreateError | レプリカ作成失敗 | 詳細エラー確認 |

### リトライ仕様

- 本機能にリトライロジックは実装されていない
- 失敗時はStop-Functionでエラー出力

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

- SMOのCreate()メソッドは内部でトランザクション管理
- Join-DbaAvailabilityGroupは別トランザクション
- 途中失敗時は部分的に処理完了の可能性あり

## パフォーマンス要件

- エンドポイント作成・起動に数秒を要する
- クラスタ権限付与はWSFCとの通信を伴う
- XEセッション起動に追加時間
- 複数インスタンス指定時は順次処理

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

- SQL Server認証またはWindows認証対応
- 証明書認証によるエンドポイント保護オプション
- NT AUTHORITY\SYSTEMへの自動権限付与（WSFC時）
- サービスアカウントへのConnect権限自動付与

## 備考

- ConnectionModeInSecondaryRoleは"No"/"Read-intent only"/"Yes"形式も受付（内部正規化）
- ClusterTypeデフォルトはDbatoolsConfigで変更可能
- ConnectionModeInSecondaryRoleデフォルトもDbatoolsConfigで変更可能
- SYSTEMログインのSID検索で多言語対応（非英語システム対応）

---

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

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

### 推奨読解順序

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

パラメータ構造とValidateSetによる制約を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | param()ブロックの構造（182-212行目） |
| 1-2 | Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | ValidateSetによる値制約確認 |

**読解のコツ**: Get-DbatoolsConfigValueでデフォルト値を取得している箇所（189行目, 198行目）に注目。

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

パラメータ検証ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | process開始部のバリデーション（213-240行目） |

**主要処理フロー**:
1. **214-225行目**: EndpointUrlフォーマット検証
2. **227-230行目**: ReadonlyRoutingConnectionUrl検証
3. **232-240行目**: ConnectionModeInSecondaryRole正規化

#### Step 3: エンドポイント処理を理解する

エンドポイントの確認・作成・起動フローを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | エンドポイント確認と作成（261-286行目） |

**主要処理フロー**:
- **261行目**: Get-DbaEndpointで既存確認
- **267-280行目**: New-DbaEndpointでエンドポイント作成（IPアドレス抽出含む）
- **281行目**: Start-DbaEndpointで起動

#### Step 4: レプリカ構成を理解する

AvailabilityReplicaオブジェクトの生成と各種プロパティ設定を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | レプリカオブジェクト生成と設定（292-322行目） |

**主要処理フロー**:
- **294行目**: AvailabilityReplicaオブジェクト生成
- **296-302行目**: 基本プロパティ設定
- **304-314行目**: バージョン依存機能（2016+）の設定
- **316-322行目**: SessionTimeout設定（10秒未満は警告）

#### Step 5: クラスタ権限付与を理解する

WSFC環境でのNT AUTHORITY\SYSTEM権限付与を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | クラスタ権限付与（324-352行目） |

**主要処理フロー**:
- **329-331行目**: SYSTEMログインSID検索（多言語対応）
- **333-337行目**: SYSTEMログイン作成（未存在時）
- **341-347行目**: ServerPermissionSet生成と付与

#### Step 6: レプリカ追加とジョインを理解する

レプリカのAG追加、ジョイン、権限付与を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | レプリカ追加処理（378-413行目） |

**主要処理フロー**:
- **378-380行目**: Passthru判定
- **382-388行目**: Invoke-Create、Join-DbaAvailabilityGroup、Alter
- **393-400行目**: Automatic時のCreateAnyDatabase権限付与
- **403-411行目**: サービスアカウントへのConnect権限付与

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

```
Add-DbaAgReplica
    │
    ├─ Connect-DbaInstance (接続)
    │
    ├─ Get-DbaDbCertificate (証明書確認)
    │
    ├─ Get-DbaEndpoint (エンドポイント確認)
    │      └─ New-DbaEndpoint (作成)
    │             └─ Start-DbaEndpoint (起動)
    │
    ├─ SMO AvailabilityReplica.New() (レプリカ生成)
    │
    ├─ New-DbaLogin (SYSTEMログイン作成)
    │
    ├─ Server.Grant() (クラスタ権限付与)
    │
    ├─ Get-DbaXESession (XEセッション取得)
    │      └─ Start-DbaXESession (起動)
    │
    ├─ Invoke-Create (レプリカ作成)
    │
    ├─ Join-DbaAvailabilityGroup (AGジョイン)
    │
    └─ Grant-DbaAgPermission (権限付与)
           ├─ CreateAnyDatabase (Automatic時)
           └─ Connect (エンドポイント)
```

### データフロー図

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

SqlInstance ─────────────▶ Connect-DbaInstance
                                  │
InputObject (AG) ────────────────▶│
                                  ▼
                          ┌─────────────────────┐
                          │ エンドポイント処理   │
EndpointUrl ────────────▶ │ Get/New/Start      │
Certificate ────────────▶ │                     │
                          └─────────────────────┘
                                  │
                                  ▼
AvailabilityMode ────────▶┌─────────────────────┐
FailoverMode ────────────▶│ Replicaオブジェクト │
BackupPriority ──────────▶│ 生成・設定          │
ConnectionMode ──────────▶│                     │
ReadOnlyRouting ─────────▶│                     │
SeedingMode ─────────────▶│                     │
                          └─────────────────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             ▼             ▼
             [Wsfc権限]    [XE設定]     [Passthru?]
                    │             │             │
                    └─────────────┼─────────────┘
                                  ▼
                          ┌─────────────────────┐
                          │ AG追加・ジョイン    │
                          │ 権限付与            │
                          └─────────────────────┘
                                  │
                                  ▼
                          AvailabilityReplica
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | ソース | メインコマンド実装 |
| Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | ソース | エンドポイント取得 |
| New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | ソース | エンドポイント作成 |
| Start-DbaEndpoint.ps1 | `public/Start-DbaEndpoint.ps1` | ソース | エンドポイント起動 |
| Join-DbaAvailabilityGroup.ps1 | `public/Join-DbaAvailabilityGroup.ps1` | ソース | AGジョイン |
| Grant-DbaAgPermission.ps1 | `public/Grant-DbaAgPermission.ps1` | ソース | AG権限付与 |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | XEセッション取得 |
| Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | ソース | XEセッション起動 |
| New-DbaLogin.ps1 | `public/New-DbaLogin.ps1` | ソース | ログイン作成 |
