# 機能設計書 182-New-DbaAvailabilityGroup

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `New-DbaAvailabilityGroup` コマンドレットの機能設計書である。このコマンドレットは、SQL Server可用性グループ（Always On Availability Groups）を自動化されたワークフローで作成する機能を提供する。

### 本機能の処理概要

本機能は、SQL Server可用性グループの作成を完全に自動化し、手動でT-SQLやSSMSを使用して行う複数ステップの設定プロセスを単一のコマンドで実行する。プライマリレプリカの作成、セカンダリレプリカの追加と参加、データベースのシーディング、リスナーの構成まで、高可用性環境のセットアップに必要なすべてのステップを処理する。

**業務上の目的・背景**：高可用性（HA）や災害復旧（DR）ソリューションの構築は複雑で時間がかかる作業である。複数のサーバー間でエンドポイント権限、サービスアカウントアクセス、データベースシーディングモード、クラスター統合などを手動で調整する必要がある。本機能はこれらの複雑な調整を自動化し、設定ミスを防ぎ、展開時間を大幅に短縮する。

**機能の利用シーン**：
- 新規高可用性環境のセットアップ
- 災害復旧ソリューションの構築
- 読み取りスケールアウト構成の展開
- コンテナやLinux環境でのクラスターレス構成
- 開発・テスト環境への本番環境の複製

**主要な処理内容**：
1. すべてのインスタンスで前提条件を検証（HADR有効化、接続確認）
2. 可用性グループオブジェクトの作成とプライマリレプリカの構成
3. データベースミラーリングエンドポイントの設定（適切な認証付き）
4. セカンダリレプリカの追加と自動参加
5. バックアップ/リストアまたは直接シーディングによるデータベースのシード
6. 静的IPまたはDHCPでリスナーを構成
7. 必要なクラスターおよびエンドポイント権限の付与
8. AlwaysOn_health拡張イベントセッションの有効化

**関連システム・外部連携**：Windows Server Failover Cluster (WSFC)、Pacemaker（Linux）、SMO、データベースミラーリングエンドポイント

**権限による制御**：ALTER ANY AVAILABILITY GROUP権限、CONTROL SERVER権限、およびWSFCへの管理アクセスが必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | 可用性グループ管理 | 主機能 | 可用性グループの新規作成、レプリカ設定、データベースシーディング |

## 機能種別

