# 画面設計書 14-sp_DatabaseRestore実行画面

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_DatabaseRestoreストアドプロシージャが提供する実行画面の設計書です。sp_DatabaseRestoreは、Ola Hallengren氏のメンテナンスソリューションと連携して、バックアップファイルからデータベースを自動的にリストアする機能を提供します。

### 本画面の処理概要

sp_DatabaseRestore実行画面は、指定されたパスからフル、差分、ログバックアップを自動検出し、正しい順序でリストアを実行するユーティリティです。ログシッピングの手動設定、災害復旧テスト、開発環境への本番データベースコピーなど、様々なシナリオで利用できます。

**業務上の目的・背景**：データベースリストアは手順が複雑で、特に複数のログバックアップを正しい順序で適用する必要がある場合、ミスが発生しやすい作業です。sp_DatabaseRestoreは、バックアップファイルのパスを指定するだけで、最新のフルバックアップの検出、差分バックアップの適用、ログバックアップチェーンの復元を自動化し、ヒューマンエラーを防止します。また、Ola Hallengren氏のCommandExecuteプロシージャと連携することで、実行ログの記録と監視が可能です。

**画面へのアクセス方法**：SQL Server Management Studio（SSMS）またはAzure Data Studio等のクエリツールから、以下のようにストアドプロシージャを実行します。
- 基本実行: `EXEC sp_DatabaseRestore @Database = 'MyDB', @BackupPathFull = 'D:\Backup\MyDB\FULL\';`
- ログシッピング初期化: `EXEC sp_DatabaseRestore @Database = 'MyDB', @BackupPathFull = '...', @BackupPathLog = '...', @ContinueLogs = 0, @RunRecovery = 0;`
- ログシッピング継続: `EXEC sp_DatabaseRestore @Database = 'MyDB', @BackupPathLog = '...', @ContinueLogs = 1, @RunRecovery = 0;`

**主要な操作・処理内容**：
1. Ola Hallengren CommandExecuteプロシージャの存在確認
2. バックアップパスの正規化（末尾の区切り文字追加）
3. バックアップファイル一覧の取得（xp_cmdshell または xp_dirtree）
4. 最新フルバックアップの検出
5. RESTORE HEADERONLY/FILELISTONLYでバックアップ情報取得
6. MOVEオプションの構築（ファイル移動が必要な場合）
7. 既存データベースの処理（@ExistingDBAction）
8. フルバックアップのリストア
9. 差分バックアップのリストア（@RestoreDiff = 1の場合）
10. ログバックアップのリストア
11. 復旧（@RunRecovery = 1の場合）
12. DBCC CHECKDB（@RunCheckDB = 1の場合）
13. テストリストア後のDB削除（@TestRestore = 1の場合）

**画面遷移**：
- sp_BlitzBackupsからのリストア分析後に実行
- 単独のリストアユーティリティとして実行
- ログシッピング環境での定期実行

**権限による表示制御**：
- データベースリストアのためのALTER DATABASE権限が必要
- xp_cmdshellが有効な場合は追加の権限が必要
- CommandExecuteプロシージャの実行権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | sp_DatabaseRestore | 主機能 | バックアップファイルからデータベースをリストア |
| 8 | sp_BlitzBackups | 遷移元 | バックアップ分析後のリストア実行 |
| - | Ola Hallengren CommandExecute | 依存関係 | コマンド実行・ログ記録基盤 |

## 画面種別

ユーティリティ / コマンド実行

## URL/ルーティング

T-SQLストアドプロシージャとして実行
```sql
EXEC dbo.sp_DatabaseRestore [@パラメータ名] = [値];
```

## 入出力項目

### 入力パラメータ

