# 画面設計書 19-データベースバックアップ

## 概要

本ドキュメントは、SQL Server データベースのバックアップ機能を提供するコマンド群の設計仕様を記述したものです。

### 本画面の処理概要

本機能は、SQL Server データベースのフル・差分・トランザクションログバックアップを柔軟な出力先オプションとエンタープライズ機能で実行します。ローカルファイルシステム、Azure Blob Storage、S3互換オブジェクトストレージへのバックアップをサポートします。

**業務上の目的・背景**：SQL Server データベースの定期バックアップと災害復旧準備が必要です。T-SQL BACKUP コマンドを手動で実行する代わりに、PowerShellで一元的にバックアップを管理できます。圧縮、暗号化、ストライピングなどの高度な機能をパラメータで簡単に指定できます。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Backup-DbaDatabase` - データベースバックアップの実行
- `Measure-DbaBackupThroughput` - バックアップスループットの測定

**主要な操作・処理内容**：
1. フル・差分・ログバックアップの実行
2. Azure Blob Storage/S3へのクラウドバックアップ
3. バックアップの圧縮・暗号化
4. 複数ファイルへのストライピング
5. バックアップの検証（RESTORE VERIFYONLY）

**画面遷移**：本機能はCLIコマンドです。

**権限による表示制御**：データベースへのBACKUP DATABASE権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 27 | Backup-DbaDatabase | 主機能 | データベースバックアップの実行 |
| 41 | Measure-DbaBackupThroughput | 補助機能 | バックアップスループットの測定 |

## 画面種別

操作 / 実行

## URL/ルーティング

PowerShell コマンドとして提供（CLIベース）

## 入出力項目

### Backup-DbaDatabase パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | No | バックアップ対象データベース |
| ExcludeDatabase | object[] | No | 除外するデータベース |
| Path | string[] | No | バックアップファイルのディレクトリパス |
| FilePath | string | No | 完全なバックアップファイル名 |
| Type | string | No | バックアップ種別（Full, Log, Differential） |
| CopyOnly | switch | No | コピーオンリーバックアップ |
| FileCount | int | No | ストライプファイル数 |
| CompressBackup | switch | No | バックアップ圧縮の有効化 |
| Checksum | switch | No | チェックサム計算の有効化 |
| Verify | switch | No | バックアップ後のVERIFYONLY実行 |
| MaxTransferSize | int | No | 転送単位サイズ（64KBの倍数） |
| BlockSize | int | No | 物理ブロックサイズ |
| BufferCount | int | No | I/Oバッファ数 |
| StorageBaseUrl | string[] | No | Azure/S3ストレージURL |
| StorageCredential | string | No | ストレージ認証情報名 |
| StorageRegion | string | No | S3リージョン |
| NoRecovery | switch | No | ログバックアップ時のNORECOVERY |
| BuildPath | switch | No | パスの自動作成 |
| WithFormat | switch | No | メディアのフォーマット |
| Initialize | switch | No | 既存バックアップセットの上書き |
| EncryptionAlgorithm | string | No | 暗号化アルゴリズム（AES128/192/256, TRIPLEDES） |
| EncryptionCertificate | string | No | 暗号化証明書名 |
| Description | string | No | バックアップセットの説明 |
| OutputScriptOnly | switch | No | T-SQLスクリプトのみ出力 |
| EnableException | switch | No | 例外を有効化 |

### Measure-DbaBackupThroughput パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | No | 分析対象データベース |
| ExcludeDatabase | object[] | No | 除外するデータベース |
| Type | string | No | バックアップ種別（Full, Log, Differential等） |
| Since | datetime | No | 指定日以降のバックアップのみ |
| Last | switch | No | 最新のバックアップのみ |
| DeviceType | string[] | No | デバイス種別でフィルタ |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Backup-DbaDatabase 出力

| 項目名 | 説明 |
|--------|------|
| SqlInstance | 完全なSQL Serverインスタンス名 |
| Database | データベース名 |
| Type | バックアップ種別（Full, Differential, Log） |
| TotalSize | バックアップサイズ（バイト） |
| DeviceType | バックアップ先デバイス種別 |
| Duration | バックアップ所要時間 |
| ComputerName | コンピュータ名 |
| InstanceName | インスタンス名 |
| DatabaseId | データベースID |
| UserName | 実行ユーザー |
| Start | 開始日時 |
| End | 終了日時 |
| Path | バックアップファイルパス配列 |
| CompressedBackupSize | 圧縮後サイズ |
| CompressionRatio | 圧縮率 |
| BackupSetId | バックアップセットID |
| FirstLsn | 最初のLSN |
| LastLsn | 最後のLSN |
| IsCopyOnly | コピーオンリーかどうか |
| RecoveryModel | 復旧モデル |
| EncryptorType | 暗号化種別 |
| KeyAlgorithm | 暗号化アルゴリズム |
| BackupComplete | バックアップ完了フラグ |
| BackupFile | バックアップファイル名 |
| Script | 実行されたT-SQL |

### Measure-DbaBackupThroughput 出力

| 項目名 | 説明 |
|--------|------|
| ComputerName | コンピュータ名 |
| InstanceName | インスタンス名 |
| SqlInstance | 完全なSQL Serverインスタンス名 |
| Database | データベース名 |
| AvgThroughput | 平均スループット（MB/秒） |
| AvgSize | 平均バックアップサイズ |
| AvgDuration | 平均所要時間 |
| MinThroughput | 最小スループット |
| MaxThroughput | 最大スループット |
| MinBackupDate | 最古のバックアップ日時 |
| MaxBackupDate | 最新のバックアップ日時 |
| BackupCount | バックアップ件数 |

## イベント仕様

### 1-データベースバックアップ実行

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. データベースフィルタ（Database, ExcludeDatabase）を適用
3. 暗号化オプションの検証（証明書/キーの存在確認）
4. バックアップパスの設定と検証
5. SMO Backupオブジェクトを構成
   - バックアップ種別（Full/Diff/Log）の設定
   - 圧縮オプションの設定
   - 暗号化オプションの設定
6. バックアップデバイスの追加
7. `SqlBackup()` でバックアップ実行
8. `-Verify` 指定時は `RESTORE VERIFYONLY` で検証
9. バックアップ履歴情報を取得して出力

### 2-S3バックアップ（SQL Server 2022+）

**処理フロー**:
1. S3 URLの検出（`s3://` プレフィックス）
2. SQL Server バージョン確認（2022以上必須）
3. MaxTransferSize の検証（5MB-20MB）
4. StorageRegion 指定時は BACKUP_OPTIONS パラメータを追加
5. バックアップスクリプトを生成してT-SQL実行

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Backup-DbaDatabase | msdb.dbo.backupset等 | INSERT | バックアップ履歴の記録 |
| Backup-DbaDatabase | ファイルシステム/クラウド | WRITE | バックアップファイルの書き込み |
| Measure-DbaBackupThroughput | msdb.dbo.backupset | SELECT | バックアップ履歴の分析 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| Error | 接続失敗 | "Failure" (ConnectionError) |
| Error | tempdbのバックアップ試行 | "Backing up tempdb not supported" |
| Error | アクセス不可データベース | "Database $dbName is not accessible. Cannot perform backup." |
| Error | Simple復旧モデルでログバックアップ | "$db is in simple recovery mode, cannot take log backup" |
| Error | フルバックアップなしで差分/ログバックアップ | "$db does not have an existing full backup..." |
| Error | S3でSQL 2022未満 | "S3 backup requires SQL Server 2022 or later" |
| Error | S3のMaxTransferSize範囲外 | "MaxTransferSize for S3 backups must be... between 5MB and 20MB" |
| Error | CreateFolderとクラウドストレージ | "CreateFolder cannot be specified with a cloud storage backup" |
| Warning | 圧縮非対応エディション | "Compression is not supported with this version/edition" |
| Warning | Azure page blobでBlockSize指定 | "BlockSize cannot be specified when backing up to an Azure page blob" |