CRUD操作（可用性グループの作成）、構成管理、高可用性設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Primary | DbaInstanceParameter | No | プライマリレプリカをホストするSQL Serverインスタンス | パイプラインから入力可能 |
| PrimarySqlCredential | PSCredential | No | プライマリへの代替認証資格情報 | - |
| Secondary | DbaInstanceParameter[] | No | セカンダリレプリカをホストするSQL Serverインスタンス | 複数指定可能 |
| SecondarySqlCredential | PSCredential | No | セカンダリへの代替認証資格情報 | - |
| Name | string | Yes | 可用性グループの名前 | 必須、WSFC内で一意である必要あり |
| IsContained | switch | No | 含有可用性グループを作成（SQL 2022+） | - |
| ReuseSystemDatabases | switch | No | 含有AG再作成時にシステムDBを再利用 | IsContainedと組み合わせて使用 |
| DtcSupport | switch | No | 分散トランザクションサポートを有効化 | Linux不可 |
| ClusterType | string | No | クラスタリング技術（Wsfc/External/None） | ValidateSet、デフォルトはWsfc |
| AutomatedBackupPreference | string | No | バックアップ優先設定 | ValidateSet: None/Primary/Secondary/SecondaryOnly |
| FailureConditionLevel | string | No | 自動フェイルオーバーをトリガーする条件 | ValidateSet、デフォルトはOnCriticalServerErrors |
| HealthCheckTimeout | int | No | ヘルスチェックタイムアウト（ミリ秒） | デフォルト30000 |
| Basic | switch | No | 基本可用性グループを作成（SQL 2016 Standard+） | - |
| DatabaseHealthTrigger | switch | No | データベースレベルのヘルス監視を有効化 | - |
| Passthru | switch | No | 作成前にAGオブジェクトを返す | - |
| Database | string[] | No | AGに追加するデータベース | Full復旧モデル必須 |
| SharedPath | string | No | データベースバックアップの共有パス | 手動シーディング時に必要 |
| UseLastBackup | switch | No | 既存バックアップを使用 | - |
| Force | switch | No | セカンダリの既存DBを削除してからリストア | SharedPathまたはUseLastBackup必須 |
| AvailabilityMode | string | No | 同期モード（SynchronousCommit/AsynchronousCommit） | ValidateSet、デフォルトはSynchronousCommit |
| FailoverMode | string | No | フェイルオーバーモード（Automatic/Manual/External） | ValidateSet、デフォルトはAutomatic |
| BackupPriority | int | No | バックアップ優先度（0-100） | デフォルト50 |
| Endpoint | string | No | エンドポイント名 | デフォルトはhadr_endpoint |
| EndpointUrl | string[] | No | カスタムエンドポイントURL | TCP://hostname:port形式 |
| ConnectionModeInPrimaryRole | string | No | プライマリの接続モード | ValidateSet |
| ConnectionModeInSecondaryRole | string | No | セカンダリの接続モード | ValidateSet、Standardでは無視 |
| SeedingMode | string | No | シーディングモード（Automatic/Manual） | SQL 2016+でAutomatic利用可能 |
| Certificate | string | No | エンドポイント認証用証明書 | - |
| ConfigureXESession | switch | No | AlwaysOn_health XEセッションを開始 | - |
| IPAddress | ipaddress[] | No | リスナーの静的IPアドレス | Dhcpと排他 |
| SubnetMask | ipaddress | No | リスナーのサブネットマスク | デフォルト255.255.255.0 |
| Port | int | No | リスナーのTCPポート | デフォルト1433 |
| Dhcp | switch | No | DHCPでリスナーIPを取得 | IPAddressと排他 |
| ClusterConnectionOption | string | No | TDS 8.0接続オプション（SQL 2025+） | セミコロン区切りのキー=値ペア |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SQL Serverインスタンス指定（直接指定またはパイプライン入力）
- 可用性グループに追加するデータベース
- ネットワーク共有パス（手動シーディング時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | 可用性グループの名前 |
| PrimaryReplica | string | プライマリレプリカのサーバー名 |
| LocalReplicaRole | string | ローカルレプリカの役割 |
| AvailabilityReplicas | Collection | AGのレプリカコレクション |
| AvailabilityDatabases | Collection | AGのデータベースコレクション |
| AvailabilityGroupListeners | Collection | AGのリスナーコレクション |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ EndpointUrl形式、排他パラメータ、Force要件の確認
2. プライマリインスタンスへの接続
   └─ Connect-DbaInstanceでプライマリに接続
3. 前提条件の検証
   └─ HADR有効化の確認
   └─ シーディングモードに応じたパス確認
4. セカンダリインスタンスへの接続と検証
   └─ 各セカンダリのHADR確認
   └─ 自動シーディング時のデフォルトパス確認
5. 既存AG確認
   └─ 同名AGが存在しないことを確認
6. 証明書確認（指定時）
7. 共有パスアクセス確認
8. データベース検証
   └─ ミラーリング状態、ステータス、復旧モデル確認
9. AGオブジェクト作成
   └─ SMO AvailabilityGroupオブジェクトの生成
   └─ プロパティ設定（バージョンに応じた機能）
10. プライマリレプリカ追加
    └─ Add-DbaAgReplicaでプライマリを追加
11. セカンダリレプリカ追加
    └─ 各セカンダリにAdd-DbaAgReplicaを実行
12. AG作成（Create）
    └─ Invoke-CreateでAGを作成
13. リスナー追加（指定時）
    └─ Add-DbaAgListenerで静的IPまたはDHCPリスナーを作成
14. セカンダリの参加
    └─ Join-DbaAvailabilityGroupで各セカンダリを参加
15. レプリカ接続待機
    └─ 最大20秒間レプリカの接続準備を待機
16. 自動シーディング権限付与（該当時）
    └─ Grant-DbaAgPermissionでCreateAnyDatabase権限付与
17. データベース追加
    └─ Add-DbaAgDatabaseでデータベースをAGに追加
