# 画面設計書 20-データベースリストア

## 概要

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

### 本画面の処理概要

本機能は、SQL Server データベースをバックアップファイルからリストアします。インテリジェントなバックアップチェーン選択とポイントインタイムリカバリをサポートし、フル・差分・トランザクションログバックアップから最適なリストアシーケンスを自動的に選択します。

**業務上の目的・背景**：データベースの災害復旧、テスト環境の構築、データベースの移行に使用されます。T-SQL RESTORE コマンドを手動で実行する代わりに、複雑なバックアップチェーンの構築を自動化し、PowerShellで効率的にリストアを実行できます。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Restore-DbaDatabase` - データベースリストアの実行
- `Invoke-DbaAdvancedRestore` - 高度なリストア操作

**主要な操作・処理内容**：
1. バックアップファイルのスキャンとチェーン構築
2. ポイントインタイムリカバリ
3. 異なるファイルパスへのリストア
4. Azure Blob Storage/S3からのリストア
5. ページリストア（Enterprise Edition）
6. スタンバイモードでのリストア

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

**権限による表示制御**：データベースへのALTER DATABASE権限が必要です。新規データベースの場合はCREATE DATABASE権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 45 | Restore-DbaDatabase | 主機能 | データベースのリストア実行 |
| 40 | Invoke-DbaAdvancedRestore | 補助機能 | 高度なリストア操作 |

## 画面種別

操作 / 実行

## URL/ルーティング

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

## 入出力項目

### Restore-DbaDatabase パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Path | object[] | Yes | バックアップファイルのパス（ローカル/UNC/URL） |
| DatabaseName | object[] | No | リストア先データベース名 |
| DestinationDataDirectory | string | No | データファイルのリストア先ディレクトリ |
| DestinationLogDirectory | string | No | ログファイルのリストア先ディレクトリ |
| DestinationFileStreamDirectory | string | No | FILESTREAMデータのリストア先 |
| RestoreTime | datetime | No | ポイントインタイムリカバリの対象日時 |
| NoRecovery | switch | No | リストア後にデータベースをRESTORING状態に |
| WithReplace | switch | No | 既存データベースの上書き |
| XpDirTree | switch | No | xp_dirtreeによるファイル検索 |
| OutputScriptOnly | switch | No | T-SQLスクリプトのみ出力 |
| VerifyOnly | switch | No | バックアップファイルの検証のみ |
| MaintenanceSolutionBackup | switch | No | Ola Hallengren形式のフォルダ構造 |
| FileMapping | hashtable | No | ファイル配置のカスタムマッピング |
| IgnoreLogBackup | switch | No | ログバックアップを除外 |
| IgnoreDiffBackup | switch | No | 差分バックアップを除外 |
| UseDestinationDefaultDirectories | switch | No | インスタンスのデフォルトディレクトリを使用 |
| ReuseSourceFolderStructure | switch | No | 元のフォルダ構造を維持 |
| DestinationFilePrefix | string | No | ファイル名のプレフィックス |
| DestinationFileSuffix | string | No | ファイル名のサフィックス |
| RestoredDatabaseNamePrefix | string | No | データベース名のプレフィックス |
| TrustDbBackupHistory | switch | No | バックアップ履歴を信頼（ヘッダー検証スキップ） |
| MaxTransferSize | int | No | 転送単位サイズ |
| BlockSize | int | No | ブロックサイズ |
| BufferCount | int | No | バッファ数 |
| Continue | switch | No | 既存のリストアチェーンを継続 |
| StandbyDirectory | string | No | スタンバイモード用のUNDOファイルディレクトリ |
| StorageCredential | string | No | Azure/S3ストレージ認証情報名 |
| ReplaceDbNameInFile | switch | No | ファイル名のDB名を置換 |
| Recover | switch | No | RESTORING状態のDBをオンラインに |
| KeepCDC | switch | No | CDC設定を維持 |
| KeepReplication | switch | No | レプリケーション設定を維持 |
| PageRestore | object | No | ページリストア対象 |
| PageRestoreTailFolder | string | No | ページリストア用テールログの保存先 |
| StopMark | string | No | 停止するトランザクションマーク |
| StopBefore | switch | No | マーク前で停止 |
| StopAfterDate | datetime | No | 指定日時以降の最初のマークで停止 |
| Checksum | switch | No | チェックサム検証を強制 |
| Restart | switch | No | 中断されたリストアを再開 |
| StatementTimeout | int | No | ステートメントタイムアウト（分） |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Restore-DbaDatabase 出力（-Recover時）

| 項目名 | 説明 |
|--------|------|
| SqlInstance | SQL Serverインスタンス名 |
| DatabaseName | データベース名 |
| RestoreComplete | リカバリ成功フラグ |
| Scripts | 実行されたT-SQLスクリプト |

### Restore-DbaDatabase 出力（-OutputScriptOnly時）

T-SQL RESTORE ステートメントの文字列を返す。

### 標準リストア操作

Invoke-DbaAdvancedRestore に委譲され、詳細なリストア結果が出力される。

## イベント仕様

### 1-データベースリストア実行

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. パラメータの検証（相互排他チェック等）
3. `-TrustDbBackupHistory` の場合はヘッダー検証をスキップ
4. それ以外は `Get-DbaBackupInformation` でバックアップ情報を取得
5. `Format-DbaBackupInformation` でファイルパスを設定
6. `Select-DbaBackupInformation` でリストア対象を選択
7. `Test-DbaBackupInformation` でリストア可能性を検証
8. `Invoke-DbaAdvancedRestore` で実際のリストアを実行

### 2-ポイントインタイムリカバリ

**処理フロー**:
1. `-RestoreTime` パラメータで対象日時を指定
2. バックアップチェーンを分析して必要なバックアップを特定
3. フルバックアップ → 差分バックアップ → トランザクションログの順でリストア
4. 最終ログを `STOPAT` オプション付きでリストア

### 3-データベースリカバリ

**処理フロー**:
1. `-Recover` パラメータでリカバリモードを指定
2. RESTORING状態のデータベースを確認
3. `RESTORE DATABASE [name] WITH RECOVERY` を実行
4. データベースをオンライン状態に

### 4-S3からのリストア（SQL Server 2022+）

**処理フロー**:
1. S3 URLの検出（`s3://` プレフィックス）
2. SQL Server バージョン確認（2022以上必須）
3. 資格情報の検証
4. リストア実行

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Restore-DbaDatabase | ファイルシステム | WRITE | データベースファイルの復元 |
| Restore-DbaDatabase | msdb.dbo.restorehistory | INSERT | リストア履歴の記録 |
| Restore-DbaDatabase (Recover) | sys.databases | UPDATE | データベース状態の更新 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| Error | 接続失敗 | "Failure" (ConnectionError) |
| Error | FileMapping/ReuseSourceFolderStructure/DestinationDataDirectory併用 | "You've specified incompatible Location parameters" |
| Error | ReplaceDbNameInFile指定時にDatabaseName未指定 | "To use ReplaceDbNameInFile you must specify DatabaseName" |
| Error | DestinationLogDirectoryのみ指定 | "...can only be specified together with DestinationDataDirectory" |
| Error | OutputScriptOnlyとVerifyOnly併用 | "...cannot both be specified at the same time" |
| Error | ExecuteAsログイン不存在 | "...the login '$ExecuteAs' does not exist" |
| Error | KeepCDCとNoRecovery/Standby併用 | "KeepCDC cannot be specified with Norecovery or Standby" |
| Error | URL資格情報なし | "A URL to a backup has been passed in, but no credential can be found" |
| Error | MaxTransferSize範囲外 | "MaxTransferSize value must be a multiple of 64kb and no greater than 4MB" |
| Error | BlockSize不正値 | "Block size must be one of 0.5kb,1kb,2kb,4kb,8kb,16kb,32kb,64kb" |
| Warning | バックアップなし | "No backups passed through..." |
| Warning | Recoveryモードでデータベース不存在 | "$Database does not exist on $RestoreInstance" |
| Warning | Recoveryモードで状態不正 | "...state [$(...)] is not a valid state" |