| パラメータ名 | データ型 | デフォルト値 | 説明 |
|-------------|---------|-------------|------|
| @Database | NVARCHAR(128) | NULL | ソースデータベース名 |
| @RestoreDatabaseName | NVARCHAR(128) | NULL | リストア先データベース名（NULLの場合@Database） |
| @BackupPathFull | NVARCHAR(260) | NULL | フルバックアップパス（カンマ区切りで複数指定可） |
| @BackupPathDiff | NVARCHAR(260) | NULL | 差分バックアップパス |
| @BackupPathLog | NVARCHAR(260) | NULL | ログバックアップパス |
| @MoveFiles | BIT | 1 | ファイルを別ドライブに移動 |
| @MoveDataDrive | NVARCHAR(260) | NULL | データファイル移動先（NULLでデフォルトパス） |
| @MoveLogDrive | NVARCHAR(260) | NULL | ログファイル移動先（NULLでデフォルトパス） |
| @MoveFilestreamDrive | NVARCHAR(260) | NULL | FILESTREAMファイル移動先 |
| @MoveFullTextCatalogDrive | NVARCHAR(260) | NULL | フルテキストカタログ移動先 |
| @BufferCount | INT | NULL | RESTORE BufferCount |
| @MaxTransferSize | INT | NULL | RESTORE MaxTransferSize（最大4194304） |
| @BlockSize | INT | NULL | RESTORE BlockSize（512-65536） |
| @TestRestore | BIT | 0 | テストリストア後にDB削除 |
| @RunCheckDB | BIT | 0 | リストア後にDBCC CHECKDB実行 |
| @RestoreDiff | BIT | 0 | 差分バックアップをリストア |
| @ContinueLogs | BIT | 0 | ログバックアップの継続リストア |
| @StandbyMode | BIT | 0 | STANDBYモードでリストア |
| @StandbyUndoPath | NVARCHAR(MAX) | NULL | スタンバイUndoファイルパス |
| @RunRecovery | BIT | 0 | リストア後にRECOVERY実行 |
| @ForceSimpleRecovery | BIT | 0 | リカバリ後にSIMPLEモードに変更 |
| @ExistingDBAction | TINYINT | 0 | 既存DB処理（0:何もしない, 1:SINGLE_USER, 2:KILL, 3:DROP, 4:OFFLINE） |
| @StopAt | NVARCHAR(14) | NULL | ポイントインタイムリカバリの停止時刻（yyyyMMddHHmmss） |
| @OnlyLogsAfter | NVARCHAR(14) | NULL | 指定時刻以降のログのみリストア |
| @SimpleFolderEnumeration | BIT | 0 | xp_dirtreeを使用（xp_cmdshell無効時は自動的に1） |
| @SkipBackupsAlreadyInMsdb | BIT | 0 | msdbに既存のバックアップをスキップ |
| @DatabaseOwner | SYSNAME | NULL | リストア後のDB所有者 |
| @SetTrustworthyON | BIT | 0 | TRUSTWORTHYをONに設定 |
| @FixOrphanUsers | BIT | 0 | 孤立ユーザーの修正 |
| @KeepCdc | BIT | 0 | CDCを維持 |
| @Execute | CHAR(1) | 'Y' | 'Y'=実行, 'N'=コマンド出力のみ |
| @FileExtensionDiff | NVARCHAR(128) | NULL | 差分バックアップの拡張子 |
| @Debug | INT | 0 | デバッグ出力 |
| @Help | BIT | 0 | ヘルプ表示 |
| @FileNamePrefix | NVARCHAR(260) | NULL | 移動時のファイル名プレフィックス |
| @RunStoredProcAfterRestore | NVARCHAR(260) | NULL | リストア後に実行するプロシージャ |
| @EnableBroker | BIT | 0 | Service Brokerを有効化 |

## 表示項目

### 結果セット: コマンド実行結果

CommandExecuteプロシージャからの出力。

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| Command | NVARCHAR(MAX) | 実行されたコマンド |
| CommandType | VARCHAR(100) | コマンドタイプ（RESTORE DATABASE等） |
| StartTime | DATETIME | 開始時刻 |
| EndTime | DATETIME | 終了時刻 |
| ErrorNumber | INT | エラー番号（0=成功） |
| ErrorMessage | NVARCHAR(MAX) | エラーメッセージ |

