# 機能設計書 204-Remove-DbaDatabaseSafely

## 概要

本ドキュメントは、dbatools PowerShellモジュールのRemove-DbaDatabaseSafely関数の機能設計を定義する。この関数は、検証済みバックアップを作成し、リストア手順をテストした後にデータベースを削除するための包括的なデータベース削除ワークフローを提供する。

### 本機能の処理概要

Remove-DbaDatabaseSafelyは、データベースの整合性を検証し、チェックサム付きバックアップを作成し、リストア手順をテストしてから本番データベースを削除する一連のワークフローを自動実行する。Grant Fritcheyのバックアップ検証ビデオにインスピレーションを受けて作成された。

**業務上の目的・背景**：データベースを削除する前に、復旧可能なバックアップが存在することを確認することは、コンプライアンスとデータ保護の観点から重要である。この関数は、バックアップの作成だけでなく、そのバックアップから実際にリストアできることを検証することで、削除されたデータベースが必要になった場合の復旧を保証する。

**機能の利用シーン**：
- データベースのデコミッション（廃止）作業
- 環境クリーンアップ時の安全なデータベース削除
- コンプライアンス要件で削除前のバックアップ検証が必要な場合
- 本番環境での計画的なデータベース削除

**主要な処理内容**：
1. DBCC CHECKDBによるデータベース整合性検証（オプション）
2. チェックサム付きバックアップの作成
3. リストア用SQL Agentジョブの作成
4. 元のデータベースの削除
5. リストアジョブの実行によるバックアップ検証
6. リストアされたデータベースのDBCC CHECKDB実行
7. テストデータベースの削除

**関連システム・外部連携**：
- SQL Server Agent：リストアジョブの作成・実行
- Backup-DbaDatabase：バックアップ作成
- Restore-DbaDatabase：リストアスクリプト生成
- Remove-DbaDatabase：データベース削除

**権限による制御**：sysadmin権限が必要。SQL Server 2000以上をサポート。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | データベース管理 | 補助機能 | 安全なデータベース削除（バックアップ後） |

## 機能種別

複合処理（バックアップ + 削除 + 検証）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | Yes | 元のデータベースが存在するSQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 | - |
| Destination | DbaInstanceParameter | No | リストアジョブを作成・実行するインスタンス。デフォルトはSqlInstance | - |
| DestinationSqlCredential | PSCredential | No | 宛先インスタンス用の資格情報 | - |
| Database | object[] | No | 削除対象のデータベース名 | Alias='Name' |
| NoDbccCheckDb | switch | No | 事前のDBCC CHECKDBをスキップ | Alias='NoCheck' |
| BackupFolder | string | Yes | バックアップ保存先フォルダパス | UNCパス推奨 |
| JobOwner | string | No | Agentジョブの所有者。デフォルトは'sa' | - |
| UseDefaultFilePaths | switch | No | 宛先サーバーのデフォルトパスを使用 | - |
| CategoryName | string | No | Agentジョブカテゴリ。デフォルトは'Rationalisation' | - |
| BackupCompression | string | No | バックアップ圧縮設定（Default/On/Off） | ValidateSet |
| AllDatabases | switch | No | 全ユーザーデータベースを対象 | - |
| ReuseSourceFolderStructure | switch | No | 元のファイルパス構造を維持 | - |
| Force | switch | No | DBCCエラー時も続行 | - |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- パラメータ入力：SqlInstance、Database、BackupFolder
- パイプライン入力：SqlInstanceパラメータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | 元のSQL Serverインスタンス名 |
| DatabaseName | string | 削除されたデータベース名 |
| JobName | string | 作成されたリストアジョブ名 |
| TestingInstance | string | リストアテストを実行したインスタンス |
| BackupFolder | string | バックアップ保存先フォルダ |

### 出力先

- パイプライン：PSCustomObject
- SQL Server：データベース削除、Agentジョブ作成
- ファイルシステム：バックアップファイル

## 処理フロー

### 処理シーケンス

