# 機能設計書 44-Remove-DbaDbBackupRestoreHistory

## 概要

本ドキュメントは、MSDBデータベースからバックアップおよびリストア履歴レコードを削除するdbatools PowerShellコマンド `Remove-DbaDbBackupRestoreHistory` の機能設計書である。

### 本機能の処理概要

この機能は、MSDBデータベースのバックアップおよびリストア履歴テーブルからレコードを削除し、過度なディスク使用量とパフォーマンス低下を防止する。サーバーレベルのクリーンアップ（保持日数指定）とデータベースレベルのクリーンアップ（特定データベースの全履歴削除）の2つのモードをサポートする。

**業務上の目的・背景**：バックアップ頻度の高いSQL Serverインスタンスでは、MSDBのバックアップ履歴テーブル（backupset、backupfile、restorehistory等）が大きく成長し、ディスク容量を消費する。また、SSMSでのバックアップ履歴表示が遅くなるなど、パフォーマンス問題も発生する。定期的なクリーンアップにより、これらの問題を予防する。

**機能の利用シーン**：
- 定期的なMSDBメンテナンスの一環
- データベース廃止時の関連履歴削除
- MSDBデータベースの肥大化対応
- 大規模メンテナンス操作後のクリーンアップ

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続
2. モードの判定（サーバーレベル vs データベースレベル）
3. サーバーレベル: DeleteBackupHistory()で保持日数以前のレコードを削除
4. データベースレベル: DropBackupHistory()で特定データベースの全履歴を削除

**関連システム・外部連携**：MSDBデータベースのシステムテーブル

**権限による制御**：sysadmin権限またはMSDBデータベースへの適切な権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIベースの運用コマンド |

## 機能種別

データ削除 / メンテナンス処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | sysadmin権限、SQL 2000以上 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| KeepDays | int | No | 保持する日数。デフォルト30日 | Databaseと排他 |
| Database | string[] | No | 履歴削除対象データベース名 | KeepDaysと排他 |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | パイプラインからのDBオブジェクト | - |
| EnableException | switch | No | 例外を有効にするスイッチ | - |
| WhatIf | switch | No | 実行せずに何が起きるか表示 | - |
| Confirm | switch | No | 確認プロンプト表示 | - |

### 入力データソース

パラメータ入力またはパイプライン（Get-DbaDatabase出力）

## 出力仕様

### 出力データ

本機能はオブジェクトを返さない。MSDBデータベースの履歴テーブルから削除操作を実行する。

### 出力先

MSDBデータベース（バックアップ/リストア履歴テーブル）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ KeepDaysとDatabaseの排他チェック
2. デフォルト値設定
   └─ KeepDaysもDatabaseも未指定時は30日
3. インスタンスごとの処理
   └─ Connect-DbaInstanceで接続
4. モード判定と処理実行
   ├─ サーバーレベル: server.DeleteBackupHistory(日付)
   └─ データベースレベル: db.DropBackupHistory()
5. 結果の反映
   └─ server.Refresh() / db.Refresh()
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{KeepDays/Database両方未指定?}
    B -->|Yes| C[KeepDays=30設定]
    B -->|No| D{KeepDaysとDatabase両方指定?}
    C --> E[インスタンスループ]
    D -->|Yes| F[Stop-Function]
    D -->|No| E
    E --> G[Connect-DbaInstance]
    G --> H{接続成功?}
    H -->|No| I[Stop-Function Continue]
    H -->|Yes| J{Database未指定?}
    I --> E
    J -->|Yes| K[サーバーレベルクリーンアップ]
    J -->|No| L[InputObjectにDB追加]
    K --> M{ShouldProcess確認}
    M -->|Yes| N[DeleteBackupHistory実行]
    M -->|No| E
    N --> O[server.Refresh]
    O --> E
    L --> P[データベースループ]
    P --> Q{ShouldProcess確認}
    Q -->|Yes| R[DropBackupHistory実行]
    Q -->|No| P
    R --> S[db.Refresh]
    S --> P
    P --> E
    E --> T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-44-01 | デフォルト保持期間 | KeepDaysとDatabase両方未指定時は30日 | パラメータ未指定時 |
| BR-44-02 | パラメータ排他 | KeepDaysとDatabaseは同時指定不可 | 両方指定時 |
| BR-44-03 | サーバーレベル削除 | Database未指定時は全DBの古い履歴を削除 | Database未指定時 |
| BR-44-04 | データベースレベル削除 | Database指定時は該当DBの全履歴を削除 | Database指定時 |

### 計算ロジック

