# 機能設計書 203-Remove-DbaDatabase

## 概要

本ドキュメントは、dbatools PowerShellモジュールのRemove-DbaDatabase関数の機能設計を定義する。この関数は、複数のフォールバック手法を使用してユーザーデータベースを削除するための機能を提供する。

### 本機能の処理概要

Remove-DbaDatabaseは、3つの異なる削除メソッドを順次試行することで、スタックしたりロックされたりしたデータベースにも対応できる堅牢なデータベース削除機能を提供する。アクティブな接続、レプリケーション、ミラーリング、その他のロックによって通常の削除が妨げられているデータベースにも対応できる。

**業務上の目的・背景**：データベースの削除は日常的なDBA作業であるが、アクティブな接続や依存関係により削除が失敗することがある。この関数は複数の削除アプローチを自動的に試行することで、このような問題を解決し、DBAの作業効率を向上させる。

**機能の利用シーン**：
- 開発・テスト環境のデータベースクリーンアップ
- アプリケーション廃止に伴うデータベース削除
- データベース移行後の古いデータベース削除
- トラブルシューティング時の問題データベースの強制削除

**主要な処理内容**：
1. 標準的なKillDatabase()メソッドでの削除を試行
2. 失敗時、SINGLE_USER WITH ROLLBACK IMMEDIATEを設定してDROP DATABASE
3. さらに失敗時、SMO Drop()メソッドで削除を試行
4. システムデータベース（master, model, msdb, tempdb, resource）は自動除外
5. 削除成功/失敗の結果をPSCustomObjectとして出力

**関連システム・外部連携**：
- SQL Server Database Engine：データベース削除操作
- SMO (SQL Server Management Objects)：KillDatabase()、Drop()メソッド
- Remove-TeppCacheItem：タブ補完キャッシュの更新

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | データベース管理 | 主画面 | データベースの削除 |

## 機能種別

データ削除（DDL操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes（instanceセット時） | 対象のSQL Serverインスタンス | ParameterSetName="instance" |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Database | object[] | Yes（instanceセット時） | 削除するデータベース名。ワイルドカード対応 | Alias='Name' |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | Yes（databasesセット時） | パイプラインからのデータベースオブジェクト | ValueFromPipeline |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- パラメータ入力：SqlInstance、Database
- パイプライン入力：Get-DbaDatabaseからのデータベースオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverが稼働しているコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | 処理されたデータベース名 |
| Status | string | "Dropped"（成功時）またはエラーメッセージ |

### 出力先

- パイプライン：PSCustomObject
- SQL Server：データベースの削除

## 処理フロー

### 処理シーケンス

