# 機能設計書 9-sp_DatabaseRestore

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_DatabaseRestoreストアドプロシージャの機能設計について記載する。sp_DatabaseRestoreはデータベースのリストア操作を自動化するユーティリティである。

### 本機能の処理概要

sp_DatabaseRestoreは、指定されたバックアップファイルパスからデータベースをリストアするためのストアドプロシージャである。フル、差分、トランザクションログバックアップの順序を自動的に検出し、適切なリストアコマンドを生成・実行する。

**業務上の目的・背景**：データベースのリストアは複雑な手順を伴い、特にログシッピングや災害復旧シナリオでは正確なLSN順序でのリストアが必要となる。sp_DatabaseRestoreはこれらの手順を自動化し、人為的ミスを防ぐ。

**機能の利用シーン**：
- ログシッピングの受信側でのリストア自動化
- 災害復旧時のデータベース復元
- テスト環境への本番データベース複製
- ポイントインタイムリカバリ

**主要な処理内容**：
1. バックアップファイルの列挙と解析
2. RESTORE HEADERONLYによるバックアップ情報取得
3. RESTORE FILELISTONLYによるファイル情報取得
4. リストアコマンドの生成
5. リストア実行（オプション）
6. DBCC CHECKDB実行（オプション）

**関連システム・外部連携**：
- Ola HallengrenのCommandExecuteストアドプロシージャ（必須依存）
- ファイルシステム（バックアップファイルの読み取り）

**権限による制御**：
- データベースリストア権限が必要
- バックアップファイルへのアクセス権が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | sp_DatabaseRestore結果画面 | 主機能 | バックアップからのデータベースリストアを実行 |

## 機能種別

運用ユーティリティ / データベース復元 / 自動化ツール

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| @Database | NVARCHAR(128) | No | リストア対象データベース名 | NULL許可 |
| @RestoreDatabaseName | NVARCHAR(128) | No | リストア先データベース名 | NULL時は@Database使用 |
| @BackupPathFull | NVARCHAR(260) | No | フルバックアップパス | NULL許可 |
| @BackupPathDiff | NVARCHAR(260) | No | 差分バックアップパス | NULL許可 |
| @BackupPathLog | NVARCHAR(260) | No | ログバックアップパス | NULL許可 |
| @MoveFiles | BIT | No | ファイル移動有効化 | デフォルト1 |
| @MoveDataDrive | NVARCHAR(260) | No | データファイル移動先 | NULL時はインスタンスデフォルト |
| @MoveLogDrive | NVARCHAR(260) | No | ログファイル移動先 | NULL時はインスタンスデフォルト |
| @MoveFilestreamDrive | NVARCHAR(260) | No | Filestream移動先 | NULL時はインスタンスデフォルト |
| @MoveFullTextCatalogDrive | NVARCHAR(260) | No | フルテキスト移動先 | NULL時はインスタンスデフォルト |
| @BufferCount | INT | No | バッファカウント | NULL許可 |
| @MaxTransferSize | INT | No | 最大転送サイズ | 4194304以下、64の倍数 |
| @BlockSize | INT | No | ブロックサイズ | 512-65536の2のべき乗 |
| @TestRestore | BIT | No | テストリストアモード | デフォルト0 |
| @RunCheckDB | BIT | No | CHECKDB実行 | デフォルト0 |
| @RestoreDiff | BIT | No | 差分リストア有効化 | デフォルト0 |
| @ContinueLogs | BIT | No | ログ継続リストア | デフォルト0 |
| @StandbyMode | BIT | No | スタンバイモード | デフォルト0 |
| @StandbyUndoPath | NVARCHAR(MAX) | No | スタンバイUndoファイルパス | NULL許可 |
| @RunRecovery | BIT | No | リカバリ実行 | デフォルト0 |
| @ForceSimpleRecovery | BIT | No | シンプルリカバリモデル強制 | デフォルト0 |
| @ExistingDBAction | TINYINT | No | 既存DB処理 | デフォルト0 |
| @StopAt | NVARCHAR(14) | No | ポイントインタイム（YYYYMMDDHHMMSS） | NULL許可 |
| @OnlyLogsAfter | NVARCHAR(14) | No | 指定日時以降のログのみ | NULL許可 |
| @SimpleFolderEnumeration | BIT | No | xp_dirtree使用 | デフォルト0 |
| @SkipBackupsAlreadyInMsdb | BIT | No | MSDB既存スキップ | デフォルト0 |
| @DatabaseOwner | sysname | No | DB所有者 | NULL許可 |
| @SetTrustworthyON | BIT | No | TRUSTWORTHY ON設定 | デフォルト0 |
| @FixOrphanUsers | BIT | No | 孤立ユーザー修正 | デフォルト0 |
| @KeepCdc | BIT | No | CDC維持 | デフォルト0 |
| @Execute | CHAR(1) | No | 実行フラグ | デフォルト'Y' |
| @FileExtensionDiff | NVARCHAR(128) | No | 差分ファイル拡張子 | NULL許可 |
| @Debug | INT | No | デバッグモード | デフォルト0 |
| @Help | BIT | No | ヘルプ表示 | デフォルト0 |
| @Version | VARCHAR(30) | No | バージョン（OUTPUT） | 出力専用 |
| @VersionDate | DATETIME | No | バージョン日付（OUTPUT） | 出力専用 |
| @VersionCheckMode | BIT | No | バージョンチェックモード | デフォルト0 |
| @FileNamePrefix | NVARCHAR(260) | No | ファイル名プレフィックス | NULL許可 |
| @RunStoredProcAfterRestore | NVARCHAR(260) | No | リストア後実行プロシージャ | NULL許可 |
| @EnableBroker | BIT | No | Service Broker有効化 | デフォルト0 |