**削除対象日付計算（99行目）**:
```powershell
$odt = (Get-Date).AddDays(-$KeepDays)
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| サーバーレベル削除 | msdb.dbo.backupset等 | DELETE | 指定日付より古い全レコードを削除 |
| データベースレベル削除 | msdb.dbo.backupset等 | DELETE | 指定DBの全履歴レコードを削除 |

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

#### msdb.dbo.backupset（および関連テーブル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | 全カラム | backup_finish_date < 指定日付 | サーバーレベル時 |
| DELETE | 全カラム | database_name = 指定DB | データベースレベル時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | KeepDaysとDatabase両方指定 | Stop-Functionで終了 |
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Function Continueで次のインスタンスへ |
| - | 削除失敗 | 権限不足等 | Stop-Function Continueで継続 |

### リトライ仕様

本機能にはリトライ機構は実装されていない。

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

SMOメソッド（DeleteBackupHistory/DropBackupHistory）内部でトランザクション管理される。

## パフォーマンス要件

- 大量の履歴レコードがある場合、削除に時間がかかる可能性あり
- 本番環境ではOla Hallengrenのメンテナンスソリューションによる定期スケジュール実行を推奨

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

- sysadmin権限またはMSDBへの適切な権限が必要
- ConfirmImpact = 'High'により、デフォルトで確認プロンプトが表示される
- SqlCredentialパラメータでセキュアな認証情報の受け渡しが可能

## 備考

- DeleteBackupHistoryはリストア履歴も削除する（メソッド名にかかわらず）
- DropBackupHistoryも同様にリストア履歴を削除する
- Ola Hallengrenのsp_delete_backuphistoryジョブでの定期実行を推奨

---

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

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

### 推奨読解順序

#### Step 1: パラメータ定義を理解する

入力パラメータの構造と排他関係を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Remove-DbaDbBackupRestoreHistory.ps1 | `public/Remove-DbaDbBackupRestoreHistory.ps1` | 84-93行目のparam定義 |

**読解のコツ**: ConfirmImpact = 'High'により、ShouldProcessで確認が必要になる。

#### Step 2: デフォルト値設定を理解する

KeepDaysのデフォルト30日設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Remove-DbaDbBackupRestoreHistory.ps1 | `public/Remove-DbaDbBackupRestoreHistory.ps1` | 95-99行目のbeginブロック |

**主要処理フロー**:
- **96-98行目**: KeepDays/Database両方未指定時にKeepDays=30設定
- **99行目**: 削除対象日付の計算

#### Step 3: パラメータ排他チェックを理解する

KeepDaysとDatabaseの同時指定エラーを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Remove-DbaDbBackupRestoreHistory.ps1 | `public/Remove-DbaDbBackupRestoreHistory.ps1` | 102-106行目 |

**主要処理フロー**:
- **103-104行目**: 両方指定時のStop-Function

#### Step 4: サーバーレベル削除処理を理解する

DeleteBackupHistory()の使用を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Remove-DbaDbBackupRestoreHistory.ps1 | `public/Remove-DbaDbBackupRestoreHistory.ps1` | 113-123行目 |

**主要処理フロー**:
- **115行目**: ShouldProcess確認
- **117行目**: server.DeleteBackupHistory($odt)実行
- **118行目**: server.Refresh()

#### Step 5: データベースレベル削除処理を理解する

DropBackupHistory()の使用を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Remove-DbaDbBackupRestoreHistory.ps1 | `public/Remove-DbaDbBackupRestoreHistory.ps1` | 128-139行目 |

**主要処理フロー**:
- **131行目**: ShouldProcess確認
- **133行目**: db.DropBackupHistory()実行
- **134行目**: db.Refresh()

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

```
Remove-DbaDbBackupRestoreHistory
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ server.DeleteBackupHistory(DateTime)
    │      └─ SMOメソッドで古い履歴を削除
    │
    └─ db.DropBackupHistory()
           └─ SMOメソッドでDB履歴を削除
```

### データフロー図

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

SqlInstance ────────────────► Connect-DbaInstance ─────────────►
KeepDays ───────────────────► 日付計算 ─────────────────────────►
Database ───────────────────► モード判定 ───────────────────────►
                                      │
                                      ├──► DeleteBackupHistory()
                                      │         │
                                      │         ▼
                                      │   msdb履歴テーブル削除
                                      │
                                      └──► DropBackupHistory()
                                                │
                                                ▼
                                          DB履歴テーブル削除
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaDbBackupRestoreHistory.ps1 | `public/Remove-DbaDbBackupRestoreHistory.ps1` | ソース | メイン機能実装 |
| Remove-DbaDbBackupRestoreHistory.Tests.ps1 | `tests/Remove-DbaDbBackupRestoreHistory.Tests.ps1` | テスト | Pesterテストコード |
