# 画面設計書：24-バックアップ管理

## 1. 基本情報

| 項目 | 内容 |
|------|------|
| 画面ID | 24 |
| 画面名 | バックアップ管理 |
| カテゴリ | バックアップ |
| 対応コマンド | Find-DbaBackup, Remove-DbaBackup |
| 関連機能No | 107, 108 |

## 2. 概要・目的

バックアップファイルの検索と保持期間に基づくクリーンアップを管理する機能群です。ファイルシステム上のバックアップファイル（.bak, .trn, .dif等）を再帰的に検索し、指定した保持期間より古いファイルを特定・削除します。

SQL Server メンテナンスプランのバックアップクリーンアップタスクをPowerShellで置き換え、より柔軟な制御を提供します。

## 3. 機能説明

### 3.1 Find-DbaBackup - バックアップファイル検索

指定したディレクトリから保持期間を超過したバックアップファイルを検索します。

**主要機能:**
- 再帰的なディレクトリ検索
- 拡張子によるフィルタリング（bak, trn, dif等）
- 保持期間による経過時間フィルタリング
- アーカイブビットによる安全性確認

**保持期間の形式:**
| 単位 | 表記例 | 意味 |
|------|--------|------|
| h | 48h | 48時間 |
| d | 7d | 7日間 |
| w | 4w | 4週間 |
| m | 1m | 1ヶ月 |

### 3.2 Remove-DbaBackup - バックアップファイル削除

Find-DbaBackupの機能に加え、検出したファイルを自動削除します。

**主要機能:**
- 保持期間超過ファイルの削除
- 空フォルダの自動削除オプション
- WhatIfによる事前確認
- ShouldProcess対応（Confirmサポート）

## 4. パラメータ仕様

### 4.1 Find-DbaBackup パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| Path | string | Yes | - | 検索対象のルートディレクトリパス |
| BackupFileExtension | string | Yes | - | 検索する拡張子（ピリオドなし：bak, trn, dif） |
| RetentionPeriod | string | Yes | - | 保持期間（48h, 7d, 4w, 1m形式） |
| CheckArchiveBit | switch | No | $false | アーカイブ済みファイルのみを対象 |
| EnableException | switch | No | $false | 例外を有効化 |

### 4.2 Remove-DbaBackup パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| Path | string | Yes | - | クリーンアップ対象のルートディレクトリパス |
| BackupFileExtension | string | Yes | - | 削除対象の拡張子（ピリオドなし） |
| RetentionPeriod | string | Yes | - | 保持期間（48h, 7d, 4w, 1m形式） |
| CheckArchiveBit | switch | No | $false | アーカイブ済みファイルのみを削除 |
| RemoveEmptyBackupFolder | switch | No | $false | 空フォルダを削除 |
| EnableException | switch | No | $false | 例外を有効化 |
| WhatIf | switch | No | $false | 実行せず結果を表示 |
| Confirm | switch | No | $false | 実行前に確認 |

## 5. 出力仕様

### 5.1 Find-DbaBackup 出力オブジェクト

**型**: System.IO.FileInfo

| プロパティ | 型 | 説明 |
|-----------|-----|------|
| FullName | string | ファイルの完全パス |
| Name | string | ファイル名（拡張子含む） |
| Extension | string | ファイル拡張子 |
| DirectoryName | string | 親ディレクトリパス |
| Length | long | ファイルサイズ（バイト） |
| LastWriteTime | DateTime | 最終更新日時（保持期間判定に使用） |
| Attributes | FileAttributes | ファイル属性（Archive含む） |
| CreationTime | DateTime | 作成日時 |
| LastAccessTime | DateTime | 最終アクセス日時 |

### 5.2 Remove-DbaBackup 出力

出力なし（ファイル削除のみ実行）。WhatIfで削除予定内容を表示。

## 6. 処理フロー

### 6.1 Find-DbaBackup 処理フロー

```
[開始]
    |
    v
[BackupFileExtensionバリデーション]
    | - ピリオドで始まる場合は警告
    v
[Pathの存在確認]
    | - 存在しない場合はStop-Function
    v
[RetentionPeriod解析]
    | - Convert-UserFriendlyRetentionToDatetime呼び出し
    | - 単位（h/d/w/m）と数値を分離
    | - 基準日時を計算
    v
[ファイル検索]
    | - Get-ChildItem -Recurse -Filter "*.$ext"
    | - Where-Object LastWriteTime -lt $RetentionDate
    v
[アーカイブビットフィルタ]
    | - CheckArchiveBit指定時はArchive属性なしのみ
    v
[ファイルオブジェクト出力]
    |
    v
[終了]
```