```
1. 初期化処理
   └─ 1.1 パラメータ検証（Database or AllDatabases必須）
   └─ 1.2 ソースサーバー接続
   └─ 1.3 宛先サーバー接続（異なる場合）
   └─ 1.4 BackupFolderアクセス確認
   └─ 1.5 JobOwnerの存在確認
   └─ 1.6 SQL Agentサービス状態確認
2. 各データベースについて処理
   └─ 2.1 最後のフルバックアップ所要時間確認（10分超の場合は確認）
   └─ 2.2 既存リストアジョブの確認（-Forceで削除）
   └─ 2.3 DBCC CHECKDB実行（NoDbccCheckDbでスキップ）
   └─ 2.4 バックアップ作成（チェックサム付き）
   └─ 2.5 リストア用Agentジョブ作成
   └─ 2.6 元データベースの削除
   └─ 2.7 リストアジョブ実行
   └─ 2.8 リストア完了待機
   └─ 2.9 リストアされたDBのDBCC CHECKDB
   └─ 2.10 テストデータベースの削除
3. 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ検証]
    B --> C{検証OK?}
    C -->|No| D[Stop-Function]
    C -->|Yes| E[サーバー接続]
    E --> F[Agentサービス確認]
    F --> G{データベースループ}
    G -->|次のDB| H{NoDbccCheckDb?}
    H -->|No| I[DBCC CHECKDB]
    I --> J{DBCC成功?}
    J -->|No| K{Force?}
    K -->|No| G
    K -->|Yes| L[警告付きで続行]
    J -->|Yes| L
    H -->|Yes| L
    L --> M[バックアップ作成]
    M --> N[Agentジョブ作成]
    N --> O[元DB削除]
    O --> P[リストアジョブ実行]
    P --> Q[完了待機]
    Q --> R[リストアDBのDBCC]
    R --> S[テストDB削除]
    S --> T[結果出力]
    T --> G
    G -->|完了| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-204-01 | バックアップフォルダ要件 | 異なるサーバー間ではUNCパス必須 | Destination != SqlInstance |
| BR-204-02 | DBCC事前検証 | デフォルトでDBCC CHECKDBを実行し、破損データベースのバックアップを防止 | NoDbccCheckDb未指定時 |
| BR-204-03 | 長時間バックアップ確認 | 最後のフルバックアップが10分超の場合、ユーザーに確認 | 常時 |
| BR-204-04 | DBCCエラー命名 | DBCC失敗+Force時は'DBCCERROR'をファイル名に含める | Force指定時 |
| BR-204-05 | Express非対応 | Express EditionはSQL Agent非サポートのため使用不可 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-----|---------|------|
| DBCC CHECKDB | 対象データベース | SELECT | 整合性検証 |
| バックアップ | 対象データベース | BACKUP | フルバックアップ作成 |
| ジョブ作成 | msdb | INSERT | SQL Agentジョブ登録 |
| データベース削除 | 対象データベース | DROP | 元データベース削除 |
| リストア | master | RESTORE | テストリストア実行 |
| テストDB削除 | リストアDB | DROP | テストデータベース削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | 接続情報を確認 |
| PathAccessError | パスエラー | BackupFolderにアクセス不可 | パスとアクセス権を確認 |
| JobExistsError | ジョブエラー | 同名ジョブが存在 | -Forceで上書き |
| DbccError | 検証エラー | DBCC CHECKDBで破損検出 | -Forceで続行可能 |
| AgentNotRunning | サービスエラー | SQL Agentが停止中 | サービスを起動 |
| RestoreError | リストアエラー | リストアジョブ失敗 | ジョブ履歴を確認 |

### リトライ仕様

データベースリフレッシュは最大5回リトライ（1秒間隔）。

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

各データベースの処理は独立して実行。途中失敗時は次のデータベースに続行。

## パフォーマンス要件

- バックアップ所要時間はデータベースサイズに依存
- 10分超のバックアップは事前に警告

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

- sysadmin権限が必要
- バックアップフォルダへのサービスアカウント権限が必要
- ConfirmImpact=Mediumで確認プロンプト

## 備考

- Rob Sewell (@SQLDBAWithBeard) により作成
- Grant Fritcheyのバックアップ検証ビデオにインスピレーション
- リストアジョブは将来の復旧用に保持される

---

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

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

### 推奨読解順序

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

SQL Server Agentジョブの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Microsoft.SqlServer.Management.Smo.Agent.Job | SMO | ジョブ、ステップ、カテゴリの関係 |

**読解のコツ**: SQL Agentジョブはジョブ→ステップの階層構造を持つ。各ステップにはSubSystem（TransactSql等）とCommandが設定される。

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

Remove-DbaDatabaseSafely.ps1の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Remove-DbaDatabaseSafely.ps1 | `public/Remove-DbaDatabaseSafely.ps1` | 関数全体の処理フロー |

**主要処理フロー**:
1. **168-232行目**: begin ブロック（初期化、接続、検証）
2. **266-333行目**: DBCC CHECKDBとバックアップ処理
3. **384-449行目**: Agentジョブ作成
4. **452-460行目**: 元データベース削除
5. **462-506行目**: リストアジョブ実行と待機
6. **509-529行目**: リストアDBのDBCC検証と削除

#### Step 3: 関連機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | バックアップ作成 |
| 3-2 | Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | リストアスクリプト生成 |
| 3-3 | New-DbaAgentJob.ps1 | `public/New-DbaAgentJob.ps1` | Agentジョブ作成 |
| 3-4 | New-DbaAgentJobStep.ps1 | `public/New-DbaAgentJobStep.ps1` | ジョブステップ作成 |
| 3-5 | Remove-DbaDatabase.ps1 | `public/Remove-DbaDatabase.ps1` | データベース削除 |

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

```
Remove-DbaDatabaseSafely
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ Get-DbaService
    │      └─ SQL Agentサービス状態確認
    │
    ├─ Get-DbaDbBackupHistory
    │      └─ 最後のバックアップ所要時間取得
    │
    ├─ Get-DbaAgentJob
    │      └─ 既存ジョブ確認
    │
    ├─ Start-DbccCheck
    │      └─ DBCC CHECKDB実行
    │
    ├─ Backup-DbaDatabase
    │      └─ チェックサム付きバックアップ
    │
    ├─ New-DbaAgentJobCategory
    │      └─ ジョブカテゴリ作成
    │
    ├─ New-DbaAgentJob
    │      └─ リストアジョブ作成
    │
    ├─ Restore-DbaDatabase -OutputScriptOnly
    │      └─ リストアスクリプト生成
    │
    ├─ New-DbaAgentJobStep
    │      └─ ジョブステップ作成
    │
    ├─ Remove-DbaDatabase
    │      └─ 元データベース削除
    │
    ├─ $job.Start() / $job.Refresh()
    │      └─ リストアジョブ実行・監視
    │
    └─ Get-DbaDatabase
           └─ リストアされたDB取得