## 備考

- バックアップチェーンを自動的に構築（フル→差分→ログの最適順序）
- Ola Hallengren のメンテナンスソリューションのフォルダ構造をサポート
- SQL Server 2000からのリストアには TrustDbBackupHistory を使用
- ページリストアは Enterprise Edition でオンライン、Standard Edition でオフライン
- Azure Blob Storage/S3からのリストアをサポート（SQL Server 2022+ for S3）
- 継続的なログリストアには `-Continue` を使用

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | 275-296行: .OUTPUTS セクションで出力オブジェクト構造を確認 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | 447-504行: パラメータ定義、多数のリストアオプション |
| 2-2 | Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | 509-614行: パラメータ検証ロジック |

**主要処理フロー**:
- **510-515行**: Connect-DbaInstance で接続確立
- **517-527行**: Managed Instance の制限チェック
- **529-606行**: パラメータの相互排他チェック
- **632-648行**: SQL Server 2000 対応処理
- **649-717行**: バックアップ履歴の収集
- **776-804行**: バックアップ情報のフォーマット
- **814-823行**: バックアップ情報の選択
- **833-847行**: バックアップ情報のテスト
- **874-902行**: Invoke-DbaAdvancedRestore でリストア実行
- **725-766行**: Recover モードの処理

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

```
Restore-DbaDatabase
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- パラメータ検証
    |       +-- 相互排他チェック
    |       +-- Managed Instance制限チェック
    |       +-- 資格情報検証
    |
    +-- [ParameterSetName = "Recovery"]
    |       +-- データベース状態確認
    |       +-- RESTORE DATABASE WITH RECOVERY 実行
    |       +-- 結果オブジェクト出力
    |
    +-- [ParameterSetName = "Restore"]
    |       |
    |       +-- [TrustDbBackupHistory]
    |       |       +-- パイプライン入力をそのまま使用
    |       |
    |       +-- [通常]
    |       |       +-- Get-DbaBackupInformation
    |       |               +-- バックアップヘッダー読み取り
    |       |               +-- バックアップチェーン構築
    |       |
    |       +-- Format-DbaBackupInformation
    |       |       +-- ファイルパス設定
    |       |       +-- DB名置換
    |       |
    |       +-- Select-DbaBackupInformation
    |       |       +-- RestoreTime に基づく選択
    |       |       +-- 差分/ログのフィルタ
    |       |
    |       +-- Test-DbaBackupInformation
    |       |       +-- リストア可能性検証
    |       |       +-- パス存在確認
    |       |
    |       +-- Invoke-DbaAdvancedRestore
    |               +-- RESTORE DATABASE 実行
    |               +-- [NoRecovery] RESTORING状態で停止
    |               +-- [StandbyDirectory] スタンバイモード
    |
    +-- [ParameterSetName = "RestorePage"]
            +-- ページリストア処理
            +-- テールログバックアップ
            +-- ページ復元
```