```
1. SqlInstanceごとにループ処理
   └─ 1.1 Connect-DbaInstanceでSQL Serverに接続
       └─ 接続失敗時はStop-FunctionでContinue
   └─ 1.2 指定されたDatabaseに一致するデータベースをInputObjectに追加
2. システムデータベースを除外
   └─ master, model, tempdb, resource, msdbを除外
3. 各データベースについて削除処理
   └─ 3.1 KillDatabase()による削除試行
       └─ 成功時: Status="Dropped"を出力
       └─ 失敗時: 次の手法へ
   └─ 3.2 SINGLE_USER + DROP DATABASEによる削除試行
       └─ 成功時: Status="Dropped"を出力
       └─ 失敗時: 次の手法へ
   └─ 3.3 SMO Drop()による削除試行
       └─ 成功時: Status="Dropped"を出力
       └─ 失敗時: エラーメッセージを出力
4. 削除成功時はTeppキャッシュからデータベース名を削除
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstanceループ}
    B -->|次のインスタンス| C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function]
    E --> B
    D -->|Yes| F[データベース取得]
    F --> G[システムDB除外]
    G --> H{データベースループ}
    H -->|次のDB| I{ShouldProcess?}
    I -->|No| H
    I -->|Yes| J[KillDatabase試行]
    J --> K{成功?}
    K -->|Yes| L[Status=Dropped出力]
    L --> M[TeppCache削除]
    M --> H
    K -->|No| N[SINGLE_USER+DROP試行]
    N --> O{成功?}
    O -->|Yes| L
    O -->|No| P[SMO Drop試行]
    P --> Q{成功?}
    Q -->|Yes| L
    Q -->|No| R[エラーStatus出力]
    R --> H
    H -->|完了| B
    B -->|完了| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-203-01 | システムDB保護 | master, model, tempdb, resource, msdbは削除対象から自動除外 | 常時 |
| BR-203-02 | 三段階フォールバック | KillDatabase → SINGLE_USER+DROP → SMO Dropの順で試行 | 削除失敗時 |
| BR-203-03 | 確認プロンプト | ConfirmImpact=Highで実行前に確認を求める | Confirm未指定時 |
| BR-203-04 | 結果出力 | 成功/失敗に関わらず各データベースの結果を出力 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| データベース削除 | - | DDL (DROP DATABASE) | KillDatabaseまたはDROP DATABASE |
| 単一ユーザーモード設定 | - | DDL (ALTER DATABASE) | フォールバック時のみ |

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

#### 対象データベース

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| KillDatabase | - | $server.KillDatabase($db.name) | 全接続を強制切断して削除 |
| ALTER DATABASE | - | SET SINGLE_USER WITH ROLLBACK IMMEDIATE | 排他モードへ移行 |
| DROP DATABASE | - | DROP DATABASE $db | データベース削除 |
| SMO Drop | - | $db.Parent.databases[$dbName].Drop() | SMO経由での削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | 接続情報を確認して再試行 |
| DropFailed | 実行エラー | 全ての削除手法が失敗 | 手動でのトラブルシューティング |

### リトライ仕様

3種類の削除メソッドを順次試行するフォールバック機構を実装。

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

DROP DATABASE操作は暗黙的にトランザクションを使用。SINGLE_USER設定時はROLLBACK IMMEDIATEで既存トランザクションを強制終了。

## パフォーマンス要件

- 単一データベース削除は通常数秒以内に完了
- ロックされたデータベースの場合、フォールバック処理で時間がかかる可能性あり

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

- sysadmin権限が必要
- ConfirmImpact=Highによる誤操作防止
- システムデータベースの自動除外による安全性確保

## 備考

- Chrissy LeMaire (@cl) により作成
- SQL Server 2000以上をサポート
- パイプライン経由でGet-DbaDatabaseと連携可能

---

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

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

### 推奨読解順序

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

SMOのDatabaseオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Microsoft.SqlServer.Management.Smo.Database | SMO | Database.Parent（サーバー参照）、KillDatabase()、Drop()メソッド |

**読解のコツ**: KillDatabase()はサーバーオブジェクトのメソッドで、接続を強制切断してからデータベースを削除する。Drop()はデータベースオブジェクトのメソッド。

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

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

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

**主要処理フロー**:
1. **104-111行目**: インスタンス接続とデータベース取得
2. **113-115行目**: システムデータベースの除外フィルタ
3. **117-132行目**: KillDatabase()による削除試行
4. **133-145行目**: SINGLE_USER + DROP DATABASEによる削除試行
5. **146-171行目**: SMO Drop()による削除試行とエラー出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | パイプライン入力元 |
| 3-2 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | インスタンス接続 |
| 3-3 | Remove-TeppCacheItem.ps1 | `functions/Remove-TeppCacheItem.ps1` | タブ補完キャッシュ更新 |

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

```
Remove-DbaDatabase
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ $server.KillDatabase()
    │      └─ 接続強制切断 + データベース削除
    │
    ├─ $server.Query()
    │      └─ ALTER DATABASE + DROP DATABASE
    │
    ├─ $db.Drop()
    │      └─ SMO経由削除
    │
    ├─ Remove-TeppCacheItem
    │      └─ タブ補完キャッシュから削除
    │
    └─ Get-ErrorMessage
           └─ エラーメッセージ取得
```

### データフロー図

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

SqlInstance ─────────▶ Connect-DbaInstance
    │                        │
    │                        ▼
Database ────────────▶ データベース取得
    │                        │
    │                        ▼
InputObject ─────────▶ システムDB除外
                             │
                             ▼
                    ┌────────────────┐
                    │ 三段階削除試行  │
                    │ 1. KillDatabase │
                    │ 2. SINGLE_USER  │
                    │ 3. SMO Drop     │
                    └────────────────┘
                             │
            ┌────────────────┼────────────────┐
            ▼                ▼                ▼
      成功時出力         TeppCache更新      失敗時出力
    PSCustomObject                       PSCustomObject
    Status=Dropped                       Status=Error
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaDatabase.ps1 | `public/Remove-DbaDatabase.ps1` | ソース | メイン関数実装 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得（パイプライン入力元） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Remove-TeppCacheItem.ps1 | `functions/Remove-TeppCacheItem.ps1` | ソース | タブ補完キャッシュ更新 |
