# 画面設計書 2-AGデータベース管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるAlwaysOn可用性グループ内のデータベース管理機能の設計書です。可用性グループへのデータベースの追加、取得、削除、およびレプリカ状態の確認といった操作を提供するコマンド群について記述します。

### 本画面の処理概要

AGデータベース管理機能は、SQL Server AlwaysOn可用性グループに参加するデータベースのライフサイクル管理を実現するPowerShellコマンド群です。

**業務上の目的・背景**：可用性グループへのデータベースの追加は、バックアップ/リストア、シーディングモードの設定、レプリカ間の同期など、複雑な手順を伴います。本機能群により、これらの手順を自動化し、運用ミスを防止しながら、効率的なデータベースの高可用性設定を実現します。また、データベースの同期状態やフェイルオーバー準備状態を監視することで、可用性グループの健全性を継続的に確認できます。

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

**主要な操作・処理内容**：
1. **AGデータベースの取得（Get-DbaAgDatabase）**：可用性グループ内のデータベース情報（同期状態、フェイルオーバー準備状態、一時停止状態等）を取得
2. **AGへのデータベース追加（Add-DbaAgDatabase）**：バックアップ/リストアまたは自動シーディングを使用して、可用性グループにデータベースを追加
3. **AGからのデータベース削除（Remove-DbaAgDatabase）**：可用性グループからデータベースを削除（実際のデータベースファイルは保持）
4. **レプリカ状態の確認（Get-DbaAgDatabaseReplicaState）**：各レプリカにおけるデータベースの参加状態と同期状態を確認

**画面遷移**：CLIベースのため画面遷移は存在しませんが、Get-DbaAgDatabaseの出力をパイプラインでRemove-DbaAgDatabaseに渡すことで、取得→削除といったワークフローを構成できます。また、Get-DbaDatabase出力をAdd-DbaAgDatabaseにパイプで渡すことも可能です。

**権限による表示制御**：可用性グループのデータベース操作にはALTER AVAILABILITY GROUP権限またはsysadmin固定サーバーロールが必要です。読み取り操作（Get-DbaAgDatabase）はVIEW SERVER STATE権限で実行可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Add-DbaAgDatabase | 主機能 | 可用性グループへのデータベース追加 |
| 11 | Get-DbaAgDatabase | 主機能 | 可用性グループデータベースの取得と同期状態確認 |
| 18 | Remove-DbaAgDatabase | 主機能 | 可用性グループからのデータベース削除 |
| 12 | Get-DbaAgDatabaseReplicaState | 補助機能 | レプリカ全体のデータベース参加状態取得 |

## 画面種別

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

## URL/ルーティング

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

コマンド呼び出し例：
- `Get-DbaAgDatabase -SqlInstance sql2017a -AvailabilityGroup AG1`
- `Add-DbaAgDatabase -SqlInstance sql2017a -AvailabilityGroup AG1 -Database db1 -SharedPath \\share\backup`
- `Remove-DbaAgDatabase -SqlInstance sql2017a -AvailabilityGroup AG1 -Database db1`

## 入出力項目

### Get-DbaAgDatabase パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | 接続先SQL Serverインスタンス（2012以降） |
| SqlCredential | PSCredential | No | 代替認証情報 |
| AvailabilityGroup | string[] | No | フィルタリング対象のAG名 |
| Database | string[] | No | フィルタリング対象のデータベース名 |
| InputObject | AvailabilityGroup[] | No | パイプライン入力用AGオブジェクト |
| EnableException | switch | No | 例外処理の有効化 |

