# 機能設計書 27-Backup-DbaDatabase

## 概要

本ドキュメントは、SQL Serverデータベースのバックアップを作成するBackup-DbaDatabase機能の設計仕様を記述する。

### 本機能の処理概要

Backup-DbaDatabaseは、SQL Serverデータベースのフル、差分、またはトランザクションログバックアップを作成するPowerShellコマンドレットである。ローカルファイルシステム、Azure Blob Storage、S3互換ストレージへのバックアップをサポートする。

**業務上の目的・背景**：SQL Serverデータベースの定期バックアップは、データ保護と災害復旧の基盤である。本機能は、T-SQLのBACKUP DATABASEコマンドをPowerShellから簡単に実行可能にし、圧縮、暗号化、ストライピング等のエンタープライズバックアップ機能をサポートする。Azure Blob StorageやS3互換ストレージへの直接バックアップにより、クラウドネイティブな運用も可能になる。

**機能の利用シーン**：
- 定期的なフルバックアップ/差分バックアップ/ログバックアップの実行
- サーバー移行前のアドホックバックアップ
- 災害復旧テスト用のバックアップ作成
- Azure/S3へのクラウドバックアップ
- 暗号化バックアップによるセキュアなバックアップ作成

**主要な処理内容**：
1. SqlInstanceまたはInputObjectパラメータから対象データベースを特定
2. バックアップパス、ファイル名、オプションの設定
3. SMOのBackupオブジェクトを構築し各種プロパティを設定
4. SqlBackup()メソッドまたはT-SQL実行でバックアップを実行
5. バックアップ履歴から結果情報を取得して返却

**関連システム・外部連携**：
- SQL Server Management Objects (SMO) のBackupクラス
- Azure Blob Storage（StorageBaseUrl + StorageCredential）
- S3互換ストレージ（SQL Server 2022以降）

**権限による制御**：BACKUP DATABASE権限またはdb_backupoperatorロールメンバーシップが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | データベースバックアップ | 主機能 | データベースバックアップの実行 |

## 機能種別

バックアップ操作（データベースバックアップ）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | No | 対象SQL Serverインスタンス | ParameterSet "Pipe" |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| Database | object[] | No | 対象データベース名 | - |
| ExcludeDatabase | object[] | No | 除外データベース名 | - |
| Path | string[] | No | バックアップ出力ディレクトリ | 複数指定でストライピング |
| FilePath | string | No | 完全なバックアップファイル名 | 単一DB用 |
| Type | string | No | バックアップ種別（デフォルト：Database） | Full/Log/Differential/Diff/Database |
| FileCount | int | No | ストライプファイル数 | デフォルト：0 |
| CompressBackup | switch | No | バックアップ圧縮を有効化 | - |
| Checksum | switch | No | チェックサム計算を有効化 | - |
| Verify | switch | No | バックアップ検証を実行 | - |
| MaxTransferSize | int | No | 転送単位サイズ | 64KBの倍数、最大4MB（S3は5-20MB） |
| BlockSize | int | No | ブロックサイズ | 0.5-64KB |
| BufferCount | int | No | I/Oバッファ数 | - |
| CopyOnly | switch | No | コピーのみバックアップ | - |
| StorageBaseUrl | string[] | No | クラウドストレージURL | Azure/S3 |
| StorageCredential | string | No | クラウドストレージ認証情報名 | - |
| StorageRegion | string | No | S3リージョン | S3のみ |
| EncryptionAlgorithm | string | No | 暗号化アルゴリズム | AES128/AES192/AES256/TRIPLEDES |
| EncryptionCertificate | string | No | 暗号化証明書名 | masterデータベース内 |
| NoRecovery | switch | No | ログバックアップでNORECOVERY | Type=Log時のみ |
| CreateFolder | switch | No | DB別フォルダ作成 | - |
| WithFormat | switch | No | メディアフォーマット | - |
| Initialize | switch | No | 既存バックアップセット上書き | - |
| OutputScriptOnly | switch | No | T-SQLスクリプトのみ出力 | - |
| Description | string | No | バックアップセット説明 | 最大255文字 |
| InputObject | object[] | No | パイプラインからのDBオブジェクト | ParameterSet "NoPipe" |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- SqlInstanceパラメータ：SQL Serverインスタンス名の直接指定
- InputObjectパラメータ：Get-DbaDatabaseからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | SQL Serverインスタンス名 |
| Database | string | データベース名 |
| Type | string | バックアップ種別 |
| TotalSize | long | バックアップサイズ（バイト） |
| DeviceType | string | デバイス種別 |
| Duration | TimeSpan | バックアップ所要時間 |
| Start | DateTime | バックアップ開始日時 |
| End | DateTime | バックアップ終了日時 |
| Path | string[] | バックアップファイルパス |
| BackupComplete | bool | バックアップ完了フラグ |
| Verified | bool | 検証結果（Verify使用時） |
| Script | string | 実行されたT-SQLスクリプト |