### @Execute = 'N' または @Debug = 1 の場合

実行予定のRESTOREコマンドがPRINT出力されます。

## イベント仕様

### 1-プロシージャ実行

ユーザーがsp_DatabaseRestoreを実行すると、以下の処理が順次実行されます。

1. バージョンチェック（@VersionCheckMode=1時は即リターン）
2. @Help=1の場合はヘルプテキストを表示して終了
3. SQL Serverバージョン確認（2008未満はエラー）
4. Ola Hallengren CommandExecuteプロシージャの存在確認
5. パスの正規化（末尾に\または/を追加）
6. @MoveDataDrive等のデフォルト値設定（InstanceDefaultDataPath/LogPath）
7. バックアップファイル一覧取得
8. 最新フルバックアップ検出
9. RESTORE FILELISTONLY実行（#FileListParameters）
10. RESTORE HEADERONLY実行（#Headers）
11. MOVEオプション構築
12. @ExistingDBAction処理
13. フルバックアップリストア実行
14. 差分バックアップリストア（@RestoreDiff=1）
15. ログバックアップリストア
16. RECOVERY実行（@RunRecovery=1）
17. 後処理（DBCC CHECKDB、テストDB削除等）

### 2-ログシッピングモード

@ContinueLogs=1の場合：

1. 既存データベースのredo_start_lsnを取得
2. 該当LSN以降のログバックアップのみをリストア
3. @RunRecovery=0でスタンバイ状態を維持

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

@StopAtが指定された場合：

1. 指定日時より後のバックアップファイルを除外
2. STOPAT句付きでログをリストア
3. 指定時点での一貫性のある状態でRECOVERY

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| リストア実行 | [対象DB] | RESTORE | データベースリストア |
| 既存DB処理 | [対象DB] | ALTER/DROP | シングルユーザー/オフライン/削除 |
| CHECKDB実行 | [対象DB] | DBCC | 整合性チェック |
| テストリストア | [対象DB] | DROP | テスト後のDB削除 |

### リストア処理の内部動作

| 処理 | 説明 |
|-----|------|
| RESTORE DATABASE ... WITH NORECOVERY | フルバックアップリストア |
| RESTORE DATABASE ... WITH NORECOVERY | 差分バックアップリストア |
| RESTORE LOG ... WITH NORECOVERY | ログバックアップリストア |
| RESTORE DATABASE ... WITH RECOVERY | 最終リカバリ |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|--------------|----------|---------|
| エラー | Sorry, DatabaseRestore doesn't work on versions of SQL prior to 2008. | SQL Server 2008未満 |
| エラー | DatabaseRestore requires the CommandExecute stored procedure... | Ola Hallengren未インストール |
| エラー | (FULL) No rows were returned for that database in path %s | バックアップファイルなし |
| エラー | (FULL) Access is denied to %s | アクセス権限なし |
| エラー | No backups for "%s" found in "%s" | バックアップ検出失敗 |
| エラー | Backupfile "%s" does not match @Database parameter "%s" | ファイルとDB名不一致 |
| エラー | @MaxTransferSize can not be greater then 4194304 | パラメータ超過 |
| 情報 | Fixing @BackupPathFull to add a "\" | パス末尾補正 |
| 情報 | Getting default data drive for @MoveDataDrive | デフォルトパス取得 |
| 情報 | @MoveFiles = 1, adjusting paths | ファイル移動パス調整 |
| 情報 | Setting single user | シングルユーザー設定 |
| 情報 | Killing connections | 接続切断 |
| 情報 | Dropping database | DB削除 |
| 情報 | @ContinueLogs set to 0 | 初回リストアモード |

## 例外処理