18. 結果取得
    └─ Get-DbaAvailabilityGroupで作成されたAGを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ検証]
    B --> C[プライマリ接続]
    C --> D{HADR有効?}
    D -->|No| E[警告/終了]
    D -->|Yes| F[セカンダリ接続・検証]
    F --> G{前提条件OK?}
    G -->|No| H[警告/終了]
    G -->|Yes| I[既存AG確認]
    I --> J{重複?}
    J -->|Yes| K[エラー終了]
    J -->|No| L[データベース検証]
    L --> M[AGオブジェクト作成]
    M --> N[プライマリレプリカ追加]
    N --> O[セカンダリレプリカ追加]
    O --> P[AG Create実行]
    P --> Q{リスナー指定?}
    Q -->|Yes| R[リスナー追加]
    Q -->|No| S[セカンダリ参加]
    R --> S
    S --> T[接続待機]
    T --> U{自動シーディング?}
    U -->|Yes| V[権限付与]
    U -->|No| W[データベース追加]
    V --> W
    W --> X[結果取得・出力]
    X --> Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | HADR必須 | すべてのレプリカでAlwaysOn HADRが有効である必要がある | 常時 |
| BR-002 | 自動シーディングパス一致 | 自動シーディング時はプライマリとセカンダリのデフォルトパスが一致推奨 | SeedingMode=Automatic時 |
| BR-003 | Full復旧モデル必須 | AGに追加するデータベースはFull復旧モデルが必要 | Database指定時 |
| BR-004 | 手動シーディング共有パス必須 | 手動シーディングでデータベース追加時はSharedPathが必要 | SeedingMode=Manual, Database指定時 |
| BR-005 | Linux制限 | LinuxではClusterType=External/Noneのみ、DtcSupport不可 | Linuxインスタンス時 |
| BR-006 | Standard Edition制限 | Standard EditionではConnectionModeInSecondaryRoleは無効 | Standard Edition時 |
| BR-007 | 基本AG制限 | 基本AGは1データベース、2レプリカまで | Basic=true時 |
| BR-008 | 含有AG要件 | 含有AGはSQL Server 2022以上が必要 | IsContained=true時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| AG作成 | sys.availability_groups等 | INSERT | 可用性グループメタデータの登録 |
| レプリカ追加 | sys.availability_replicas等 | INSERT | レプリカ情報の登録 |
| データベース追加 | sys.availability_databases_cluster等 | INSERT | AGデータベース情報の登録 |
| リスナー追加 | sys.availability_group_listeners等 | INSERT | リスナー情報の登録 |

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

#### sys.availability_groups（可用性グループ）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | group_id, name, automated_backup_preference等 | 指定されたAG構成値 | SMO経由で実行 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | 接続情報・ネットワーク確認 |
| - | HADR未有効 | インスタンスでHADRが有効でない | Enable-DbaAgHadrで有効化 |
| - | AG重複 | 同名AGが既に存在 | 別名を使用またはRemove-DbaAvailabilityGroupで削除 |
| - | 証明書未存在 | 指定した証明書がプライマリに存在しない | 証明書を作成または正しい名前を指定 |
| - | 共有パスアクセス不可 | SharedPathにアクセスできない | アクセス権の確認 |
| - | 復旧モデル不正 | データベースがFull復旧モデルでない | 復旧モデルを変更 |
| - | バージョン不足 | 機能に必要なSQL Serverバージョンでない | SQL Serverをアップグレード |

### リトライ仕様

レプリカ接続待機で最大20秒（500ms x 40回）のリトライを実施。

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

SMOのAG作成メソッドは内部的にトランザクションを管理。複数ステップの操作は個別に実行され、途中で失敗した場合は部分的な状態が残る可能性がある。

## パフォーマンス要件

- データベースシーディングの時間はデータベースサイズとネットワーク帯域幅に依存
- 自動シーディングはネットワーク帯域幅が十分な場合に推奨
- 大規模データベースの手動シーディングにはバックアップ/リストア時間を考慮

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

- ALTER ANY AVAILABILITY GROUP権限が必要
- CONTROL SERVER権限が推奨
- エンドポイント認証には証明書またはWindows認証を使用
- 資格情報はPSCredentialで安全に管理
- ファイアウォールでエンドポイントポート（デフォルト5022）を開放する必要あり

## 備考

- SQL Server 2012以降で利用可能
- バージョンにより利用可能な機能が異なる（自動シーディングはSQL 2016+、含有AGはSQL 2022+）
- バックアップファイルは共有パスに残る
- LinuxでFQDNが必要な場合は、FQDNを使用してエンドポイントを作成

---

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

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

### 推奨読解順序

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

パラメータ定義が多いため、まずパラメータブロックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | 344-399行目のparamブロックで多数のパラメータを確認 |