### 入力データソース

- バックアップファイル（フル、差分、ログ）
- RESTORE HEADERONLY: バックアップヘッダー情報
- RESTORE FILELISTONLY: ファイルリスト情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| GeneratedCommand | NVARCHAR(MAX) | 生成されたリストアコマンド |
| ExecutionResult | VARCHAR | 実行結果 |

### 出力先

- 画面表示（生成されたコマンド）
- 実行結果のPRINT出力

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証と初期化
   ├─ CommandExecute存在確認
   ├─ パス末尾の補正（\または/追加）
   └─ デフォルトパス設定

2. バックアップファイル列挙
   ├─ xp_cmdshellまたはxp_dirtreeでファイル取得
   └─ CSVパス分割処理（ストライプバックアップ対応）

3. フルバックアップ処理
   ├─ RESTORE HEADERONLYでLSN取得
   ├─ RESTORE FILELISTONLYでファイル情報取得
   └─ RESTOREコマンド生成・実行

4. 差分バックアップ処理（@RestoreDiff=1時）
   ├─ 差分バックアップファイル特定
   └─ RESTOREコマンド生成・実行

5. ログバックアップ処理
   ├─ LSN順にログファイル特定
   └─ RESTOREコマンド順次生成・実行

6. リカバリ処理（@RunRecovery=1時）
   └─ RESTORE WITH RECOVERY