| 状態 | 説明 | 対応 |
|------|------|------|
| SQL Server 2008未満 | サポート対象外バージョン | RAISERROR後RETURN |
| CommandExecute未インストール | Ola Hallengren依存関係なし | RAISERROR後RETURN |
| バックアップファイルなし | 指定パスにファイルがない | RAISERROR後RETURN |
| アクセス拒否 | パスへのアクセス権限なし | RAISERROR後RETURN |
| DB名不一致 | ヘッダのDB名とパラメータ不一致 | RAISERROR後RETURN |

## 備考

- Ola Hallengren氏のメンテナンスソリューション（CommandExecute）が必要
- xp_cmdshellが無効な場合は自動的にxp_dirtreeを使用
- 分割バックアップ（striped backup）に対応
- バージョン: 8.29（2026年2月3日時点）
- カンマ区切りで複数のバックアップパスを指定可能（striped backup対応）

### @ExistingDBAction値一覧

| 値 | 動作 |
|---|------|
| 0 | 何もしない（デフォルト） |
| 1 | SINGLE_USER WITH ROLLBACK IMMEDIATE |
| 2 | 既存接続をKILL |
| 3 | 既存接続をKILL後、DROP DATABASE |
| 4 | OFFLINE WITH ROLLBACK IMMEDIATE |

---

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

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

### 推奨読解順序

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

sp_DatabaseRestoreは複数の一時テーブルとテーブル変数を使用します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行279-283: @FileListSimpleテーブル変数（ファイル一覧） |
| 1-2 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行285-288: @FileListテーブル変数（バックアップパス+ファイル） |
| 1-3 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行296-320: #FileListParametersテーブル（RESTORE FILELISTONLY結果） |
| 1-4 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行322-388: #Headersテーブル（RESTORE HEADERONLY結果） |

**読解のコツ**: #HeadersテーブルはSQL Serverバージョンによってカラム数が異なります（行554-561参照）。

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

プロシージャのパラメータと初期化処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行14-54: プロシージャのパラメータ定義（41パラメータ） |
| 2-2 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行61: バージョン情報 '8.29', '20260203' |
| 2-3 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行69-225: @Help=1時のヘルプ出力（使用例付き） |

**主要処理フロー**:
1. **行227-239**: SQL Serverバージョンチェック（2008未満はエラー）
2. **行241-254**: CommandExecuteプロシージャ存在確認
3. **行390-500**: パス正規化（末尾区切り文字追加）

#### Step 3: バックアップファイル取得を理解する

ファイル一覧取得とフルバックアップ検出の処理です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行541-543: xp_cmdshell無効時の自動切り替え |
| 3-2 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行566-599: フルバックアップパス処理（CSV分割） |
| 3-3 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行596-613: xp_dirtree vs xp_cmdshellでのファイル取得 |
| 3-4 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行692-717: 最新フルバックアップ検出（ORDER BY DESC） |

**主要処理フロー**:
- **行598**: xp_dirtreeでディレクトリ一覧取得
- **行610**: xp_cmdshell DIR /bでファイル一覧取得
- **行694-701**: .bakファイルから最新を選択

#### Step 4: バックアップ情報取得を理解する

RESTORE HEADERONLYとFILELISTONLYの処理です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行544-564: @HeadersSQL動的構築 |
| 4-2 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行727-739: @FileListParamSQL動的構築 |
| 4-3 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行554-561: バージョン別カラム追加 |

**主要処理フロー**:
- **行554-555**: SQL Server 2012以降でContainmentカラム追加
- **行557-558**: SQL Server 2014 CU1以降で暗号化カラム追加
- **行560-561**: SQL Server 2016以降でLastValidRestoreTime等追加

#### Step 5: MOVEオプション構築を理解する

ファイル移動オプションの構築処理です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行792-816: @MoveFiles=1時のMOVEオプション構築 |

**主要処理フロー**:
- **行796-810**: WITH Files CTEでファイル種別（D/L/S/F）に応じた移動先を決定
- **行811**: MOVEオプション文字列を連結