### データフロー図

```
    ┌───────────────────────────────────────────────────────────────┐
    │                      Backup Files                              │
    │  (Local Disk / UNC / Azure Blob / S3)                         │
    └───────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │   Get-DbaBackupInformation    │
                    │   - ヘッダー読み取り           │
                    │   - チェーン構築               │
                    └───────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │  Format-DbaBackupInformation  │
                    │   - ファイルパス設定           │
                    │   - プレフィックス/サフィックス │
                    └───────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │  Select-DbaBackupInformation  │
                    │   - RestoreTime フィルタ       │
                    │   - 差分/ログ選択              │
                    └───────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │   Test-DbaBackupInformation   │
                    │   - リストア可能性検証         │
                    │   - パス存在確認              │
                    └───────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │   Invoke-DbaAdvancedRestore   │
                    │   - RESTORE DATABASE 実行     │
                    │   - 順次リストア              │
                    └───────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │      Restored Database        │
                    └───────────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | データベースリストアメインコマンド |
| Get-DbaBackupInformation.ps1 | `public/Get-DbaBackupInformation.ps1` | ソース | バックアップ情報取得 |
| Format-DbaBackupInformation.ps1 | `public/Format-DbaBackupInformation.ps1` | ソース | バックアップ情報フォーマット |
| Select-DbaBackupInformation.ps1 | `public/Select-DbaBackupInformation.ps1` | ソース | バックアップ情報選択 |
| Test-DbaBackupInformation.ps1 | `public/Test-DbaBackupInformation.ps1` | ソース | バックアップ情報検証 |
| Invoke-DbaAdvancedRestore.ps1 | `public/Invoke-DbaAdvancedRestore.ps1` | ソース | 高度なリストア実行 |