### Add-DbaAgDatabase パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | Yes(NonPipeline) | プライマリレプリカのSQLインスタンス |
| SqlCredential | PSCredential | No | プライマリの認証情報 |
| AvailabilityGroup | string | Yes | 対象の可用性グループ名 |
| Database | string[] | Yes(NonPipeline) | 追加するデータベース名 |
| Secondary | DbaInstanceParameter[] | No | セカンダリレプリカ（省略時は自動検出） |
| SecondarySqlCredential | PSCredential | No | セカンダリの認証情報 |
| InputObject | Database[] | Yes(Pipeline) | パイプライン入力用DBオブジェクト |
| SeedingMode | string | No | シーディングモード（Automatic/Manual） |
| SharedPath | string | No | バックアップ用共有パス（手動シーディング時必須） |
| UseLastBackup | switch | No | 既存のバックアップを使用 |
| AdvancedBackupParams | hashtable | No | バックアップの追加パラメータ |
| NoWait | switch | No | 同期完了を待たずに終了 |
| SkipReuseSourceFolderStructure | switch | No | ソースのフォルダ構造を再利用しない |

### Remove-DbaAgDatabase パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 認証情報 |
| Database | string[] | Yes(SqlInstance使用時) | 削除するデータベース名 |
| AvailabilityGroup | string[] | No | 対象の可用性グループ名 |
| InputObject | object[] | No | パイプライン入力用オブジェクト |
| EnableException | switch | No | 例外処理の有効化 |

## 表示項目

### Get-DbaAgDatabase / Add-DbaAgDatabase 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLインスタンスのコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| AvailabilityGroup | string | 可用性グループ名 |
| LocalReplicaRole | string | ローカルレプリカの役割（Primary/Secondary） |
| Name | string | データベース名 |
| SynchronizationState | string | 同期状態（NotSynchronizing/Synchronizing/Synchronized/Reverting/Initializing） |
| IsFailoverReady | bool | フェイルオーバー準備完了状態 |
| IsJoined | bool | AG参加状態 |
| IsSuspended | bool | データ移動一時停止状態 |
| EstimatedDataLoss | int | 推定データ損失（秒） |
| EstimatedRecoveryTime | int | 推定リカバリ時間（秒） |
| LogSendQueue | int | ログ送信キュー（KB） |
| RedoQueue | int | REDOキュー（KB） |
| SecondaryLagSeconds | int | セカンダリの遅延（秒） |

### Remove-DbaAgDatabase 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLインスタンスのコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| AvailabilityGroup | string | 可用性グループ名 |
| Database | string | データベース名 |
| Status | string | 操作結果（Removed） |

## イベント仕様

### 1-Get-DbaAgDatabase実行

**処理フロー**：
1. SqlInstanceまたはInputObjectの検証
2. SqlInstance指定時はGet-DbaAvailabilityGroupを呼び出してAGオブジェクトを取得
3. InputObject.AvailabilityDatabasesコレクションをループ
4. Databaseパラメータが指定されている場合はフィルタリング
5. 各DBにComputerName、InstanceName、SqlInstance、AvailabilityGroup、LocalReplicaRoleを追加
6. Select-DefaultViewで表示プロパティを選択して出力

### 2-Add-DbaAgDatabase実行

**処理フロー**：
1. タイムアウト設定の読み込み（既存状態待機、同期待機）
2. DatabaseまたはInputObject毎にTest-DbaAvailabilityGroupで前提条件を検証
3. **Step 1**: シーディングモードの設定（必要に応じてreplica.SeedingModeを変更、Automatic時はCreateAnyDatabase権限付与）
4. **Step 2**: 手動シーディング時はBackup-DbaDatabase + Restore-DbaDatabase実行
5. **Step 3**: プライマリでAvailabilityDatabaseオブジェクトを作成しCreate()実行
6. **Step 4**: セカンダリでGet-DbaAgDatabaseを取得し、JoinAvailablityGroup()実行（手動シーディング時のみ）
7. **Step 5**: NoWait未指定時は同期完了まで待機（自動シーディング時は進捗表示）
8. Get-DbaAgDatabaseで出力オブジェクトを取得して返却

### 3-Remove-DbaAgDatabase実行

**処理フロー**：
1. SqlInstanceまたはInputObjectの検証
2. SqlInstance使用時はDatabaseパラメータ必須チェック
3. InputObjectがDatabaseオブジェクトの場合はDatabase名を抽出
4. Get-DbaAgDatabaseで対象AGデータベースを取得
5. 各DBに対してDrop()メソッドを実行
6. 結果オブジェクト（ComputerName、InstanceName、SqlInstance、AvailabilityGroup、Database、Status）を返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Add-DbaAgDatabase | sys.availability_databases_cluster | INSERT | データベースをAGに追加 |
| Add-DbaAgDatabase (手動シーディング) | ユーザーデータベース | RESTORE | セカンダリにDBをリストア |
| Remove-DbaAgDatabase | sys.availability_databases_cluster | DELETE | データベースをAGから削除 |

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