#### Step 6: 既存DB処理を理解する

@ExistingDBActionによる既存データベース処理です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行818-905: @ExistingDBAction処理 |

**主要処理フロー**:
- **行823-844**: @ExistingDBAction=1: SINGLE_USER設定
- **行845-863**: @ExistingDBAction=2,3: 接続KILL
- **行864-876**: @ExistingDBAction=3: DROP DATABASE
- **行877-899**: @ExistingDBAction=4: OFFLINE設定

#### Step 7: リストア実行を理解する

実際のRESTOREコマンド実行処理です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 7-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行907-966: フルバックアップリストア |
| 7-2 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行912-929: 分割バックアップ対応 |
| 7-3 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 行930-944: スタンバイモード対応 |

**主要処理フロー**:
- **行916-924**: 分割バックアップ時は複数DISKを連結
- **行928**: 単一ファイル時のRESTORE DATABASE構築
- **行952**: CommandExecuteでコマンド実行

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

```
sp_DatabaseRestore
    |
    +-- Ola Hallengren CommandExecute（必須依存）
    |      |
    |      +-- コマンド実行ログ記録
    |
    +-- xp_dirtree / xp_cmdshell
    |      |
    |      +-- バックアップファイル一覧取得
    |
    +-- RESTORE HEADERONLY
    |      |
    |      +-- #Headersテーブル（バックアップメタ情報）
    |
    +-- RESTORE FILELISTONLY
    |      |
    |      +-- #FileListParameters（ファイル一覧）
    |
    +-- RESTORE DATABASE (FULL)
    |      |
    |      +-- WITH NORECOVERY, REPLACE
    |      +-- MOVEオプション
    |
    +-- RESTORE DATABASE (DIFF)
    |      |
    |      +-- WITH NORECOVERY
    |
    +-- RESTORE LOG
    |      |
    |      +-- WITH NORECOVERY / STANDBY
    |      +-- STOPAT（ポイントインタイム）
    |
    +-- RESTORE DATABASE WITH RECOVERY
    |
    +-- DBCC CHECKDB（オプション）
    |
    +-- DROP DATABASE（テストリストア時）
```

### データフロー図

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

@BackupPathFull         ───▶  パス正規化
@BackupPathDiff                    |
@BackupPathLog                     ▼
                            xp_dirtree/xp_cmdshell    ───▶  @FileList
                                    |
                                    ▼
                            最新バックアップ検出
                            (ORDER BY DESC)
                                    |
                                    ▼
                            RESTORE HEADERONLY        ───▶  #Headers
                            RESTORE FILELISTONLY      ───▶  #FileListParameters
                                    |
                                    ▼
@MoveDataDrive          ───▶  MOVEオプション構築     ───▶  @MoveOption
@MoveLogDrive
                                    |
                                    ▼
@ExistingDBAction       ───▶  既存DB処理
                            (SINGLE_USER/KILL/DROP/OFFLINE)
                                    |
                                    ▼
                            RESTORE DATABASE (FULL)
                                    |
                                    ▼
@RestoreDiff=1          ───▶  RESTORE DATABASE (DIFF)
                                    |
                                    ▼
@BackupPathLog          ───▶  RESTORE LOG
@StopAt                     (ループ処理)
                                    |
                                    ▼
@RunRecovery=1          ───▶  RESTORE WITH RECOVERY
                                    |
                                    ▼
@RunCheckDB=1           ───▶  DBCC CHECKDB
                                    |
                                    ▼
@TestRestore=1          ───▶  DROP DATABASE
                                    |
                                    ▼
                            [完了メッセージ]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | ソース | メインストアドプロシージャ |
| sp_BlitzBackups.sql | `sp_BlitzBackups.sql` | ソース | バックアップ分析（遷移元） |
| CommandExecute | 外部依存 | 外部 | Ola Hallengren実行基盤 |