## 備考

- SQL Server 2008+ Enterprise/Standard で圧縮をサポート
- SQL Server 2022+ で S3互換ストレージをサポート
- Azure Blob Storage へのバックアップは SAS トークンまたはアクセスキーで認証
- TDE暗号化データベースの圧縮には MaxTransferSize > 64KB が必要
- FilePath に 'NUL' を指定するとバックアップを破棄（テスト用）
- OutputScriptOnly でT-SQLを確認可能

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | 196-244行: .OUTPUTS セクションでBackupHistoryオブジェクト構造を確認 |
| 1-2 | Measure-DbaBackupThroughput.ps1 | `public/Measure-DbaBackupThroughput.ps1` | 64-84行: .OUTPUTS セクションでスループット統計オブジェクト構造を確認 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | 317-364行: パラメータ定義、多数のバックアップオプション |
| 2-2 | Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | 380-396行: S3バックアップの検出と検証 |

**主要処理フロー**:
- **403-409行**: Connect-DbaInstance で接続確立
- **522-555行**: 暗号化オプションの検証と設定
- **589-673行**: クラウドストレージ（Azure/S3）の処理
- **736-737行**: SMO Backupオブジェクトの作成と設定
- **746-783行**: 圧縮オプションの処理
- **921-939行**: バックアップデバイスの追加
- **962-976行**: バックアップ実行とスクリプト生成
- **989-1023行**: 検証（Verify）処理

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

