# アーキテクチャ設計書

## 概要

本ドキュメントは、SQL Server First Responder Kitのアーキテクチャ設計を記載したものです。SQL Server First Responder Kitは、Microsoft SQL Serverのデータベース管理者(DBA)、システム管理者、開発者向けに設計されたT-SQLストアドプロシージャ集であり、SQL Serverのパフォーマンス診断、ヘルスチェック、トラブルシューティングを支援するツールキットです。

## システム全体構成

### アーキテクチャ概要図

[アーキテクチャ構成図](./アーキテクチャ構成図.md)を参照してください。

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| SQL Server DMV (Dynamic Management Views) | T-SQL クエリ | サーバー状態、パフォーマンス統計、待機統計の取得 |
| SQL Server システムデータベース (master, msdb, model, tempdb) | T-SQL クエリ | バックアップ履歴、ジョブ情報、データベースメタデータの取得 |
| Extended Events / System Health Session | XML解析 | デッドロック情報、パフォーマンスイベントの取得 |
| 外部出力テーブル | INSERT文 | 診断結果の永続化・履歴管理 |
| Ola Hallengren Maintenance Solution | ストアドプロシージャ連携 | sp_DatabaseRestoreがCommandExecuteプロシージャを使用 |
| OpenAI API (オプション) | REST API呼び出し | sp_BlitzCacheのAIアドバイス機能 |

## レイヤー構成

### アーキテクチャスタイル

**モジュラーストアドプロシージャアーキテクチャ**

本プロジェクトは、各機能領域に特化した独立したストアドプロシージャ群で構成されており、単一責任の原則に基づいた設計となっています。各プロシージャは独立して動作可能であり、必要に応じて相互に呼び出すことができます。

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| エントリーポイント層 | ユーザーからの実行要求受付、パラメータ検証、出力形式制御 | 各ストアドプロシージャのパラメータ処理部分 |
| 診断・分析層 | SQL Serverの状態診断、パフォーマンス分析、問題検出 | sp_Blitz, sp_BlitzFirst, sp_BlitzCache, sp_BlitzIndex, sp_BlitzLock, sp_BlitzWho |
| データ収集層 | DMV、システムテーブルからの情報収集 | 各プロシージャ内の動的SQL生成・実行部分 |
| 結果集約・出力層 | 診断結果の優先順位付け、フォーマット変換、出力先への書き込み | 一時テーブル、結果セット出力、テーブル永続化 |
| ユーティリティ層 | 共通機能、バージョン管理、ヘルプ表示 | @Help, @Version, @VersionDate パラメータ処理 |

### レイヤー間の依存関係ルール

1. **診断プロシージャの独立性**: 各診断プロシージャ(sp_Blitz, sp_BlitzCache等)は独立して実行可能
2. **呼び出し階層**: sp_BlitzFirst は sp_BlitzWho, sp_BlitzCache を内部で呼び出し可能
3. **データ収集の分離**: DMVアクセスは各プロシージャ内で個別に実装
4. **出力の統一**: 全プロシージャで共通の出力パラメータ体系 (@OutputDatabaseName, @OutputSchemaName, @OutputTableName)

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| サーバーヘルスチェック | SQL Server全体の健全性診断 | sp_Blitz |
| リアルタイムパフォーマンス診断 | 現在実行中のクエリ・待機状態の分析 | sp_BlitzFirst, sp_BlitzWho |
| クエリパフォーマンス分析 | プランキャッシュ内のリソース集約型クエリ特定 | sp_BlitzCache |
| インデックス分析 | インデックス設計・使用状況の診断 | sp_BlitzIndex |
| デッドロック分析 | デッドロック履歴の解析・可視化 | sp_BlitzLock |
| バックアップ分析 | バックアップ状況・RPO/RTO分析 | sp_BlitzBackups |
| データベースリストア | バックアップからのリストア自動化 | sp_DatabaseRestore |
| 履歴データ分析 | sp_BlitzFirst出力テーブルの分析 | sp_BlitzAnalysis |
| ユーティリティ | 複数データベースへの一括実行 | sp_ineachdb |

### パッケージ構造