### 6.2 Remove-DbaBackup 処理フロー

```
[開始]
    |
    v
[BackupFileExtensionバリデーション]
    |
    v
[Find-DbaBackup呼び出し]
    | - 同一パラメータで検索実行
    v
[ファイル削除ループ]
    | - ShouldProcess確認
    | - Remove-Item -Force実行
    | - エラー時は警告出力して継続
    v
[空フォルダ削除（オプション）]
    | - RemoveEmptyBackupFolder指定時
    | - 深い階層から順にソート
    | - 空フォルダのみ削除
    v
[終了]
```

## 7. 内部実装詳細

### 7.1 保持期間変換関数

Find-DbaBackup内部で定義される `Convert-UserFriendlyRetentionToDatetime` 関数:

```powershell
# Find-DbaBackup.ps1 行94-136
function Convert-UserFriendlyRetentionToDatetime {
    # 入力例: "48h", "7d", "4w", "1m"
    # 出力: 現在日時からの相対DateTime

    $Value = $UserFriendlyRetention.Substring(0, $Length - 1)  # 数値部分
    $Units = $UserFriendlyRetention.Substring($Length - 1, 1)  # 単位

    switch ($Units) {
        'h' { (Get-Date).AddHours(-$Value) }
        'd' { (Get-Date).AddDays(-$Value) }
        'w' { (Get-Date).AddDays(-$Value * 7) }
        'm' { (Get-Date).AddMonths(-$Value) }
    }
}
```

### 7.2 アーカイブビットフィルタ

動的フィルタとして定義（行162-173）:

```powershell
if ($CheckArchiveBit) {
    filter DbaArchiveBitFilter {
        if ($_.Attributes -notmatch "Archive") { $_ }
    }
} else {
    filter DbaArchiveBitFilter { $_ }
}
```

### 7.3 ファイル列挙とストリーミング処理

大量ファイル対応のストリーミング処理（行174-178）:

```powershell
Get-ChildItem $Path -Filter "*.$BackupFileExtension" -File -Recurse |
    Where-Object LastWriteTime -lt $RetentionDate |
    DbaArchiveBitFilter
```

### 7.4 空フォルダ削除ロジック

深い階層から順に削除（Remove-DbaBackup.ps1 行120-148）:

```powershell
(Get-ChildItem -Directory -Path $Path -Recurse).FullName |
    Sort-Object -Descending |  # 深い階層から
    ForEach-Object {
        $Contents = @(Get-ChildItem -Force $_ -ErrorAction Stop)
        if ($Contents.Count -eq 0) { return $_ }
    } |
    ForEach-Object { Remove-Item $_ }
```

## 8. 使用例

### 8.1 トランザクションログの検索

```powershell
# 48時間以上経過したtrnファイルを検索
Find-DbaBackup -Path "C:\MSSQL\Backup\" -BackupFileExtension trn -RetentionPeriod 48h
```

### 8.2 フルバックアップの安全な削除

```powershell
# アーカイブ済みの7日以上経過したbakファイルを削除
Remove-DbaBackup -Path "C:\MSSQL\Backup\" -BackupFileExtension bak `
    -RetentionPeriod 7d -CheckArchiveBit
```

### 8.3 削除予定の確認（WhatIf）

```powershell
# 削除対象を確認（実際には削除しない）
Remove-DbaBackup -Path "C:\MSSQL\Backup\" -BackupFileExtension bak `
    -RetentionPeriod 7d -WhatIf
```

### 8.4 空フォルダも含めたクリーンアップ

```powershell
# ファイル削除後、空になったフォルダも削除
Remove-DbaBackup -Path "C:\MSSQL\Backup\" -BackupFileExtension bak `
    -RetentionPeriod 1w -RemoveEmptyBackupFolder
```

### 8.5 パイプラインによる削除

```powershell
# Find-DbaBackupの結果をパイプで削除
Find-DbaBackup -Path "\\SQL2014\Backup\" -BackupFileExtension bak `
    -RetentionPeriod 24h | Remove-Item -Verbose