**読解のコツ**: パラメータは機能別にグループ化されている（AG設定、データベース設定、レプリカ設定、ネットワーク設定）。Get-DbatoolsConfigValueでデフォルト値を動的に取得している箇所に注意。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | 403行目のprocessブロックが処理の開始点 |

**主要処理フロー**:
1. **406-421行目**: パラメータ検証（Force、EndpointUrl形式、IP/DHCP排他）
2. **439-444行目**: プライマリインスタンス接続
3. **446-464行目**: バージョンチェックと機能可用性確認
4. **466-509行目**: 前提条件検証（HADR、パス一致）

#### Step 3: AG作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | 601-667行目のAGオブジェクト作成とレプリカ追加 |

**主要処理フロー**:
- **606行目**: SMO AvailabilityGroupオブジェクト作成
- **607-628行目**: バージョンに応じたプロパティ設定
- **636-657行目**: Add-DbaAgReplicaでレプリカパラメータ構築
- **658行目**: プライマリレプリカ追加
- **673-687行目**: セカンダリレプリカ追加
- **690-701行目**: Invoke-CreateでAG作成

#### Step 4: リスナーとセカンダリ参加を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | 703-768行目のリスナー作成とセカンダリ参加処理 |

**主要処理フロー**:
- **711-718行目**: Add-DbaAgListenerでリスナー追加
- **723-734行目**: Join-DbaAvailabilityGroupでセカンダリを参加
- **738-748行目**: レプリカの接続準備待機（最大20秒）

#### Step 5: データベース追加処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | 771-801行目のデータベース追加処理 |

**主要処理フロー**:
- **757-768行目**: 自動シーディング時の権限付与
- **773-800行目**: Add-DbaAgDatabaseでデータベース追加

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

```
New-DbaAvailabilityGroup
    │
    ├─ Connect-DbaInstance
    │      └─ プライマリ/セカンダリへの接続
    │
    ├─ Get-DbaAvailabilityGroup
    │      └─ 既存AG確認
    │
    ├─ Get-DbaDbCertificate
    │      └─ 証明書確認
    │
    ├─ Test-DbaPath
    │      └─ 共有パスアクセス確認
    │
    ├─ Get-DbaDatabase
    │      └─ データベース情報取得
    │
    ├─ Set-DbaDbRecoveryModel
    │      └─ 復旧モデル変更
    │
    ├─ Add-DbaAgReplica
    │      └─ レプリカ追加（プライマリ/セカンダリ）
    │
    ├─ Invoke-Create
    │      └─ SMO Createメソッド呼び出し
    │
    ├─ Add-DbaAgListener
    │      └─ リスナー作成
    │
    ├─ Join-DbaAvailabilityGroup
    │      └─ セカンダリのAG参加
    │
    ├─ Grant-DbaAgPermission
    │      └─ 自動シーディング権限付与
    │
    └─ Add-DbaAgDatabase
           └─ データベースをAGに追加
```

### データフロー図

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

Primary ─────────────▶ Connect-DbaInstance ──────────▶ $server (プライマリ)
Secondary ───────────▶ Connect-DbaInstance ──────────▶ $secondaries (セカンダリ配列)
Name ─────────────────▶ New-Object AG ───────────────▶ $ag (AGオブジェクト)
                              │
                              ▼
                       Add-DbaAgReplica ─────────────▶ レプリカ構成
                              │
                              ▼
                       Invoke-Create ────────────────▶ AG作成
                              │
                              ▼
                       Add-DbaAgListener ────────────▶ リスナー構成
                              │
                              ▼
                       Join-DbaAvailabilityGroup ────▶ セカンダリ参加
                              │
                              ▼
                       Add-DbaAgDatabase ────────────▶ DB追加
                              │
                              ▼
                       Get-DbaAvailabilityGroup ─────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | ソース | メイン機能の実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | ソース | レプリカ追加 |
| Add-DbaAgListener.ps1 | `public/Add-DbaAgListener.ps1` | ソース | リスナー追加 |
| Add-DbaAgDatabase.ps1 | `public/Add-DbaAgDatabase.ps1` | ソース | データベース追加 |
| Join-DbaAvailabilityGroup.ps1 | `public/Join-DbaAvailabilityGroup.ps1` | ソース | AG参加 |
| Grant-DbaAgPermission.ps1 | `public/Grant-DbaAgPermission.ps1` | ソース | AG権限付与 |
| Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | ソース | AG取得 |
