# 機能設計書 199-Remove-DbaAvailabilityGroup

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`Remove-DbaAvailabilityGroup`機能の設計仕様を記載する。この機能は、DROP AVAILABILITY GROUPを使用してSQL Serverインスタンスから可用性グループを削除する。

### 本機能の処理概要

**業務上の目的・背景**：高可用性セットアップの廃止、別ソリューションへの移行、テスト環境のクリーンアップなどの場面で、可用性グループを適切に削除する必要がある。本機能は、DROP AVAILABILITY GROUP T-SQLコマンドを実行し、可用性グループを安全に削除する。プライマリレプリカからの削除とセカンダリレプリカからの削除では挙動が異なるため、注意が必要。

**機能の利用シーン**：
- 高可用性構成の廃止
- テスト環境のクリーンアップ
- 可用性グループの再構築準備
- サーバーの廃止作業

**主要な処理内容**：
1. SqlInstanceまたはInputObjectから可用性グループオブジェクトを取得
2. ShouldProcess確認（高影響操作のため）
3. DROP AVAILABILITY GROUPクエリを実行
4. 削除結果をPSCustomObjectで返却

**関連システム・外部連携**：SQL Server Always On可用性グループ、WSFC（Windows Server Failover Clustering）。

**権限による制御**：ALTER AVAILABILITY GROUP権限またはCONTROL AVAILABILITY GROUP権限が必要。sysadminロールメンバーでも実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | 可用性グループ管理 | 主機能 | 可用性グループの削除 |

## 機能種別

CRUD操作（DELETE） / 高可用性管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | InputObjectと排他 |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| AvailabilityGroup | string[] | No | 削除する可用性グループ名 | SqlInstance使用時に必要 |
| AllAvailabilityGroups | switch | No | 全可用性グループを削除 | SqlInstance使用時に必要 |
| InputObject | AvailabilityGroup[] | No | 可用性グループオブジェクト（パイプライン入力） | - |
| EnableException | switch | No | 例外をスローするかどうか | - |

### 入力データソース

- パラメータ入力: SqlInstance、AvailabilityGroup
- パイプライン入力: Get-DbaAvailabilityGroupから

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピューター名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| AvailabilityGroup | string | 削除された可用性グループ名 |
| Status | string | 削除状態（"Removed"） |

### 出力先

PowerShellパイプラインへの出力。

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   ├─ SqlInstanceとInputObjectの両方未指定→エラー
   └─ SqlInstance指定時にAvailabilityGroup/AllAvailabilityGroups未指定→エラー
2. InputObject取得
   └─ SqlInstance指定時: Get-DbaAvailabilityGroupで取得
3. 各可用性グループに対してループ
   ├─ ShouldProcess確認（ConfirmImpact = High）
   └─ DROP AVAILABILITY GROUP実行
4. 結果オブジェクト返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance/InputObject両方未指定?}
    B -->|Yes| C[Stop-Function エラー]
    B -->|No| D{SqlInstance指定?}
    D -->|Yes| E{AG/AllAG指定?}
    E -->|No| F[Stop-Function エラー]
    E -->|Yes| G[Get-DbaAvailabilityGroupでInputObject取得]
    D -->|No| H[InputObjectをそのまま使用]
    G --> I[foreach InputObject]
    H --> I
    I --> J{ShouldProcess確認}
    J -->|No| K[次のAGへ]
    J -->|Yes| L[DROP AVAILABILITY GROUP実行]
    L --> M{実行成功?}
    M -->|Yes| N[PSCustomObject返却]
    M -->|No| O[Stop-Function Continue]
    N --> K
    O --> K
    K --> P{次のAGあり?}
    P -->|Yes| I
    P -->|No| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パラメータ必須 | SqlInstanceまたはInputObjectのいずれかが必要 | 常時 |
| BR-002 | AG指定必須 | SqlInstance使用時はAvailabilityGroupまたはAllAvailabilityGroupsが必要 | SqlInstance指定時 |
| BR-003 | 高影響確認 | ConfirmImpact = Highで確認プロンプト | 常時 |
| BR-004 | プライマリ推奨 | プライマリレプリカから削除することを推奨 | 常時 |

### 計算ロジック

特に計算処理はない。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Get-DbaAvailabilityGroup | - | SELECT | 可用性グループ情報取得 |
| DROP AVAILABILITY GROUP | - | DDL | 可用性グループ削除 |

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

