# 画面設計書 1-可用性グループ管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける可用性グループ（Availability Group）管理機能の設計書です。SQL Server AlwaysOn可用性グループの作成、取得、設定変更、削除、同期、テストといった包括的な管理機能を提供するコマンド群について記述します。

### 本画面の処理概要

可用性グループ管理機能は、SQL Server 2012以降で提供されるAlwaysOn可用性グループの完全なライフサイクル管理を実現するPowerShellコマンド群です。

**業務上の目的・背景**：SQL Serverの高可用性（HA）およびディザスタリカバリ（DR）ソリューションであるAlwaysOn可用性グループは、企業の基幹システムにおいて重要な役割を担います。従来、可用性グループの構成や管理にはSSMSやT-SQLの複雑な手順が必要でしたが、本機能群により自動化・効率化が可能となり、運用負荷の軽減とヒューマンエラーの防止を実現します。

**画面へのアクセス方法**：PowerShellコンソールまたはPowerShell ISE/VS Codeから各コマンドレットを実行します。`Get-DbaAvailabilityGroup`、`New-DbaAvailabilityGroup`、`Set-DbaAvailabilityGroup`、`Remove-DbaAvailabilityGroup`、`Sync-DbaAvailabilityGroup`、`Test-DbaAvailabilityGroup`、`Join-DbaAvailabilityGroup`、`Compare-DbaAvailabilityGroup`などのコマンドを使用します。

**主要な操作・処理内容**：
1. **可用性グループの取得（Get-DbaAvailabilityGroup）**：指定インスタンス上の可用性グループ情報を取得し、レプリカの役割、クラスタタイプ、データベース、リスナー等の詳細を表示
2. **可用性グループの作成（New-DbaAvailabilityGroup）**：プライマリレプリカ、セカンダリレプリカ、データベース、リスナーを含む完全な可用性グループを自動構成
3. **可用性グループの設定変更（Set-DbaAvailabilityGroup）**：DTC支援、バックアップ優先度、フェイルオーバー条件、ヘルスチェックタイムアウト等の設定を変更
4. **可用性グループの削除（Remove-DbaAvailabilityGroup）**：DROP AVAILABILITY GROUPを実行して可用性グループを削除
5. **サーバーレベルオブジェクトの同期（Sync-DbaAvailabilityGroup）**：ログイン、ジョブ、リンクサーバー等をプライマリからセカンダリに同期
6. **可用性グループのテスト（Test-DbaAvailabilityGroup）**：レプリカ接続状態の検証およびデータベース追加の前提条件を確認

**画面遷移**：CLIベースのため画面遷移は存在しませんが、コマンド間の連携として、Get-DbaAvailabilityGroupの出力をパイプラインで他のコマンドに渡すことで、取得→設定変更→削除といったワークフローを構成できます。

**権限による表示制御**：可用性グループの操作にはsysadmin固定サーバーロールまたはCONTROL SERVER権限が必要です。読み取り専用の操作（Get-DbaAvailabilityGroup）はVIEW SERVER STATE権限で実行可能な場合もあります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 90 | Get-DbaAvailabilityGroup | 主機能 | 可用性グループの構成と状態情報を取得 |
| 182 | New-DbaAvailabilityGroup | 主機能 | 可用性グループの新規作成、レプリカ設定、データベースシーディング |
| 199 | Remove-DbaAvailabilityGroup | 主機能 | 可用性グループの削除 |
| 216 | Set-DbaAvailabilityGroup | 補助機能 | 可用性グループの構成設定変更 |
| 237 | Sync-DbaAvailabilityGroup | 補助機能 | プライマリからセカンダリへのサーバーレベルオブジェクト同期 |
| 238 | Test-DbaAvailabilityGroup | 補助機能 | 可用性グループのレプリカ接続とデータベース前提条件の検証 |
| 178 | Join-DbaAvailabilityGroup | 補助機能 | 既存の可用性グループへのセカンダリレプリカ追加 |
| 78 | Compare-DbaAvailabilityGroup | 補助機能 | 可用性グループレプリカ間の構成比較 |

## 画面種別

コマンドラインインターフェース（CLI）- PowerShellコマンドレット群

## URL/ルーティング

該当なし（PowerShellモジュールのため）

コマンド呼び出し例：
- `Get-DbaAvailabilityGroup -SqlInstance sql2016`
- `New-DbaAvailabilityGroup -Primary sql2016a -Name SharePoint -Secondary sql2016b`
- `Set-DbaAvailabilityGroup -SqlInstance sql2016 -AvailabilityGroup AG1 -DtcSupportEnabled`

## 入出力項目