```
SQL-Server-First-Responder-Kit/
├── sp_Blitz.sql                    # 総合ヘルスチェック
├── sp_BlitzFirst.sql               # リアルタイム診断
├── sp_BlitzCache.sql               # クエリキャッシュ分析
├── sp_BlitzIndex.sql               # インデックス分析
├── sp_BlitzLock.sql                # デッドロック分析
├── sp_BlitzWho.sql                 # 現在実行中クエリ表示
├── sp_BlitzBackups.sql             # バックアップ分析
├── sp_BlitzAnalysis.sql            # 履歴データ分析
├── sp_DatabaseRestore.sql          # リストア自動化
├── sp_ineachdb.sql                 # 複数DB一括実行
├── SqlServerVersions.sql           # SQLServerバージョン情報テーブル
├── Install-All-Scripts.sql         # 全スクリプト統合インストール
├── Install-Azure.sql               # Azure SQL DB用インストール
├── Uninstall.sql                   # アンインストール
├── Documentation/                  # ドキュメント
│   ├── Development/                # 開発者向けドキュメント
│   ├── sp_Blitz_Checks_by_Priority.md
│   ├── sp_BlitzCache_Checks_by_Priority.md
│   ├── sp_BlitzFirst_Checks_by_Priority.md
│   └── sp_BlitzIndex_Checks_by_Priority.md
├── Deprecated/                     # 非推奨・旧バージョン
│   ├── sp_Blitz_SQL_Server_2005.sql
│   ├── sp_BlitzCache_SQL_Server_2005.sql
│   ├── sp_BlitzIndex_SQL_Server_2005.sql
│   ├── sp_BlitzQueryStore.sql
│   ├── sp_BlitzInMemoryOLTP.sql
│   ├── sp_AllNightLog.sql
│   └── sp_AllNightLog_Setup.sql
└── .github/                        # GitHub設定
    ├── ISSUE_TEMPLATE/
    ├── workflows/
    ├── bug_report.md
    └── feature_request.md
```

### コンポーネント依存関係

- **sp_BlitzFirst** -> **sp_BlitzWho**: リアルタイム診断中に現在実行中クエリを取得
- **sp_BlitzFirst** -> **sp_BlitzCache**: 診断中にクエリキャッシュ統計を収集
- **sp_BlitzAnalysis** -> **sp_BlitzFirst出力テーブル**: 履歴データの分析
- **sp_DatabaseRestore** -> **Ola Hallengren CommandExecute**: リストアコマンド実行
- **全プロシージャ** -> **SQL Server DMV/システムテーブル**: メタデータ・統計情報取得

## ミドルウェア構成

### データベース

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| RDB | Microsoft SQL Server | 2008以降 (Microsoft サポート対象版) | 診断対象・実行環境 |
| RDB | Azure SQL Database | - | 診断対象・実行環境 (一部制限あり) |
| RDB | Amazon RDS for SQL Server | - | 診断対象・実行環境 |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| SQL Server Plan Cache | - | クエリプラン、sp_BlitzCacheの分析対象 | SQL Server管理 |
| SQL Server Buffer Pool | - | sp_BlitzFirstのメモリ統計分析対象 | SQL Server管理 |

### メッセージキュー

本プロジェクトではメッセージキューは使用していません。

### 検索エンジン

本プロジェクトでは専用の検索エンジンは使用していません。Full-Text Searchの診断はsp_Blitzで実施されます。

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Extended Events | SQL Server 2008以降 | sp_BlitzLockでのデッドロックXML取得 |
| SQL Server Agent | - | 定期実行ジョブとして各プロシージャをスケジュール実行 |
| Database Mail | - | sp_Blitzからのアラート通知 (オプション) |

## データフロー

### リクエスト処理の流れ