7. 後処理（オプション）
   ├─ DBCC CHECKDB
   ├─ DB所有者変更
   ├─ TRUSTWORTHY設定
   └─ カスタムプロシージャ実行
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{@Help = 1?}
    B -->|Yes| C[ヘルプ出力]
    C --> Z[終了]
    B -->|No| D{SQL Server 2008以降?}
    D -->|No| E[エラー終了]
    D -->|Yes| F{CommandExecute存在?}
    F -->|No| E
    F -->|Yes| G[パス補正・初期化]
    G --> H[バックアップファイル列挙]
    H --> I{フルバックアップあり?}
    I -->|No| E
    I -->|Yes| J[RESTORE HEADERONLY]
    J --> K[RESTORE FILELISTONLY]
    K --> L[フルリストア実行]
    L --> M{@RestoreDiff = 1?}
    M -->|Yes| N[差分リストア実行]
    M -->|No| O{ログバックアップあり?}
    N --> O
    O -->|Yes| P[ログリストア順次実行]
    O -->|No| Q{@RunRecovery = 1?}
    P --> Q
    Q -->|Yes| R[RESTORE WITH RECOVERY]
    Q -->|No| S{@RunCheckDB = 1?}
    R --> S
    S -->|Yes| T[DBCC CHECKDB]
    S -->|No| U[後処理]
    T --> U
    U --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パス補正 | パス末尾に\または/を自動追加 | 常時 |
| BR-002 | デフォルトパス | データ/ログ移動先未指定時はインスタンスデフォルト | @Move*Drive=NULL |
| BR-003 | LSN順序 | ログはLSN順にリストア | 常時 |
| BR-004 | CommandExecute依存 | Ola Hallengrenスクリプトが必須 | 常時 |
| BR-005 | xp_cmdshell代替 | xp_cmdshell無効時はxp_dirtree使用 | xp_cmdshell disabled |
| BR-006 | @Execute=N | 'N'の場合はコマンド生成のみ | @Execute='N' |

### 計算ロジック

**パス補正**:
```sql
IF (SELECT RIGHT(@BackupPathFull, 1)) <> '\'
  SET @BackupPathFull += N'\';
```