```

## 9. エラーハンドリング

| エラー状況 | 処理 | ソース位置 |
|-----------|------|-----------|
| パスが存在しない | Stop-Function | Find-DbaBackup.ps1 行144-146 |
| 保持期間形式エラー | throw（単位不正） | Find-DbaBackup.ps1 行119-121 |
| 保持期間値エラー | throw（数値不正） | Find-DbaBackup.ps1 行124-126 |
| ファイル列挙エラー | Warning出力して継続 | Find-DbaBackup.ps1 行179-181 |
| ファイル削除エラー | Warning出力して継続 | Remove-DbaBackup.ps1 行113-115 |
| フォルダ列挙エラー | Warning出力して継続 | Remove-DbaBackup.ps1 行128-130 |
| フォルダ削除エラー | Warning出力して継続 | Remove-DbaBackup.ps1 行140-142 |

## 10. 関連コマンド

| コマンド | 関係 | 説明 |
|---------|------|------|
| Get-ChildItem | 内部使用 | ファイル・フォルダ列挙 |
| Remove-Item | 内部使用 | ファイル・フォルダ削除 |
| Backup-DbaDatabase | 関連 | バックアップ作成（このコマンドで作成されたファイルを管理） |
| Get-DbaDbBackupHistory | 関連 | MSDBからバックアップ履歴取得 |

## 11. 注意事項・制約

1. **ファイルシステム操作**: SQL Server接続は不要、純粋なファイルシステム操作
2. **LastWriteTimeベース**: ファイルの最終更新日時で経過判定（作成日時ではない）
3. **アーカイブビット**: Windows固有の属性。バックアップソフトがクリアする想定
4. **ネットワーク共有**: UNCパス対応（\\Server\Share\）
5. **権限**: ファイル削除には書き込み権限が必要
6. **大量ファイル**: ストリーミング処理によりメモリ効率的（#970対応）

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

### 12.1 関連ファイル一覧

| ファイル | 種類 | 行数 | 説明 |
|---------|------|------|------|
| public/Find-DbaBackup.ps1 | メインコマンド | 183 | バックアップファイル検索 |
| public/Remove-DbaBackup.ps1 | メインコマンド | 151 | バックアップファイル削除 |

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

```
Find-DbaBackup
    |
    +-- Convert-UserFriendlyRetentionToDatetime (内部関数, 行94-136)
    |       |
    |       +-- Get-Date (現在日時取得)
    |       +-- AddHours/AddDays/AddMonths (日時計算)
    |
    +-- Test-Path (パス検証, 行144)
    +-- Get-ChildItem (ファイル列挙, 行177)
    +-- DbaArchiveBitFilter (動的フィルタ, 行164-172)
    +-- Write-Message (ログ出力)

Remove-DbaBackup
    |
    +-- Find-DbaBackup (ファイル検索, 行107)
    +-- Remove-Item (ファイル削除, 行112)
    +-- Get-ChildItem (フォルダ列挙, 行122)
    +-- Remove-Item (フォルダ削除, 行139)
    +-- Write-Message (ログ出力)
```

### 12.3 データフロー図

```
[ユーザー入力]
    |
    | Path, BackupFileExtension, RetentionPeriod
    v
[Find-DbaBackup]
    |
    | RetentionPeriod解析
    v
[Convert-UserFriendlyRetentionToDatetime]
    |
    | "7d" -> (Get-Date).AddDays(-7) -> 基準日時
    v
[Get-ChildItem -Recurse]
    |
    | *.{extension} ファイル一覧
    v
[Where-Object LastWriteTime -lt $RetentionDate]
    |
    | 経過時間フィルタ
    v
[DbaArchiveBitFilter]
    |
    | Archive属性フィルタ（オプション）
    v
[System.IO.FileInfo出力] --> パイプライン --> [Remove-DbaBackup/Remove-Item]
                                                    |
                                                    v
                                              [ファイル削除]
                                                    |
                                                    v
                                              [空フォルダ削除（オプション）]
```

### 12.4 読み解きの流れ

1. **Find-DbaBackup.ps1 begin ブロック (行92-148)**
   - Convert-UserFriendlyRetentionToDatetime関数定義
   - パラメータバリデーション

2. **Find-DbaBackup.ps1 process ブロック (行149-182)**
   - 保持期間の日時変換
   - DbaArchiveBitFilter動的定義
   - Get-ChildItemによるストリーミング検索

3. **Remove-DbaBackup.ps1 process ブロック (行104-150)**
   - Find-DbaBackupのパイプライン呼び出し
   - ShouldProcessによる確認付き削除
   - 空フォルダの深さ順削除

## 13. 改訂履歴

| 日付 | バージョン | 変更内容 |
|------|-----------|---------|
| 2026-02-18 | 1.0 | 初版作成 |