1. **パラメータ受付**: ストアドプロシージャが@Help, @OutputType等のパラメータを受け取る
2. **バージョンチェック**: @VersionCheckMode=1の場合、バージョン情報のみ返して即座に終了
3. **権限チェック**: sysadmin権限、VIEW SERVER STATE権限等を確認
4. **一時テーブル作成**: 診断結果格納用の一時テーブル(#BlitzResults等)を作成
5. **DMV/システムテーブルクエリ**: 動的SQLで各種診断クエリを実行
6. **結果集約**: 一時テーブルに検出結果を優先度付きで格納
7. **出力処理**: @OutputTypeに応じてTABLE/XML/MARKDOWN形式で結果を返却、または指定テーブルに書き込み

### 非同期処理の流れ

本プロジェクトは同期処理のみで構成されています。ただし、以下の運用パターンが推奨されています:

1. **SQL Server Agentジョブによる定期実行**: sp_BlitzFirstを15分間隔で実行し、出力テーブルに履歴蓄積
2. **sp_BlitzAnalysisによる履歴分析**: 蓄積された履歴データを後から分析

### データ永続化の流れ

1. **出力パラメータ指定**: @OutputDatabaseName, @OutputSchemaName, @OutputTableNameを指定
2. **テーブル存在確認**: 出力先テーブルの存在を確認、不存在時は自動作成
3. **結果INSERT**: 診断結果を出力テーブルにINSERT
4. **保持期間管理**: @OutputTableRetentionDaysパラメータで古いデータを自動削除

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| sysadmin権限チェック | 各プロシージャ冒頭 | DBCC、トレースファイルアクセス等の特権操作 |
| VIEW SERVER STATE権限チェック | 各プロシージャ冒頭 | DMVアクセスの最低要件 |
| データベース単位権限チェック | @db_permsテーブル | ユーザーデータベースオブジェクトチェック |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| 診断結果ログ | @Output*パラメータによるテーブル出力 | ユーザー指定テーブル |
| 実行メッセージ | RAISERROR WITH NOWAIT | SSMSメッセージタブ |
| デバッグ情報 | @Debug=1/2パラメータ | SSMSメッセージタブ、動的SQL出力 |
| カスタムメッセージ | sp_BlitzFirst @LogMessage | BlitzFirstテーブル |

### エラーハンドリング

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| パラメータ検証エラー | RAISERROR + RETURN | エラーメッセージ表示後、即座に終了 |
| 権限不足 | IF文でスキップまたはRAISERROR | 可能な範囲で続行、または警告メッセージ |
| DMVアクセスエラー | TRY-CATCH | エラー内容を結果セットに含めて続行 |
| 出力テーブルエラー | IF EXISTS確認 | テーブル自動作成、または警告メッセージ |

### トランザクション管理

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| 全プロシージャ | SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED | READ UNCOMMITTED (ダーティリード許容) |

**理由**: 診断ツールとしての性質上、ロックの取得を最小化し、本番環境への影響を軽減するため。

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| 単一責任の原則 | 各ストアドプロシージャ | sp_BlitzCache はクエリキャッシュ分析のみに特化 |
| オープン・クローズド原則 | チェック追加の容易性 | CheckIDベースの診断項目追加が可能 |
| 依存性逆転の原則 | 出力先の抽象化 | @Output*パラメータによる出力先の柔軟な指定 |
| DRY原則 | 共通パラメータ体系 | @Help, @Debug, @Version等の共通パラメータ |

### コーディング規約

1. **SET文の標準化**: 各プロシージャ冒頭で以下を設定
   - `SET NOCOUNT ON;`
   - `SET STATISTICS XML OFF;`
   - `SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED;`

2. **パラメータ命名規則**:
   - @Help: ヘルプ表示フラグ
   - @Debug: デバッグモード
   - @Version, @VersionDate: バージョン情報出力
   - @OutputDatabaseName, @OutputSchemaName, @OutputTableName: 出力先指定

3. **バージョン管理**:
   - 全プロシージャで統一バージョン番号 (例: 8.29)
   - @VersionCheckMode=1 で即座にバージョン情報のみ返却

4. **動的SQL**:
   - sp_executesql使用によるSQLインジェクション防止
   - QUOTENAMEによるオブジェクト名エスケープ

5. **結果セット構造**:
   - Priority: 優先度 (1が最重要)
   - FindingsGroup: 問題カテゴリ
   - Finding: 問題の詳細
   - URL: 詳細情報へのリンク
   - Details: 動的に生成された詳細情報

## 備考

- **対応プラットフォーム**: SQL Server on Windows, SQL Server on Linux, Amazon RDS, Azure SQL DB (一部制限あり)
- **ライセンス**: MIT License
- **コントリビューション**: GitHub Issues/PRによる貢献が可能
- **非推奨機能**: Deprecatedフォルダに古いバージョン・非推奨機能を格納