#### sys.availability_databases_cluster

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | database_name | 追加するDB名 | Add-DbaAgDatabase実行時 |
| INSERT | group_id | AG識別子 | Add-DbaAgDatabase実行時 |
| DELETE | - | 指定されたDB | Remove-DbaAgDatabase実行時 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 発生条件 |
|--------------|--------------|---------|
| Verbose | Setting seeding mode to {SeedingMode} | シーディングモード変更時 |
| Verbose | Taking full and log backup of database {Name} | 手動シーディングでバックアップ実行時 |
| Verbose | Restore database {Name} to replica {replicaName} | リストア実行時 |
| Verbose | Database {Name} is already joined to Availability Group | 既にAGに参加済みの場合 |
| Error | Testing prerequisites for joining database {Name} to Availability Group failed | 前提条件テスト失敗時 |
| Error | Failed to take full and log backup of database {Name} | バックアップ失敗時 |
| Error | Failed to restore database {Name} to replica {replicaName} | リストア失敗時 |
| Error | Failed to add database {Name} to Availability Group | AG追加失敗時 |
| Error | Timeout of {seconds} seconds is reached | タイムアウト発生時 |
| Error | Failed while seeding database {Name} to {replicaName} | 自動シーディング失敗時 |
| Success | Removed | データベース削除成功時 |

## 例外処理

| 例外状態 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Function -Category ConnectionErrorを発生させ、処理を中断 |
| 前提条件不足 | Test-DbaAvailabilityGroupでエラーを検出し、処理を中断 |
| バックアップ失敗 | Stop-Functionでエラーメッセージを表示し、Continueで次のデータベースへ |
| リストア失敗 | Stop-Functionでエラーメッセージを表示し、Continueで次のレプリカへ |
| シーディング失敗 | sys.dm_hadr_automatic_seedingのfailure_state_descを表示して中断 |
| タイムアウト | 設定時間（デフォルト60秒/86400秒）経過後にエラーを表示 |
| プラットフォーム不一致 | SkipReuseSourceFolderStructureを自動設定 |

## 備考

- Add-DbaAgDatabaseは5段階のステップで処理を実行（シーディングモード設定→バックアップ/リストア→プライマリ追加→セカンダリ追加→同期待機）
- 自動シーディングはSQL Server 2016以降で使用可能
- 手動シーディング時はSharedPathまたはUseLastBackupが必須
- UseLastBackup使用時は最後のバックアップがログバックアップである必要がある
- NoWaitパラメータ使用時は同期完了を待たずにコマンドが終了（バックグラウンドで同期継続）
- プライマリとセカンダリのプラットフォームが異なる場合（Windows/Linux）、SkipReuseSourceFolderStructureが自動設定される
- タイムアウト値はSet-DbatoolsConfigで変更可能（commands.add-dbaagdatabase.timeout.existing、commands.add-dbaagdatabase.timeout.synchronization）

---

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

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

### 推奨読解順序

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

AGデータベース管理で使用されるSMOオブジェクトの構造を理解することが重要です。

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

**読解のコツ**: AvailabilityDatabaseはAvailabilityGroup.AvailabilityDatabasesコレクションから取得され、SynchronizationState、IsJoined、IsSuspended等の重要な状態プロパティを持つ。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgDatabase.ps1 | `public/Get-DbaAgDatabase.ps1` | Line 126-151: processブロックでの取得処理 |
| 2-2 | Add-DbaAgDatabase.ps1 | `public/Add-DbaAgDatabase.ps1` | Line 271-655: 5ステップの追加処理フロー |

