# 機能設計書 428-Test-DbaDbQueryStore

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Test-DbaDbQueryStore`コマンドレットに関する機能設計書である。このコマンドレットは、SQL ServerデータベースのQuery Store設定をベストプラクティスと比較評価する機能を提供する。

### 本機能の処理概要

`Test-DbaDbQueryStore`は、Query Store構成設定を事前定義されたベストプラクティスルールセットと比較し、各設定項目が推奨値に準拠しているかを評価するコマンドレットである。これにより、最適なQuery Store設定を維持するためのガイダンスを提供する。

**業務上の目的・背景**：Query Storeは、適切に設定されていないとパフォーマンス監視の品質が低下し、ディスク容量の浪費や、必要なデータの欠落につながる可能性がある。本機能は、Erin Stellatoによるベストプラクティス推奨事項に基づき、Query Store設定の監査を自動化する。これにより、DBAは環境全体でQuery Store設定が最適化されていることを効率的に確認できる。

**機能の利用シーン**：
- Query Store設定の健全性チェックを行う場合
- 新規データベースのQuery Store設定を検証する場合
- パフォーマンス問題の調査前にQuery Store設定を確認する場合
- コンプライアンスレポートの一部としてQuery Store設定を監査する場合
- 環境全体のQuery Store標準化状況を評価する場合

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続する（MinimumVersion 13）
2. Get-DbaDbQueryStoreOptionでQuery Store設定を取得する
3. 各設定項目をベストプラクティス推奨値と比較する
4. 非Azure環境ではトレースフラグ7745/7752の状態もチェックする
5. 比較結果を返却する

**関連システム・外部連携**：SQL Server Query Store機能と連携し、Get-DbaDbQueryStoreOptionおよびGet-DbaTraceFlagを使用する。

**権限による制御**：データベースへのVIEW DATABASE STATE権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - Query Store | 参照画面 | SSMS上でのQuery Store設定確認に相当 |

## 機能種別

データ検証 / ベストプラクティスチェック

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | No | 対象SQL Serverインスタンス | 有効なSQL Server接続文字列 |
| SqlCredential | PSCredential | No | 代替資格情報 | 有効なPSCredentialオブジェクト |
| Database | object[] | No | 評価対象データベース。ワイルドカード対応。 | なし |
| ExcludeDatabase | object[] | No | 除外するデータベース | システムDBは自動除外 |
| InputObject | object[] | No | パイプライン入力（DB、Server、インスタンス） | なし |
| EnableException | switch | No | 例外をスローするモードを有効化 | なし |

### 入力データソース

- SQL Serverインスタンス直接指定（SqlInstanceパラメータ）
- Get-DbaDatabase、サーバーオブジェクト、DbaInstanceParameterからのパイプライン入力（InputObjectパラメータ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | データベース名（Query Store設定の場合） |
| Name | string | 設定項目名またはトレースフラグ名 |
| Value | object | 現在の設定値 |
| RecommendedValue | object | ベストプラクティス推奨値 |
| IsBestPractice | bool | 推奨値に準拠しているかどうか |
| Justification | string | 推奨理由の説明 |

### 出力先

- PowerShellパイプライン（標準出力）
- PSCustomObjectとして出力

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   └─ ExcludeDatabaseにmaster, model, tempdbを追加
2. processブロック
   ├─ Test-FunctionInterruptでの中断チェック
   ├─ InputObject/SqlInstanceパラメータの検証
   ├─ InputObjectの型に応じた処理分岐
   │   ├─ DbaInstanceParameter → Get-DbaDatabase
   │   ├─ Server → Get-DbaDatabase
   │   └─ Database → そのまま使用
   ├─ Connect-DbaInstanceで接続（MinimumVersion 13）
   ├─ Azure SQL Databaseの場合はmsdbを除外対象に追加
   ├─ Database/ExcludeDatabaseフィルター適用
   ├─ ベストプラクティス定義（desiredState）の初期化
   ├─ Get-DbaDbQueryStoreOptionで設定取得
   ├─ 各DBの各設定項目をベストプラクティスと比較
   └─ 非Azure環境ではトレースフラグ7745/7752もチェック
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ExcludeDBにシステムDB追加]
    B --> C{InputObject/SqlInstance?}
    C -->|なし| D[Stop-Function]
    C -->|あり| E{InputObjectの型?}
    E -->|DbaInstanceParameter| F[Get-DbaDatabase]
    E -->|Server| G[Get-DbaDatabase]
    E -->|Database| H[そのまま使用]
    F --> I[Connect-DbaInstance]
    G --> I
    H --> I
    I --> J{Azure SQL DB?}
    J -->|Yes| K[msdbを除外に追加]
    J -->|No| L[Database/Excludeフィルター]
    K --> L
    L --> M[desiredState初期化]
    M --> N[Get-DbaDbQueryStoreOption]
    N --> O[各DBの設定を評価]
    O --> P[各プロパティをループ]
    P --> Q[PSCustomObject出力]
    Q --> R{次のプロパティ?}
    R -->|Yes| P
    R -->|No| S{Azure以外?}
    S -->|Yes| T[トレースフラグチェック]
    T --> U[TF 7745チェック]
    U --> V[TF 7752チェック（v14以下のみ）]
    V --> W{次のDB?}
    S -->|No| W
    W -->|Yes| O
    W -->|No| Z[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | システムDB除外 | master, model, tempdbは自動的に除外 | すべての実行 |
| BR-002 | Azure msdb除外 | Azure SQL DBではmsdbも除外 | Azure SQL Database |
| BR-003 | TFチェック対象 | TF 7752はv14以下のみチェック | SQL Server 2017以前 |
| BR-004 | TFチェック非対象 | Azure SQL DBではTFチェックをスキップ | Azure SQL Database |

### ベストプラクティス定義

| 設定項目 | 推奨値 | 推奨理由 |
|---------|--------|---------|
| ActualState | ReadWrite | Query Storeが有効でデータを収集している状態 |
| DataFlushIntervalInSeconds | 900 | デフォルトの900秒（15分）を推奨 |
| MaxPlansPerQuery | 200 | 1クエリあたり200プランが良い開始点 |
| MaxStorageSizeInMB | 2048 | 2GBが良い開始点 |
| QueryCaptureMode | Auto | 重要でないクエリをフィルタリング |
| SizeBasedCleanupMode | Auto | 容量に近づいたら古いデータを自動削除 |
| StaleQueryThresholdInDays | 30 | 30日間の履歴データを保持 |
| StatisticsCollectionIntervalInMinutes | 30 | 30分間隔で統計を集計 |
| WaitStatsCaptureMode | ON | トラブルシューティング時に有用なデータを追加 |

### トレースフラグ

| TF | 推奨 | 理由 |
|----|------|------|
| 7745 | 有効化推奨 | シャットダウン/フェイルオーバー時にQuery Storeデータの書き込みを待機しない |
| 7752 | 有効化推奨（v14以下） | SQL Server起動時にQuery Storeデータを非同期でロード |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Query Store設定取得 | sys.database_query_store_options | SELECT | Get-DbaDbQueryStoreOption経由 |
| トレースフラグ取得 | - | DBCC TRACESTATUS | Get-DbaTraceFlag経由 |

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

読み取り専用。Get-DbaDbQueryStoreOptionおよびGet-DbaTraceFlagを参照。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | InputObject/SqlInstance未指定 | いずれかを指定 |
| - | Stop-Function | 不正なInputObject型 | DB/Server/Instanceを指定 |
| - | ConnectionError | SQL Server接続失敗 | 接続情報を確認 |
| - | Stop-Function | Query Store取得失敗 | エラーメッセージを確認 |
| - | Stop-Function | トレースフラグ取得失敗 | エラーメッセージを確認 |

### リトライ仕様

リトライ処理は実装されていない。

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

読み取り専用操作のため、トランザクション制御は不要。

## パフォーマンス要件

特に規定なし。軽量なメタデータ取得と比較処理。

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

- SQL Server認証、Windows認証、Azure AD認証をサポート
- 接続資格情報はPSCredentialオブジェクトで安全に管理
- MFAサポートが必要な場合はConnect-DbaInstanceの事前使用を推奨

## 備考

- SQL Server 2016以降（Version 13以上）が必要
- 著者はJess Pomfret
- Erin StellatoのQuery Storeベストプラクティスに基づく
- 参考: https://www.sqlskills.com/blogs/erin/query-store-best-practices/

---

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

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

### 推奨読解順序

#### Step 1: ベストプラクティス定義を理解する

評価基準となるベストプラクティス定義を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaDbQueryStore.ps1 | `public/Test-DbaDbQueryStore.ps1` | desiredState定義（180-224行目）でベストプラクティス値を確認 |

**読解のコツ**: desiredStateは配列で定義され、各要素はProperty, Value, Justificationプロパティを持つPSCustomObject。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaDbQueryStore.ps1 | `public/Test-DbaDbQueryStore.ps1` | パラメータ定義（113-122行目）で入力の受け取り方を確認 |

**主要処理フロー**:
1. **124-126行目**: beginブロックでシステムDB除外設定
2. **128-134行目**: パラメータ検証
3. **140-160行目**: InputObjectの型判定とDB取得
4. **180-224行目**: ベストプラクティス定義
5. **226-248行目**: Query Store設定の評価
6. **250-280行目**: トレースフラグのチェック

#### Step 3: 評価ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaDbQueryStore.ps1 | `public/Test-DbaDbQueryStore.ps1` | 設定評価ループ（230-245行目） |
| 3-2 | Test-DbaDbQueryStore.ps1 | `public/Test-DbaDbQueryStore.ps1` | トレースフラグ評価（251-279行目） |

**主要処理フロー**:
- **231行目**: GetPropertySet()で除外プロパティをフィルター
- **232-244行目**: 各プロパティの評価とPSCustomObject出力
- **262-276行目**: TF 7745/7752の状態チェック

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

```
Test-DbaDbQueryStore
    │
    ├─ Test-FunctionInterrupt
    │      └─ 中断チェック
    │
    ├─ Get-DbaDatabase
    │      └─ データベースリスト取得
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続（MinimumVersion 13）
    │
    ├─ Get-DbaDbQueryStoreOption
    │      └─ Query Store設定取得
    │
    └─ Get-DbaTraceFlag
           └─ トレースフラグ状態取得
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance
InputObject                 │
                            ▼
                    Get-DbaDatabase
                            │
                            ▼
                 Get-DbaDbQueryStoreOption ───────▶ $currentOptions
                            │
                            ▼
                    desiredState定義
                            │
                            ▼
               ┌────────────┴────────────┐
               ▼                         ▼
         各プロパティ比較          Get-DbaTraceFlag
               │                         │
               ▼                         ▼
         PSCustomObject[]          TF状態チェック
               │                         │
               └────────────┬────────────┘
                            ▼
                       出力統合 ───────▶ PSCustomObject[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaDbQueryStore.ps1 | `public/Test-DbaDbQueryStore.ps1` | ソース | メイン機能の実装 |
| Get-DbaDbQueryStoreOption.ps1 | `public/Get-DbaDbQueryStoreOption.ps1` | ソース | Query Store設定取得 |
| Get-DbaTraceFlag.ps1 | `public/Get-DbaTraceFlag.ps1` | ソース | トレースフラグ状態取得 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