**ストライプバックアップパス分割**:
```sql
-- CSVパスをOla Hallengren方式で分割
WITH BackupPaths AS (
  SELECT PathItem FROM split_csv_logic
)
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 参照 | sys.objects | SELECT | CommandExecute存在確認 |
| 参照 | sys.configurations | SELECT | xp_cmdshell設定確認 |
| 実行 | RESTORE DATABASE | DDL | データベースリストア |
| 実行 | DBCC CHECKDB | DDL | 整合性チェック |

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

#### #Headers（一時テーブル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | BackupName, BackupType, FirstLSN, LastLSN | RESTORE HEADERONLY | バックアップ情報 |
| INSERT | Seq | IDENTITY | 順序管理 |

#### #FileListParameters（一時テーブル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | LogicalName, PhysicalName, Type | RESTORE FILELISTONLY | ファイル情報 |
| INSERT | FileGroupName | RESTORE FILELISTONLY | ファイルグループ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | バージョンエラー | SQL Server 2008未満 | RAISERRORでエラー通知、RETURN |
| - | 依存エラー | CommandExecute不在 | RAISERRORでエラー通知、RETURN |
| - | パラメータエラー | @MaxTransferSize > 4194304 | RAISERRORでエラー通知 |
| - | パラメータエラー | @MaxTransferSize % 64 <> 0 | RAISERRORでエラー通知 |
| - | パラメータエラー | @BlockSize不正値 | RAISERRORでエラー通知 |

### リトライ仕様

特定のリトライ機能は実装されていない。エラー時はTHROWで例外を再スロー。

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

明示的なトランザクション制御は行われない。各RESTOREコマンドは個別に実行。

## パフォーマンス要件

- @BufferCount、@MaxTransferSize、@BlockSizeでリストアパフォーマンスを調整可能
- 大規模データベースではパラメータチューニングが重要

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

- データベースリストア権限が必要
- @SetTrustworthyONは慎重に使用
- xp_cmdshell使用時はセキュリティに注意

## 備考

- バージョン: 8.29（2026年2月3日時点）
- SQL Server 2008以降対応
- Ola HallengrenのCommandExecuteストアドプロシージャが必須
- SQL Server 2016以降でLast Valid Restore Time列に対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **279-288行目**: @FileList、@FileListSimple、@PathItemテーブル変数 |
| 1-2 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **295-320行目**: #FileListParameters一時テーブル定義 |
| 1-3 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **322-388行目**: #Headers一時テーブル定義 |

**読解のコツ**:
- #Headers: RESTORE HEADERONLYの結果を格納。SQLバージョンによりカラム数が異なる
- #FileListParameters: RESTORE FILELISTONLYの結果を格納
- @FileList: バックアップファイルパスの一覧を格納

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **14-55行目**: ALTER PROCEDURE定義とパラメータ |
| 2-2 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **56-66行目**: 初期設定とバージョンチェック |
| 2-3 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **69-224行目**: @Help=1時のヘルプ出力 |

**主要処理フロー**:
1. **61行目**: バージョン情報設定（8.29）
2. **227-239行目**: SQL Serverバージョン確認
3. **241-254行目**: CommandExecute存在確認

#### Step 3: パス補正処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **393-425行目**: バックアップパス補正 |
| 3-2 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **426-489行目**: 移動先パス補正 |
| 3-3 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **490-500行目**: スタンバイUndoパス補正 |

**主要処理フロー**:
- 各パスの末尾に\または/がない場合は追加
- @Move*Driveが未指定の場合はインスタンスデフォルトを使用

#### Step 4: バックアップファイル列挙を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **541-543行目**: xp_cmdshell無効時の代替 |
| 4-2 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **544-564行目**: @HeadersSQL動的構築 |
| 4-3 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | **566-600行目**: CSVパス分割とファイル列挙 |

**主要処理フロー**:
- xp_cmdshellが無効な場合はxp_dirtreeを使用
- ストライプバックアップ対応のためCSVパスを分割処理

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

```
sp_DatabaseRestore
    │
    ├─ パラメータ検証
    │   ├─ バージョンチェック（SQL Server 2008以降）
    │   └─ CommandExecute存在確認
    │
    ├─ パス補正
    │   ├─ バックアップパス（Full/Diff/Log）
    │   ├─ 移動先パス（Data/Log/Filestream/FullText）
    │   └─ スタンバイUndoパス
    │
    ├─ バックアップファイル列挙
    │   ├─ xp_cmdshell または xp_dirtree
    │   └─ @FileList テーブル変数
    │
    ├─ RESTORE HEADERONLY
    │   └─ #Headers 一時テーブル
    │
    ├─ RESTORE FILELISTONLY
    │   └─ #FileListParameters 一時テーブル
    │
    ├─ CommandExecute（Ola Hallengren）
    │   ├─ RESTORE DATABASE (FULL)
    │   ├─ RESTORE DATABASE (DIFF)
    │   ├─ RESTORE LOG (順次)
    │   └─ RESTORE WITH RECOVERY
    │
    └─ 後処理
        ├─ DBCC CHECKDB
        ├─ ALTER AUTHORIZATION
        ├─ ALTER DATABASE SET TRUSTWORTHY
        └─ カスタムプロシージャ実行
```

### データフロー図

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

パラメータ ──────────────────▶ パラメータ検証 ─────────────────▶
   │                              │
   │                              ▼
バックアップパス ────────────▶ パス補正 ────────────────────────▶
   │                              │
   │                              ▼
ファイルシステム ────────────▶ ファイル列挙 ───────────────────▶ @FileList
   │                              │
   │                              ▼
バックアップファイル ────────▶ RESTORE HEADERONLY ────────────▶ #Headers
   │                              │
   │                              ▼
バックアップファイル ────────▶ RESTORE FILELISTONLY ──────────▶ #FileListParameters
   │                              │
   │                              ▼
                            RESTOREコマンド生成
                                  │
                                  ▼
                            CommandExecute ────────────────────▶ 実行結果
                                  │
                                  ▼
                            後処理 ────────────────────────────▶ 完了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | ソース | メインストアドプロシージャ定義 |
| CommandExecute（外部） | Ola Hallengren | 依存 | コマンド実行エンジン |