#### 削除SQL

```sql
DROP AVAILABILITY GROUP {AvailabilityGroupName}
```

### 削除時の注意事項

**プライマリレプリカから削除した場合**:
- 元のプライマリデータベースへの変更が許可される（高可用性保護なし）

**セカンダリレプリカから削除した場合**:
- プライマリレプリカはRESTORING状態のまま残る
- データベースへの変更は許可されない

**クォーラムなしでの削除**:
- クラスターに格納されているメタデータは削除されない
- クォーラム回復後に再度削除が必要

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | SqlInstance/InputObject両方未指定 | いずれかを指定 |
| - | Stop-Function | AG/AllAG両方未指定 | いずれかを指定 |
| - | Stop-Function | DROP実行失敗 | 権限・状態を確認 |

### リトライ仕様

本機能にリトライ機能はない。

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

DROP AVAILABILITY GROUPは暗黙的なトランザクションで実行される。ロールバックは不可。

## パフォーマンス要件

特になし。単一DDL操作のため、処理時間は短い。

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

- ALTER AVAILABILITY GROUPまたはCONTROL AVAILABILITY GROUP権限が必要
- ConfirmImpact = Highで誤操作を防止
- ShouldProcess対応でWhatIf/Confirmが使用可能

## 備考

- SQL Server 2012以降でサポート
- クラスターにクォーラムがない状態での削除は避けることを推奨
- 削除前にデータベースのバックアップを取得することを推奨
- 詳細: https://docs.microsoft.com/en-us/sql/t-sql/statements/drop-availability-group-transact-sql

---

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

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

### 推奨読解順序

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

Microsoft.SqlServer.Management.Smo.AvailabilityGroup型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Remove-DbaAvailabilityGroup.ps1 | `public/Remove-DbaAvailabilityGroup.ps1` | 出力オブジェクト構造（118-124行目） |

**読解のコツ**: 出力はComputerName、InstanceName、SqlInstance、AvailabilityGroup、Statusの5プロパティを持つPSCustomObject。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Remove-DbaAvailabilityGroup.ps1 | `public/Remove-DbaAvailabilityGroup.ps1` | 関数定義とパラメータ構造 |

**主要処理フロー**:
1. **90-99行目**: param()ブロック
2. **100-109行目**: パラメータ検証
3. **110-112行目**: SqlInstance指定時のInputObject取得
4. **113-129行目**: 削除処理ループ

#### Step 3: 削除処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Remove-DbaAvailabilityGroup.ps1 | `public/Remove-DbaAvailabilityGroup.ps1` | DROP実行ロジック |

**主要処理フロー**:
- **114行目**: ShouldProcess確認
- **117行目**: DROP AVAILABILITY GROUP実行
- **118-124行目**: 結果オブジェクト生成
- **125-127行目**: エラーハンドリング

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

```
Remove-DbaAvailabilityGroup
    │
    ├─ Test-Bound (内部関数)
    │      └─ パラメータ指定チェック
    │
    ├─ Get-DbaAvailabilityGroup
    │      └─ 可用性グループ取得（SqlInstance指定時）
    │
    └─ $ag.Parent.Query()
           └─ DROP AVAILABILITY GROUP実行
```

### データフロー図

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

SqlInstance ───────────────┐
    または                 │
InputObject (パイプライン) ┼──▶ Remove-DbaAvailabilityGroup
                           │           │
AvailabilityGroup ─────────┤           ├─ パラメータ検証
    または                 │           │
AllAvailabilityGroups ─────┘           ├─ Get-DbaAvailabilityGroup
                                       │     （SqlInstance時）
                                       │
                                       ├─ ShouldProcess確認
                                       │
                                       └─ DROP AVAILABILITY GROUP
                                              │
                                              ▼
                                       PSCustomObject
                                       (ComputerName, InstanceName,
                                        SqlInstance, AvailabilityGroup,
                                        Status)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaAvailabilityGroup.ps1 | `public/Remove-DbaAvailabilityGroup.ps1` | ソース | メイン関数定義 |
| Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | ソース | AG取得（パイプライン元） |
| New-DbaAvailabilityGroup.ps1 | `public/New-DbaAvailabilityGroup.ps1` | ソース | AG作成（関連機能） |
