# 通知設計書 104-データベースオフライン

## 概要

本ドキュメントは、SQL Server First Responder Kit の sp_DatabaseRestore プロシージャにおける「データベースオフライン」情報通知の設計を定義する。

### 本通知の処理概要

この通知は、データベース復元プロセスにおいて、既存のデータベースをオフライン状態に設定する際に出力される情報メッセージである。

**業務上の目的・背景**：データベースの復元処理において、既存のデータベースを削除せずにオフライン状態にしておきたい場合がある。これは、既存データベースのファイルを保持しつつ、新しいバックアップからの復元を行う場合に有用である。オフライン状態のデータベースは、データファイルを保持したまま復元処理から除外される。この通知により、DBAはオフライン設定処理が実行されていることを把握できる。

**通知の送信タイミング**：`@ExistingDBAction = 4` が設定されており、かつ復元対象データベースが既に存在する場合に出力される。データベースの状態が 'RESTORING' でない場合にのみ、実際のオフライン設定が実行される。

**通知の受信者**：sp_DatabaseRestore プロシージャを実行しているDBA、またはSQL Server Management Studio (SSMS) のクエリウィンドウで結果を監視しているオペレーター。

**通知内容の概要**：「Offlining database」というメッセージが出力され、対象データベースがオフライン状態に移行することを示す。

**期待されるアクション**：通知を受け取った受信者は、データベースがオフライン状態に設定されることを確認する。オフライン状態のデータベースは手動でオンラインに戻す必要があるため、復元処理後の対応を計画しておく必要がある。

## 通知種別

RAISERROR によるメッセージ出力（SQL Server メッセージ / SSMS メッセージタブ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（RAISERROR WITH NOWAIT） |
| 優先度 | 情報（Severity 0） |
| リトライ | なし |

### 送信先決定ロジック

本通知はクライアント接続に対して直接送信される。sp_DatabaseRestore を実行しているセッションのクライアントが受信者となる。

## 通知テンプレート

### メッセージ通知の場合

| 項目 | 内容 |
|-----|------|
| メッセージ形式 | プレーンテキスト |
| 重大度 | 0（情報） |
| 状態 | 1 |

### 本文テンプレート