```

### データフロー図

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

SqlInstance ─────────────▶ Connect-DbaInstance
    │                              │
Database ────────────────▶ DBCC CHECKDB ───────────────▶ エラー
    │                              │                    (破損時)
BackupFolder ────────────▶ Backup-DbaDatabase
    │                              │
    │                              ▼
    │                    ┌─────────────────────┐
    │                    │ バックアップファイル │
    │                    └─────────────────────┘
    │                              │
Destination ─────────────▶ New-DbaAgentJob ────────────▶ msdb
    │                              │                    (ジョブ登録)
    │                              ▼
    │                    Remove-DbaDatabase
    │                              │
    │                              ▼
    │                    $job.Start() ─────────────────▶ リストア実行
    │                              │
    │                              ▼
    │                    DBCC CHECKDB (リストアDB)
    │                              │
    │                              ▼
    └────────────────────────▶ PSCustomObject ─────────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaDatabaseSafely.ps1 | `public/Remove-DbaDatabaseSafely.ps1` | ソース | メイン関数実装 |
| Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | ソース | バックアップ作成 |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | リストアスクリプト生成 |
| New-DbaAgentJob.ps1 | `public/New-DbaAgentJob.ps1` | ソース | Agentジョブ作成 |
| New-DbaAgentJobStep.ps1 | `public/New-DbaAgentJobStep.ps1` | ソース | ジョブステップ作成 |
| Remove-DbaDatabase.ps1 | `public/Remove-DbaDatabase.ps1` | ソース | データベース削除 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ取得 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得 |