```
Backup-DbaDatabase
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- [暗号化指定時]
    |       +-- Get-DbaDbCertificate (証明書確認)
    |       +-- BackupEncryptionOptions 設定
    |
    +-- パス設定
    |       +-- [パス未指定時] Get-DbaDefaultPath
    |       +-- [ストレージURL時] 資格情報確認
    |
    +-- データベースごとの処理
    |       |
    |       +-- 前提条件チェック
    |       |       +-- tempdb除外
    |       |       +-- IsAccessible確認
    |       |       +-- Status = Normal確認
    |       |       +-- スナップショット除外
    |       |       +-- Simple復旧モデルでのログバックアップ拒否
    |       |
    |       +-- SMO Backupオブジェクト構成
    |       |       +-- Action (Database/Log)
    |       |       +-- Incremental (差分)
    |       |       +-- CompressionOption
    |       |       +-- EncryptionOption
    |       |       +-- CopyOnly
    |       |       +-- NoRecovery
    |       |
    |       +-- バックアップファイル名生成
    |       |       +-- ReplaceInName (トークン置換)
    |       |       +-- CreateFolder (サブディレクトリ)
    |       |       +-- ストライプ (FileCount)
    |       |
    |       +-- パス検証
    |       |       +-- Test-DbaPath
    |       |       +-- [BuildPath時] New-DbaDirectory
    |       |
    |       +-- デバイス追加
    |       |       +-- DeviceType (File/URL)
    |       |       +-- BackupDeviceItem
    |       |
    |       +-- [S3 + Region]
    |       |       +-- BACKUP_OPTIONS 追加
    |       |       +-- ExecuteNonQuery でT-SQL実行
    |       |
    |       +-- [通常]
    |       |       +-- SqlBackup() 実行
    |       |
    |       +-- [Verify時]
    |               +-- Restore-DbaDatabase -VerifyOnly
    |
    +-- バックアップ履歴取得
    |       +-- Get-DbaDbBackupHistory
    |
    +-- 出力オブジェクト構築
```

### データフロー図

```
                    ┌─────────────────────────────────────┐
                    │         SQL Server Instance         │
                    └─────────────────────────────────────┘
                                      │
            ┌─────────────────────────┼─────────────────────────┐
            │                         │                         │
       Database                   msdb                    Storage
            │                         │                         │
            ▼                         ▼                         ▼
    ┌───────────────┐         ┌─────────────┐         ┌─────────────┐
    │ Data/Log      │         │ backupset   │         │ Disk/URL    │
    │ Files         │         │ backupmedia │         │ Backup File │
    └───────────────┘         └─────────────┘         └─────────────┘
            │                         │                         │
            └─────────────────────────┼─────────────────────────┘
                                      │
                                      ▼
                        ┌─────────────────────────┐
                        │   Backup-DbaDatabase    │
                        │  - バックアップ実行      │
                        │  - 履歴記録             │
                        │  - 検証                 │
                        └─────────────────────────┘
                                      │
                                      ▼
                        ┌─────────────────────────┐
                        │  BackupHistory Object   │
                        │  + ファイル情報         │
                        │  + LSN情報             │
                        └─────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | ソース | データベースバックアップメインコマンド |
| Measure-DbaBackupThroughput.ps1 | `public/Measure-DbaBackupThroughput.ps1` | ソース | バックアップスループット分析コマンド |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得（内部使用） |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス検証（内部使用） |
| New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | ソース | ディレクトリ作成（内部使用） |