### Get-DbaAvailabilityGroup パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス（SQL Server 2012以降） |
| SqlCredential | PSCredential | No | 代替認証情報 |
| AvailabilityGroup | string[] | No | フィルタリング対象のAG名（ワイルドカード対応） |
| IsPrimary | switch | No | プライマリかどうかを示すブール値を返す |
| EnableException | switch | No | 例外処理の有効化 |

### New-DbaAvailabilityGroup パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Primary | DbaInstanceParameter | No | プライマリレプリカのSQLインスタンス |
| PrimarySqlCredential | PSCredential | No | プライマリの認証情報 |
| Secondary | DbaInstanceParameter[] | No | セカンダリレプリカのSQLインスタンス |
| SecondarySqlCredential | PSCredential | No | セカンダリの認証情報 |
| Name | string | Yes | 可用性グループ名 |
| IsContained | switch | No | 包含AGの作成（SQL Server 2022以降） |
| DtcSupport | switch | No | DTC支援の有効化 |
| ClusterType | string | No | クラスタタイプ（Wsfc/External/None） |
| AutomatedBackupPreference | string | No | 自動バックアップ優先設定 |
| FailureConditionLevel | string | No | 障害条件レベル |
| HealthCheckTimeout | int | No | ヘルスチェックタイムアウト（ミリ秒） |
| Database | string[] | No | 追加するデータベース |
| SharedPath | string | No | バックアップ用共有パス |
| SeedingMode | string | No | シーディングモード（Automatic/Manual） |
| IPAddress | ipaddress[] | No | リスナーの静的IPアドレス |
| Port | int | No | リスナーポート（デフォルト1433） |

## 表示項目

### Get-DbaAvailabilityGroup 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLインスタンスのコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| LocalReplicaRole | string | ローカルレプリカの役割（Primary/Secondary） |
| AvailabilityGroup | string | 可用性グループ名 |
| PrimaryReplica | string | プライマリレプリカのサーバー名 |
| ClusterType | string | クラスタタイプ（Wsfc/External/None） |
| DtcSupportEnabled | bool | DTC支援の有効/無効 |
| AutomatedBackupPreference | string | 自動バックアップ優先設定 |
| AvailabilityReplicas | Collection | レプリカのコレクション |
| AvailabilityDatabases | Collection | データベースのコレクション |
| AvailabilityGroupListeners | Collection | リスナーのコレクション |

## イベント仕様

### 1-Get-DbaAvailabilityGroup実行

**処理フロー**：
1. Connect-DbaInstanceを使用してSQLインスタンスに接続（最小バージョン11を指定）
2. IsHadrEnabledプロパティでHADRが有効か確認
3. server.AvailabilityGroupsコレクションから可用性グループを取得
4. 指定されたフィルタ（-AvailabilityGroup）を適用
5. 各AGにComputerName、InstanceName、SqlInstanceのプロパティを追加
6. IsPrimaryスイッチに応じた表示プロパティを選択して出力

### 2-New-DbaAvailabilityGroup実行

**処理フロー**：
1. 前提条件の検証（HADRの有効化、既存AGの確認、証明書の確認）
2. AvailabilityGroupオブジェクトの作成と基本プロパティの設定
3. Add-DbaAgReplicaを使用してプライマリレプリカを追加
4. 各セカンダリに対してAdd-DbaAgReplicaを実行
5. Invoke-Createを使用してAGを作成
6. IPアドレスまたはDHCPでリスナーを追加（Add-DbaAgListener）
7. Join-DbaAvailabilityGroupでセカンダリをAGに参加させる
8. 必要に応じてGrant-DbaAgPermissionでCreateAnyDatabase権限を付与
9. Add-DbaAgDatabaseでデータベースを追加
10. 作成したAGを返却

### 3-Remove-DbaAvailabilityGroup実行

**処理フロー**：
1. SqlInstanceまたはInputObjectパラメータの検証
2. Get-DbaAvailabilityGroupで対象AGを取得
3. 各AGに対してDROP AVAILABILITY GROUP T-SQLを実行
4. 結果オブジェクト（ComputerName、InstanceName、SqlInstance、AvailabilityGroup、Status）を返却

### 4-Sync-DbaAvailabilityGroup実行

**処理フロー**：
1. プライマリへの接続（パスワード取得のためDAC接続を使用）
2. セカンダリレプリカの特定と接続
3. Copy-DbaSpConfigure、Copy-DbaLogin、Copy-DbaCustomError等の同期コマンドを順次実行
4. AgentCategory、AgentOperator、AgentAlert、AgentProxy、AgentSchedule、AgentJobの同期
5. Sync-DbaLoginPermissionでログイン権限を同期

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| New-DbaAvailabilityGroup | システムカタログ | INSERT | 可用性グループメタデータの作成 |
| Set-DbaAvailabilityGroup | システムカタログ | UPDATE | 可用性グループ設定の更新 |
| Remove-DbaAvailabilityGroup | システムカタログ | DELETE | 可用性グループメタデータの削除 |
| Add-DbaAgDatabase | sys.availability_databases_cluster | INSERT | データベースのAG追加 |