### 出力先

- PowerShellパイプライン（Dataplat.Dbatools.Database.BackupHistoryオブジェクト）
- OutputScriptOnly時はT-SQL文字列

## 処理フロー

### 処理シーケンス

```
1. 初期化・パラメータ検証
   └─ タイムスタンプフォーマット、クラウドストレージ設定の検証
2. データベース取得
   └─ SqlInstanceから対象DBを取得、tempdb除外
3. 各DBに対するバックアップ処理
   ├─ パス・ファイル名決定
   ├─ 圧縮・暗号化設定
   ├─ SMO Backupオブジェクト構築
   ├─ バックアップデバイス追加
   └─ SqlBackup()またはT-SQL実行
4. 結果取得
   └─ Get-DbaDbBackupHistoryで履歴取得
5. 検証（オプション）
   └─ Restore-DbaDatabase -VerifyOnlyで検証
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ検証]
    B --> C{クラウドストレージ?}
    C -->|Yes| D[クラウド設定検証]
    C -->|No| E[ローカルパス設定]
    D --> F[データベース取得]
    E --> F
    F --> G[foreach db in InputObject]
    G --> H{tempdb?}
    H -->|Yes| I[スキップ]
    H -->|No| J{アクセス可能?}
    J -->|No| K[エラー出力]
    J -->|Yes| L[バックアップパス決定]
    L --> M[SMO Backupオブジェクト構築]
    M --> N{暗号化?}
    N -->|Yes| O[暗号化オプション設定]
    N -->|No| P[圧縮設定]
    O --> P
    P --> Q[デバイス追加]
    Q --> R{OutputScriptOnly?}
    R -->|Yes| S[スクリプト出力]
    R -->|No| T[SqlBackup実行]
    T --> U{成功?}
    U -->|Yes| V[履歴取得]
    U -->|No| W[エラー処理]
    V --> X{Verify?}
    X -->|Yes| Y[検証実行]
    X -->|No| Z[結果出力]
    Y --> Z
    I --> AA{次のDB?}
    K --> AA
    S --> AA
    W --> AA
    Z --> AA
    AA -->|Yes| G
    AA -->|No| AB[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | tempdb除外 | tempdbはバックアップ不可 | 常時 |
| BR-02 | 単純復旧モデル制限 | 単純復旧モデルDBはログバックアップ不可 | Type=Log時 |
| BR-03 | フルバックアップ必須 | 差分/ログバックアップはフルバックアップ後のみ可能 | Type=Diff/Log時 |
| BR-04 | S3バージョン制限 | S3バックアップはSQL Server 2022以降のみ | StorageBaseUrl=s3://時 |
| BR-05 | Azure認証情報 | Azure使用時は認証情報またはSAS認証が必要 | StorageBaseUrl=https://時 |
| BR-06 | TDE圧縮制限 | TDE有効DBの圧縮はSQL 2016 CU4以降 | CompressBackup+TDE時 |
| BR-07 | MaxTransferSize自動設定 | TDE+圧縮時は128KBに自動設定 | TDE+CompressBackup時 |

### 計算ロジック

#### ファイル名生成
- 自動生成：`{DatabaseName}_{yyyyMMddHHmm}.{suffix}`
- suffix: bak（Full/Diff）、trn（Log）

#### ストライプファイル名
- 複数ファイル時：`{basename}-{n}-of-{FileCount}.{suffix}`

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| BACKUP DATABASE | 対象DB | READ | データ読み取り |
| msdb.dbo.backupset | msdb | INSERT | バックアップ履歴登録 |
| msdb.dbo.backupmediafamily | msdb | INSERT | メディア情報登録 |

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

#### msdb.dbo.backupset

バックアップ完了時に自動的にバックアップメタデータが記録される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | CreateFolderとクラウドストレージ併用 | Stop-Function |
| - | バージョンエラー | S3で非SQL 2022 | Stop-Function |
| - | 認証エラー | 認証情報なしでクラウドバックアップ | Stop-Function |
| - | パスエラー | 出力先アクセス不可 | Stop-Function |
| - | 復旧モデルエラー | 単純復旧でログバックアップ | Stop-Function |
| - | 事前条件エラー | フルバックアップなしで差分/ログ | Stop-Function |

### リトライ仕様

リトライ機能は実装されていない。エラー発生時は次のデータベースの処理を継続する。

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

バックアップはSQL Server内部でトランザクション整合性を保証。各DBバックアップは独立して実行される。

## パフォーマンス要件

- バックアップスループットはストレージ性能に依存
- ストライピング（FileCount > 1）でスループット向上
- 圧縮有効化でサイズ削減（CPU使用率増加）
- 進捗表示（Write-Progress）による状態可視化

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

- SQL Server認証、Windows認証、AD認証をサポート
- 暗号化バックアップでデータ保護（AES256推奨）
- クラウドストレージ認証情報の安全な管理が必要
- 秘密情報のログ出力防止

## 備考

- SQL Server 2000以降をサポート（機能によりバージョン制限あり）
- NULデバイスへのバックアップでテスト可能
- プログレスバー表示で進捗確認可能

---

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

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

### 推奨読解順序

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

SMOのBackupクラスとBackupHistoryクラスが中心的なデータ構造である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | パラメータ定義（317-364行目）を確認 |

**読解のコツ**: ParameterSetNameでPipeとNoPipeを使い分けている点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | begin ブロック（366-461行目）で初期化処理 |
| 2-2 | Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | process ブロック（463-1079行目）がメイン処理 |

**主要処理フロー**:
1. **403-448行目**: クラウドストレージ設定検証
2. **522-555行目**: 暗号化オプション設定
3. **736-759行目**: SMO Backupオブジェクト構築
4. **962-1053行目**: SqlBackup実行と結果取得

#### Step 3: クラウドストレージ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | StorageBaseUrl処理（589-674行目） |

**主要処理フロー**:
- **591-599行目**: S3/Azureの判定
- **593-619行目**: S3バックアップのバージョンチェックとMaxTransferSize設定
- **635-671行目**: 認証情報の検証

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

```
Backup-DbaDatabase
    │
    ├─ Connect-DbaInstance (接続)
    │
    ├─ Get-DbaDatabase (DB取得、内部呼び出し)
    │
    ├─ Get-DbaDefaultPath (デフォルトパス取得)
    │
    ├─ Get-DbaDbCertificate (暗号化証明書確認)
    │
    ├─ New-DbaDirectory (パス作成)
    │
    ├─ Test-DbaPath (パス検証)
    │
    ├─ SMO Backup.SqlBackup() (バックアップ実行)
    │
    ├─ Get-DbaDbBackupHistory (履歴取得)
    │
    └─ Restore-DbaDatabase -VerifyOnly (検証、オプション)
```

### データフロー図

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

SqlInstance ───────────┐
                       │
Database ──────────────┼──▶ SMO Backup構築 ──────────▶ SqlBackup()
                       │         │                         │
Path/FilePath ─────────┤         │                         ▼
                       │         │                    ディスク/クラウド
Type ──────────────────┤         │                    バックアップファイル
                       │         │                         │
CompressBackup ────────┤         │                         ▼
                       │         │
EncryptionAlgorithm ───┤         └──▶ Get-DbaDbBackupHistory
                       │                      │
StorageBaseUrl ────────┘                      ▼

                                         BackupHistory[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | ソース | メイン機能実装 |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | リストア機能 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得 |
| Test-DbaLastBackup.ps1 | `public/Test-DbaLastBackup.ps1` | ソース | バックアップテスト |