```
Offlining database
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | 本メッセージは固定テキスト | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| プロシージャ実行 | sp_DatabaseRestore の @ExistingDBAction = 4 | @RestoreDatabaseID IS NOT NULL | 既存DBをオフラインにして復元を実行 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| @ExistingDBAction が 0, 1, 2, 3 | オフライン設定が不要 |
| @RestoreDatabaseID IS NULL | 復元対象データベースが存在しない場合は不要 |
| DATABASEPROPERTYEX が 'RESTORING' | 既に復元中のデータベースには設定不要 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[sp_DatabaseRestore 実行開始] --> B{@ExistingDBAction = 4?}
    B -->|No| Z[他の処理へ]
    B -->|Yes| C{@RestoreDatabaseID IS NOT NULL?}
    C -->|No| D[警告出力]
    C -->|Yes| E[RAISERROR 'Offlining database']
    E --> F{データベース状態 = RESTORING?}
    F -->|Yes| G[スキップ: 既に復元中]
    F -->|No| H[ALTER DATABASE SET OFFLINE WITH ROLLBACK IMMEDIATE]
    H --> I[CommandExecute 実行]
    I --> J[次の処理へ]
    G --> J
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| sys.databases | データベースの存在確認と状態確認 | DB_ID 関数経由、DATABASEPROPERTYEX |

### テーブル別参照項目詳細

#### sys.databases

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| database_id | 対象DBの存在確認 | DB_ID(@RestoreDatabaseName) |
| state_desc | データベース状態確認 | DATABASEPROPERTYEX(@UnquotedRestoreDatabaseName, 'STATUS') |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| sys.databases | UPDATE | ALTER DATABASE SET OFFLINE による状態変更 |
| dbo.CommandLog | INSERT | CommandExecute によるログ記録 |

#### CommandLog テーブル

| 操作 | 項目（カラム名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| INSERT | CommandType | 'OFFLINE DATABASE' | 実行コマンドの種別 |
| INSERT | DatabaseName | @UnquotedRestoreDatabaseName | 対象データベース名 |
| INSERT | Command | ALTER DATABASE ステートメント | 実行されたコマンド全文 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 権限不足 | ALTER DATABASE の実行権限がない | sysadmin または db_owner 権限を確認 |
| タイムアウト | ROLLBACK IMMEDIATE が長時間かかる | 長時間トランザクションを手動で終了 |
| 状態取得失敗 | DATABASEPROPERTYEX が NULL を返す | データベースの状態を手動確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし

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

- ALTER DATABASE SET OFFLINE は sysadmin 権限または対象データベースの db_owner 権限が必要
- ROLLBACK IMMEDIATE により他ユーザーのトランザクションが強制ロールバックされる
- オフライン状態のデータベースは手動でオンラインに戻す必要がある

## 備考

- @Debug = 1 の場合、実行される SQL ステートメントも追加で出力される
- @Execute = 'N' の場合、メッセージは出力されるが実際のオフライン設定は実行されない
- オフライン状態のデータベースは ALTER DATABASE SET ONLINE で復旧可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | パラメータ定義（36行目）で @ExistingDBAction の役割を理解 |
| 1-2 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 276-277行目で @RestoreDatabaseID の定義を確認 |

**読解のコツ**: @ExistingDBAction = 4 は「データベースをオフライン」にする設定を意味する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 877-899行目でオフライン処理を確認 |

**主要処理フロー**:
1. **877行目**: `IF @ExistingDBAction = 4` - オフライン対象の判定
2. **879行目**: `RAISERROR ('Offlining database', 0, 1) WITH NOWAIT` - 本通知の出力
3. **881行目**: `SET @sql = N'ALTER DATABASE ' + @RestoreDatabaseName + SPACE( 1 ) + 'SET OFFLINE WITH ROLLBACK IMMEDIATE'` - SQL 構築
4. **889-891行目**: DATABASEPROPERTYEX による状態チェックと CommandExecute 実行

#### Step 3: ALTER DATABASE ステートメントの生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 881行目で ALTER DATABASE ステートメントの構築 |

**主要処理フロー**:
- **881行目**: `SET @sql = N'ALTER DATABASE ' + @RestoreDatabaseName + SPACE( 1 ) + 'SET OFFLINE WITH ROLLBACK IMMEDIATE'`

#### Step 4: CommandExecute による実行を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 889-891行目で CommandExecute の呼び出し |

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

```
sp_DatabaseRestore
    │
    ├─ DB_ID(@RestoreDatabaseName)
    │      └─ データベースIDの取得
    │
    ├─ RAISERROR('Offlining database', 0, 1)
    │      └─ 本通知の出力
    │
    ├─ DATABASEPROPERTYEX(@UnquotedRestoreDatabaseName, 'STATUS')
    │      └─ データベース状態の確認
    │
    └─ dbo.CommandExecute
           ├─ @Command = ALTER DATABASE ... SET OFFLINE
           ├─ @CommandType = 'OFFLINE DATABASE'
           └─ @LogToTable = 'Y'
```

### データフロー図

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

@ExistingDBAction = 4 ────▶ パラメータ評価 ───────────────▶ (分岐判定)
                               │
@RestoreDatabaseName ────▶ DB_ID 確認 ──────────────────▶ @RestoreDatabaseID
                               │
                               ▼
                         RAISERROR ──────────────────────▶ 'Offlining database'
                               │                           (メッセージ出力)
                               ▼
                    DATABASEPROPERTYEX ─────────────────▶ (状態チェック)
                               │
                               ▼
                      CommandExecute ───────────────────▶ CommandLog テーブル
                               │
                               ▼
                    ALTER DATABASE 実行 ─────────────────▶ データベース状態変更
                                                           (OFFLINE)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | ソース | 本通知を発行するストアドプロシージャ本体 |
| CommandExecute | Ola Hallengren Maintenance Solution | 依存プロシージャ | コマンド実行とログ記録を担当 |