### テーブル別更新項目詳細

#### sys.availability_groups

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | 指定されたAG名 | New-DbaAvailabilityGroup実行時 |
| UPDATE | automated_backup_preference | パラメータ値 | Set-DbaAvailabilityGroup実行時 |
| UPDATE | failure_condition_level | パラメータ値 | Set-DbaAvailabilityGroup実行時 |
| DELETE | - | 指定されたAG | Remove-DbaAvailabilityGroup実行時 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 発生条件 |
|--------------|--------------|---------|
| Warning | Availability Group (HADR) is not configured for the instance: {instance}. Use Enable-DbaAgHadr to configure the instance. | HADRが有効化されていない場合 |
| Warning | Primary and secondary ({instance}) default data paths do not match. | 自動シーディング時にパスが一致しない場合 |
| Error | Availability group named {Name} already exists on {Primary} | 同名AGが既に存在する場合 |
| Error | Certificate {Certificate} does not exist on {Primary} | 指定証明書が存在しない場合 |
| Error | You must specify a SharedPath when adding databases to a manually seeded availability group | 手動シーディングでSharedPathが未指定の場合 |
| Error | Automatic seeding mode only supported in SQL Server 2016 and above | SQL Server 2016未満で自動シーディングを指定した場合 |
| Success | Removed | 可用性グループの削除成功時 |

## 例外処理

| 例外状態 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Function -Category ConnectionErrorを発生させ、処理を中断 |
| HADRが無効 | 警告メッセージを表示し、Enable-DbaAgHadrの使用を推奨 |
| バージョン不足 | 機能に必要な最小バージョンを満たさない場合はエラーメッセージを表示して中断 |
| 権限不足 | SMO操作時の権限エラーをキャッチし、適切なメッセージを表示 |
| クラスタ障害 | WSFCクォーラムがない場合の警告と、メタデータ残留の可能性を通知 |

## 備考

- 可用性グループはSQL Server 2012以降で使用可能
- Basic Availability Groupは SQL Server 2016 Standard Editionで使用可能
- 包含可用性グループ（IsContained）はSQL Server 2022以降で使用可能
- ClusterType=Noneは SQL Server 2017以降で使用可能
- Linuxプラットフォームでは ClusterType は External または None のみサポート
- DTCはLinux上のSQL Serverではサポートされていない
- バックアップ/リストア操作時のバックアップファイルはSharedPathに残存する

---

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

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

### 推奨読解順序

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

可用性グループ管理で使用されるSMOオブジェクトの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | 出力オブジェクトの構造とプロパティを理解する |

**読解のコツ**: SMOのAvailabilityGroupオブジェクトは`$server.AvailabilityGroups`コレクションから取得され、LocalReplicaRole、PrimaryReplicaServerName、AvailabilityReplicas、AvailabilityDatabases等の重要なプロパティを持つ。

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

処理の起点となるConnect-DbaInstanceと各コマンドのprocessブロックを特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | Line 117-153: processブロックでの接続と取得処理 |
| 2-2 | New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | Line 403-806: 完全なAG作成フロー |

**主要処理フロー（Get-DbaAvailabilityGroup）**:
1. **Line 120**: Connect-DbaInstanceで接続（MinimumVersion 11指定）
2. **Line 125-127**: IsHadrEnabledプロパティでHADR有効性を確認
3. **Line 129-133**: AvailabilityGroupsコレクションを取得しフィルタリング
4. **Line 135-151**: 各AGにプロパティを追加し、表示形式を選択して出力

#### Step 3: New-DbaAvailabilityGroupの処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | 前提条件の検証とAGオブジェクト作成を理解する |

**主要処理フロー（New-DbaAvailabilityGroup）**:
- **Line 439-444**: プライマリへの接続
- **Line 466-509**: 前提条件の検証（HADR有効化、パス確認等）
- **Line 572-599**: データベースの状態確認（MirroringStatus、Status、RecoveryModel）
- **Line 604-667**: AvailabilityGroupオブジェクトの作成とプロパティ設定
- **Line 670-688**: セカンダリレプリカの追加
- **Line 690-701**: Invoke-CreateでAGを作成
- **Line 703-719**: リスナーの追加（IPアドレスまたはDHCP）
- **Line 721-734**: セカンダリのAG参加
- **Line 756-769**: 自動シーディング時の権限付与
- **Line 771-801**: データベースの追加

