# 通知設計書 102-接続切断

## 概要

本ドキュメントは、SQL Server First Responder Kit の sp_DatabaseRestore プロシージャにおける「接続切断」情報通知の設計を定義する。

### 本通知の処理概要

この通知は、データベース復元プロセスにおいて、既存のデータベースへの接続を強制的に切断する際に出力される情報メッセージである。

**業務上の目的・背景**：データベースの復元処理では、対象データベースに対するアクティブな接続が存在すると処理が失敗する。特に運用中のデータベースを復元する場合、ユーザーセッションやアプリケーション接続が存在する可能性がある。この通知により、DBAは接続切断処理が実行されていることを把握でき、復元プロセスの進行状況を監視できる。

**通知の送信タイミング**：`@ExistingDBAction = 2` または `@ExistingDBAction = 3` が設定されており、かつ復元対象データベースが既に存在する場合に出力される。@ExistingDBAction = 2 は接続切断のみ、@ExistingDBAction = 3 は接続切断後にデータベース削除を実行する。

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

**通知内容の概要**：「Killing connections」というメッセージが出力され、対象データベースへの既存接続が強制終了されることを示す。

**期待されるアクション**：通知を受け取った受信者は、接続切断処理が正常に進行していることを確認する。影響を受けるユーザーがいる場合は、事前に通知しておくことが望ましい。切断された接続のユーザーは再接続が必要になる。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
Killing connections
```

### 添付ファイル

なし

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| プロシージャ実行 | sp_DatabaseRestore の @ExistingDBAction が 2 または 3 に設定 | @RestoreDatabaseID IS NOT NULL | 既存接続を切断してから復元を実行 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| @ExistingDBAction が 0, 1, 4 | 接続切断が不要 |
| @RestoreDatabaseID IS NULL | 復元対象データベースが存在しない場合は不要 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[sp_DatabaseRestore 実行開始] --> B{@ExistingDBAction IN 2,3?}
    B -->|No| Z[他の処理へ]
    B -->|Yes| C{@RestoreDatabaseID IS NOT NULL?}
    C -->|No| D[警告出力]
    C -->|Yes| E[RAISERROR 'Killing connections']
    E --> F[sys.sysprocesses から接続一覧取得]
    F --> G[KILL コマンド生成]
    G --> H[CommandExecute 実行]
    H --> I{@ExistingDBAction = 3?}
    I -->|Yes| J[DROP DATABASE 処理へ]
    I -->|No| K[次の処理へ]
    J --> K
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| sys.sysprocesses | 対象DBへの接続セッション一覧取得 | dbid で対象DBを指定 |

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

#### sys.sysprocesses

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| spid | セッションID（KILL コマンドに使用） | WHERE dbid = @RestoreDatabaseID |
| dbid | データベースID | フィルタ条件 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| dbo.CommandLog | INSERT | CommandExecute によるログ記録 |

#### CommandLog テーブル

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 権限不足 | KILL コマンドの実行権限がない | sysadmin または processadmin 権限を確認 |
| セッション不存在 | KILL 対象のセッションが既に終了 | 無視して継続（通常は問題なし） |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし

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

- KILL コマンドは sysadmin または processadmin 権限が必要
- 他ユーザーのセッションを強制終了するため、影響範囲を事前に確認すべき
- 実行されるすべての KILL コマンドは CommandLog テーブルに記録される

## 備考

- @Debug = 1 の場合、生成された KILL コマンドの一覧が出力される
- @Execute = 'N' の場合、メッセージは出力されるが実際の KILL は実行されない
- sys.sysprocesses は SQL Server 2012 以降で sys.dm_exec_sessions に置き換えられているが、下位互換性のために使用されている

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: @ExistingDBAction = 2 は「接続を切断」、@ExistingDBAction = 3 は「接続を切断してからDB削除」を意味する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 845-863行目で接続切断処理を確認 |

**主要処理フロー**:
1. **845行目**: `IF @ExistingDBAction IN (2, 3)` - 接続切断対象の判定
2. **847行目**: `RAISERROR('Killing connections', 0, 1) WITH NOWAIT` - 本通知の出力
3. **848行目**: `SET @sql = N'/* Kill connections */' + NCHAR(13)` - SQL 構築開始
4. **849-855行目**: sys.sysprocesses から KILL コマンドを動的生成

#### Step 3: KILL コマンドの生成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_DatabaseRestore.sql | `sp_DatabaseRestore.sql` | 849-855行目で KILL コマンドの動的構築 |

**主要処理フロー**:
- **849-855行目**: `SELECT @sql = @sql + N'KILL ' + CAST(spid as nvarchar(5)) + N';' + NCHAR(13) FROM sys.sysprocesses WHERE dbid = @RestoreDatabaseID`

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

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

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

```
sp_DatabaseRestore
    │
    ├─ DB_ID(@RestoreDatabaseName)
    │      └─ データベースIDの取得
    │
    ├─ RAISERROR('Killing connections', 0, 1)
    │      └─ 本通知の出力
    │
    ├─ sys.sysprocesses クエリ
    │      └─ 対象DBへの接続セッション取得
    │
    └─ dbo.CommandExecute
           ├─ @Command = KILL ステートメント群
           ├─ @CommandType = 'KILL CONNECTIONS'
           └─ @LogToTable = 'Y'
```

### データフロー図

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

@ExistingDBAction = 2,3 ──▶ パラメータ評価 ───────────────▶ (分岐判定)
                               │
@RestoreDatabaseName ────▶ DB_ID 確認 ──────────────────▶ @RestoreDatabaseID
                               │
                               ▼
                         RAISERROR ──────────────────────▶ 'Killing connections'
                               │                           (メッセージ出力)
                               ▼
                    sys.sysprocesses ───────────────────▶ spid 一覧
                               │
                               ▼
                    KILL コマンド生成 ──────────────────▶ @sql
                               │
                               ▼
                      CommandExecute ───────────────────▶ CommandLog テーブル
                               │
                               ▼
                    KILL 実行 ──────────────────────────▶ 接続終了
```

### 関連ファイル一覧

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