**主要処理フロー（Get-DbaAgDatabase）**:
1. **Line 127-130**: SqlInstance/InputObjectの検証
2. **Line 132-134**: Get-DbaAvailabilityGroupでAGオブジェクトを取得
3. **Line 136-139**: AvailabilityDatabasesをループしフィルタリング
4. **Line 142-149**: カスタムプロパティを追加し出力

#### Step 3: Add-DbaAgDatabaseの処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Add-DbaAgDatabase.ps1 | `public/Add-DbaAgDatabase.ps1` | 5ステップの追加処理を理解する |

**主要処理フロー（Add-DbaAgDatabase）**:
- **Line 259-268**: タイムアウト設定の読み込み
- **Line 279-320**: 前提条件テスト（Test-DbaAvailabilityGroup）
- **Line 337-366**: Step 1 - シーディングモード設定
- **Line 368-442**: Step 2 - バックアップ/リストア実行
- **Line 444-488**: Step 3 - プライマリでのDB追加
- **Line 490-565**: Step 4 - セカンダリでのDB追加・参加
- **Line 567-651**: Step 5 - 同期完了待機

#### Step 4: Remove-DbaAgDatabaseの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Remove-DbaAgDatabase.ps1 | `public/Remove-DbaAgDatabase.ps1` | Line 93-134: 削除処理フロー |

**主要処理フロー（Remove-DbaAgDatabase）**:
- **Line 94-104**: パラメータ検証
- **Line 106-114**: InputObject/SqlInstanceからの対象取得
- **Line 116-133**: Drop()メソッド実行と結果出力

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

```
Get-DbaAgDatabase
    |
    +-- Get-DbaAvailabilityGroup (SqlInstance使用時)
    |
    +-- InputObject.AvailabilityDatabases
    |
    +-- Select-DefaultView

Add-DbaAgDatabase
    |
    +-- Test-DbaAvailabilityGroup (前提条件テスト)
    |
    +-- replica.Alter() (シーディングモード変更)
    |
    +-- Grant-DbaAgPermission (Automatic時)
    |
    +-- Backup-DbaDatabase (手動シーディング時)
    |
    +-- Restore-DbaDatabase (手動シーディング時)
    |
    +-- New-Object AvailabilityDatabase
    |       +-- Create()
    |
    +-- Get-DbaAgDatabase (セカンダリ)
    |       +-- JoinAvailablityGroup() (手動シーディング時)
    |
    +-- sys.dm_hadr_physical_seeding_stats (進捗確認)
    |
    +-- sys.dm_hadr_automatic_seeding (状態確認)

Remove-DbaAgDatabase
    |
    +-- Get-DbaAgDatabase
    |
    +-- AvailabilityDatabases[].Drop()
```

### データフロー図

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

Database名       ----->  Test-DbaAvailabilityGroup ----+
AvailabilityGroup名                                    |
SeedingMode                                            |
SharedPath                                             |
                       +<------------------------------+
                       |
                       v
               シーディングモード設定
                       |
                       v (手動時)
            Backup-DbaDatabase ----> SharedPath
                       |
                       v
            Restore-DbaDatabase <---- SharedPath
                       |
                       v
            AvailabilityDatabase.Create()
                       |
                       v
            JoinAvailablityGroup() (手動時)
                       |
                       v
            同期完了待機 (NoWait未使用時)
                       |
                       v
                AvailabilityDatabase
                   オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgDatabase.ps1 | `public/Get-DbaAgDatabase.ps1` | ソース | AGデータベース情報の取得 |
| Add-DbaAgDatabase.ps1 | `public/Add-DbaAgDatabase.ps1` | ソース | AGへのデータベース追加 |
| Remove-DbaAgDatabase.ps1 | `public/Remove-DbaAgDatabase.ps1` | ソース | AGからのデータベース削除 |
| Test-DbaAvailabilityGroup.ps1 | `public/Test-DbaAvailabilityGroup.ps1` | ソース | 前提条件の検証 |
| Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | ソース | データベースバックアップ |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | データベースリストア |
| Grant-DbaAgPermission.ps1 | `public/Grant-DbaAgPermission.ps1` | ソース | AG権限の付与 |
| Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | ソース | 可用性グループ情報の取得 |