#### Step 4: Set/Remove/Sync/Testコマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaAvailabilityGroup.ps1 | `public/Set-DbaAvailabilityGroup.ps1` | Line 172-212: プロパティ変更とAlter()呼び出し |
| 4-2 | Remove-DbaAvailabilityGroup.ps1 | `public/Remove-DbaAvailabilityGroup.ps1` | Line 100-130: DROP AVAILABILITY GROUP実行 |
| 4-3 | Sync-DbaAvailabilityGroup.ps1 | `public/Sync-DbaAvailabilityGroup.ps1` | Line 263-406: 各種Copy-Dbaコマンドの呼び出し |
| 4-4 | Test-DbaAvailabilityGroup.ps1 | `public/Test-DbaAvailabilityGroup.ps1` | Line 115-336: 接続状態とDB前提条件の検証 |

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

```
Get-DbaAvailabilityGroup
    |
    +-- Connect-DbaInstance (MinimumVersion 11)
    |
    +-- $server.AvailabilityGroups (SMO Collection)
    |
    +-- Select-DefaultView

New-DbaAvailabilityGroup
    |
    +-- Connect-DbaInstance (Primary/Secondary)
    |
    +-- Get-DbaAvailabilityGroup (既存確認)
    |
    +-- Get-DbaDbCertificate (証明書確認)
    |
    +-- Test-DbaPath (SharedPath確認)
    |
    +-- Get-DbaDefaultPath (パス比較)
    |
    +-- New-Object AvailabilityGroup
    |
    +-- Add-DbaAgReplica (Primary + Secondary)
    |
    +-- Invoke-Create
    |
    +-- Add-DbaAgListener
    |
    +-- Join-DbaAvailabilityGroup
    |
    +-- Grant-DbaAgPermission (Automatic Seeding)
    |
    +-- Add-DbaAgDatabase

Sync-DbaAvailabilityGroup
    |
    +-- Connect-DbaInstance (DAC for passwords)
    |
    +-- Copy-DbaSpConfigure
    +-- Copy-DbaLogin
    +-- Copy-DbaCustomError
    +-- Copy-DbaCredential
    +-- Copy-DbaDbMail
    +-- Copy-DbaLinkedServer
    +-- Copy-DbaInstanceTrigger
    +-- Copy-DbaAgentJobCategory
    +-- Copy-DbaAgentOperator
    +-- Copy-DbaAgentAlert
    +-- Copy-DbaAgentProxy
    +-- Copy-DbaAgentSchedule
    +-- Copy-DbaAgentJob
    +-- Sync-DbaLoginPermission
```

### データフロー図

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

SqlInstance     ----->  Connect-DbaInstance   ----+
SqlCredential   ----->      (接続確立)            |
                                                  |
                       +<-------------------------+
                       |
                       v
                  IsHadrEnabled   ----->  エラー（無効時）
                       |
                       v
               AvailabilityGroups
                (SMOコレクション)
                       |
                       v
               Select-DefaultView  -----> AvailabilityGroup
                                          オブジェクト群
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | ソース | 可用性グループ情報の取得 |
| New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | ソース | 可用性グループの新規作成 |
| Set-DbaAvailabilityGroup.ps1 | `public/Set-DbaAvailabilityGroup.ps1` | ソース | 可用性グループ設定の変更 |
| Remove-DbaAvailabilityGroup.ps1 | `public/Remove-DbaAvailabilityGroup.ps1` | ソース | 可用性グループの削除 |
| Sync-DbaAvailabilityGroup.ps1 | `public/Sync-DbaAvailabilityGroup.ps1` | ソース | サーバーオブジェクトの同期 |
| Test-DbaAvailabilityGroup.ps1 | `public/Test-DbaAvailabilityGroup.ps1` | ソース | 可用性グループの検証 |
| Join-DbaAvailabilityGroup.ps1 | `public/Join-DbaAvailabilityGroup.ps1` | ソース | セカンダリのAG参加 |
| Compare-DbaAvailabilityGroup.ps1 | `public/Compare-DbaAvailabilityGroup.ps1` | ソース | レプリカ間構成比較 |
| Add-DbaAgReplica.ps1 | `public/Add-DbaAgReplica.ps1` | ソース | レプリカの追加 |
| Add-DbaAgListener.ps1 | `public/Add-DbaAgListener.ps1` | ソース | リスナーの追加 |
| Add-DbaAgDatabase.ps1 | `public/Add-DbaAgDatabase.ps1` | ソース | データベースのAG追加 |
| Grant-DbaAgPermission.ps1 | `public/Grant-DbaAgPermission.ps1` | ソース | AG権限の付与 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立 |
