# 機能設計書 427-Set-DbaDbQueryStoreOption

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Set-DbaDbQueryStoreOption`コマンドレットに関する機能設計書である。このコマンドレットは、SQL ServerデータベースのQuery Store構成設定を変更する機能を提供する。

### 本機能の処理概要

`Set-DbaDbQueryStoreOption`は、SQL ServerデータベースのQuery Store構成オプションを変更するコマンドレットである。運用状態（有効/無効）の調整、データ収集間隔の設定、ストレージ制限の構成、キャプチャ対象クエリの制御、データ保持ポリシーの管理が可能である。

**業務上の目的・背景**：Query Storeは、クエリ実行プランとランタイム統計を時系列で追跡するパフォーマンスデータレコーダーとして機能する。適切な設定は、パフォーマンス分析の品質とプラン回帰のトラブルシューティング能力に直接影響する。本機能により、DBAは個別のデータベースまたは複数のデータベースに対して、Query Storeの動作を細かく制御できる。

**機能の利用シーン**：
- Query Storeを有効化/無効化する場合
- データ収集間隔を調整する場合
- ストレージ制限を変更する場合
- キャプチャモードを変更する場合（All, Auto, None, Custom）
- 保持ポリシーを調整する場合
- SQL Server 2019+でカスタムキャプチャポリシーを設定する場合

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続する（MinimumVersion 13）
2. パラメータの検証を行う
3. ユーザーデータベースのリストを取得する
4. 各データベースに対してQuery Store設定を変更する
5. SMOオブジェクトの変更とT-SQLコマンドの組み合わせで設定を適用する
6. 変更後の設定を返却する

**関連システム・外部連携**：SQL Server Query Store機能と連携し、SMO QueryStoreOptionsオブジェクトおよびALTER DATABASE文を使用する。

**権限による制御**：データベースのALTER権限またはsysadminアクセスが必要。

## 関連画面

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

## 機能種別

構成変更（UPDATE/ALTER相当）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | 有効なSQL Server接続文字列 |
| SqlCredential | PSCredential | No | 代替資格情報 | 有効なPSCredentialオブジェクト |
| Database | object[] | No | 設定対象データベース | AllDatabases/ExcludeDatabaseと組み合わせ |
| ExcludeDatabase | object[] | No | 除外するデータベース | システムDBは自動除外 |
| AllDatabases | switch | No | すべてのユーザーDBに適用 | Database/ExcludeDatabaseと組み合わせ |
| State | string[] | No | Query Store状態（ReadWrite/ReadOnly/Off） | ValidateSetで検証 |
| FlushInterval | int64 | No | データフラッシュ間隔（秒） | なし |
| CollectionInterval | int64 | No | 統計収集間隔（分） | なし |
| MaxSize | int64 | No | 最大ストレージサイズ（MB） | なし |
| CaptureMode | string[] | No | キャプチャモード（Auto/All/None/Custom） | ValidateSetで検証 |
| CleanupMode | string[] | No | クリーンアップモード（Auto/Off） | ValidateSetで検証 |
| StaleQueryThreshold | int64 | No | 古いクエリ閾値（日数） | なし |
| MaxPlansPerQuery | int64 | No | クエリあたり最大プラン数（v14+） | なし |
| WaitStatsCaptureMode | string[] | No | 待機統計キャプチャ（On/Off、v14+） | ValidateSetで検証 |
| CustomCapturePolicyExecutionCount | int64 | No | 実行カウント閾値（v15+） | なし |
| CustomCapturePolicyTotalCompileCPUTimeMS | int64 | No | コンパイルCPU時間閾値（v15+） | なし |
| CustomCapturePolicyTotalExecutionCPUTimeMS | int64 | No | 実行CPU時間閾値（v15+） | なし |
| CustomCapturePolicyStaleThresholdHours | int64 | No | 古い閾値（時間、v15+） | なし |
| WhatIf | switch | No | 実行内容を表示するのみ | なし |
| Confirm | switch | No | 実行前に確認を求める | なし |
| EnableException | switch | No | 例外をスローするモードを有効化 | なし |

### 入力データソース

- SQL Serverインスタンス直接指定（SqlInstanceパラメータ）

## 出力仕様

### 出力データ

Get-DbaDbQueryStoreOptionと同じ出力形式。変更後のQuery Store設定を返却。

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | データベース名 |
| ActualState | string | 現在のQuery Store状態 |
| DataFlushIntervalInSeconds | int | データフラッシュ間隔（秒） |
| StatisticsCollectionIntervalInMinutes | int | 統計収集間隔（分） |
| MaxStorageSizeInMB | int | 最大ストレージサイズ（MB） |
| CurrentStorageSizeInMB | int | 現在のストレージ使用量（MB） |
| QueryCaptureMode | string | クエリキャプチャモード |
| SizeBasedCleanupMode | string | サイズベースクリーンアップモード |
| StaleQueryThresholdInDays | int | 古いクエリの閾値（日数） |

### 出力先

- PowerShellパイプライン（標準出力）
- Get-DbaDbQueryStoreOption経由でQueryStoreOptionsオブジェクトを返却

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   └─ ExcludeDatabaseにmaster, tempdb, modelを追加
2. processブロック
   ├─ パラメータ検証（Database/ExcludeDatabase/AllDatabasesのいずれかが必要）
   ├─ 設定パラメータの存在確認
   ├─ 各SqlInstanceの処理
   │   ├─ Connect-DbaInstanceで接続（MinimumVersion 13）
   │   ├─ Customモードのバージョンチェック（v15以上のみ）
   │   ├─ CustomCapturePolicy系パラメータのバージョン警告
   │   ├─ Get-DbaDatabase（フィルター適用）
   │   └─ 各データベースの処理
   │       ├─ アクセス可能性チェック
   │       ├─ State設定（Alter後Refresh）
   │       ├─ State=Offの場合は他の設定をスキップ
   │       ├─ 各設定項目の変更（ShouldProcess対応）
   │       ├─ v14+設定（ALTER DATABASE）
   │       ├─ v15+設定（ALTER DATABASE、CUSTOMモード時のみ）
   │       ├─ Alter/Refresh
   │       └─ Get-DbaDbQueryStoreOptionで結果返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ExcludeDBにシステムDB追加]
    B --> C{パラメータ検証}
    C -->|DB指定なし| D[Stop-Function]
    C -->|設定なし| E[Stop-Function]
    C -->|OK| F[各インスタンスを処理]
    F --> G[Connect-DbaInstance]
    G --> H{Customモード?}
    H -->|Yes, v<15| I[Stop-Function]
    H -->|No/v15+| J[Get-DbaDatabase]
    J --> K[各DBを処理]
    K --> L{アクセス可能?}
    L -->|No| M[Warning, Skip]
    L -->|Yes| N{State指定?}
    N -->|Yes| O[State変更, Alter, Refresh]
    N -->|No| P{State=Off?}
    O --> P
    P -->|Yes, State未指定| Q[Warning, Skip]
    P -->|No| R[各設定項目変更]
    R --> S{v14+設定?}
    S -->|Yes| T[ALTER DATABASE]
    S -->|No| U[Alter, Refresh]
    T --> V{v15+設定?}
    V -->|Yes, CUSTOM| W[ALTER DATABASE]
    V -->|No| U
    W --> U
    U --> X[Get-DbaDbQueryStoreOption]
    X --> Y{次のDB?}
    M --> Y
    Q --> Y
    Y -->|Yes| K
    Y -->|No| Z{次のインスタンス?}
    Z -->|Yes| F
    Z -->|No| AA[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パラメータ必須 | Database/ExcludeDatabase/AllDatabasesのいずれかが必要 | すべての実行 |
| BR-002 | 設定必須 | 少なくとも1つの設定パラメータが必要 | すべての実行 |
| BR-003 | システムDB除外 | master, tempdb, modelは自動的に除外 | すべての実行 |
| BR-004 | アクセス不可DB処理 | IsAccessible=falseのDBはスキップ | アクセス不可DB検出時 |
| BR-005 | Customモードバージョン | Customモードはv15以上のみ | CaptureMode=Custom時 |
| BR-006 | v15+パラメータ警告 | CustomCapturePolicy系はv15未満で警告 | v14以下でCustomCapturePolicy指定時 |
| BR-007 | State=Off時の制限 | State=Offの場合、他の設定変更は不可 | State=Off、かつState未指定 |
| BR-008 | CUSTOM時のv15+設定 | CustomCapturePolicy系はQueryCaptureMode=CUSTOM時のみ有効 | v15+でCUSTOMモード |

### 計算ロジック

特になし。パラメータ値はそのままQuery Store設定に適用される。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Query Store設定変更 | sys.database_query_store_options | ALTER | Query Store構成の変更 |

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

#### ALTER DATABASE ... SET QUERY_STORE

| 操作 | 項目 | 更新値・条件 | 備考 |
|-----|------|-------------|------|
| ALTER | desired_state | State パラメータ | ReadWrite/ReadOnly/Off |
| ALTER | data_flush_interval_seconds | FlushInterval | SMO経由 |
| ALTER | interval_length_minutes | CollectionInterval | SMO経由 |
| ALTER | max_storage_size_mb | MaxSize | SMO経由 |
| ALTER | query_capture_mode | CaptureMode | SMO経由 |
| ALTER | size_based_cleanup_mode | CleanupMode | SMO経由 |
| ALTER | stale_query_threshold_days | StaleQueryThreshold | SMO経由 |
| ALTER | max_plans_per_query | MaxPlansPerQuery | T-SQL（v14+） |
| ALTER | wait_stats_capture_mode | WaitStatsCaptureMode | T-SQL（v14+） |
| ALTER | QUERY_CAPTURE_POLICY | CustomCapturePolicy系 | T-SQL（v15+, CUSTOMモード） |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | Database/ExcludeDatabase/AllDatabases未指定 | いずれかを指定 |
| - | Stop-Function | 設定パラメータ未指定 | 少なくとも1つ指定 |
| - | ConnectionError | SQL Server接続失敗 | 接続情報を確認 |
| - | Stop-Function | Customモードでv14以下 | v15以上を使用 |
| - | Warning | CustomCapturePolicy系でv14以下 | v15以上を使用（スキップ） |
| - | Warning | State=Offで他設定変更 | Stateを変更 |
| - | InvalidOperation | 設定変更失敗 | エラーメッセージを確認 |

### リトライ仕様

リトライ処理は実装されていない。エラー時は-Continueで次のDBを処理。

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

各設定変更は個別に実行される。明示的なトランザクション制御は実装されていない。

## パフォーマンス要件

特に規定なし。Query Store設定変更は軽量な操作。

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

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

## 備考

- SQL Server 2016以降（Version 13以上）が必要
- 著者はEnrico van de Laar、Tracy Boggiano
- SupportsShouldProcess対応（WhatIf/Confirm）
- 変更後の設定はGet-DbaDbQueryStoreOption経由で返却

---

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

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

### 推奨読解順序

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

入出力のQuery Store設定オブジェクトの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | .OUTPUTSセクション（111-141行目）で出力オブジェクトの構造を理解 |

**読解のコツ**: 出力はGet-DbaDbQueryStoreOption経由で取得されるため、同じ構造。

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

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

**主要処理フロー**:
1. **191-193行目**: beginブロックでシステムDB除外設定
2. **195-204行目**: パラメータ検証
3. **206-219行目**: インスタンス接続とバージョンチェック
4. **221-346行目**: 各データベースの処理

#### Step 3: 設定変更ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | SMO経由の設定変更（233-280行目） |
| 3-2 | Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | T-SQL経由の設定変更（282-325行目） |

**主要処理フロー**:
- **233-239行目**: State変更とAlter/Refresh
- **246-280行目**: FlushInterval, CollectionInterval, MaxSize等のSMO経由変更
- **284-298行目**: v14+のT-SQL変更（MaxPlansPerQuery, WaitStatsCaptureMode）
- **300-324行目**: v15+のCustomCapturePolicy変更

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

```
Set-DbaDbQueryStoreOption
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続（MinimumVersion 13）
    │
    ├─ Get-DbaDatabase
    │      └─ データベースリスト取得
    │
    ├─ db.QueryStoreOptions.Alter()
    │      └─ SMO経由の設定変更
    │
    ├─ db.Query() / ALTER DATABASE
    │      └─ T-SQL経由の設定変更（v14+）
    │
    └─ Get-DbaDbQueryStoreOption
           └─ 変更後の設定取得
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance
Database                    │
各設定パラメータ              ▼
                    Get-DbaDatabase
                            │
                            ▼
                   db.QueryStoreOptions
                            │
           ┌────────────────┼────────────────┐
           ▼                ▼                ▼
       State変更      SMO経由変更      T-SQL変更
           │                │                │
           └────────────────┼────────────────┘
                            ▼
                    db.Alter() / Refresh()
                            │
                            ▼
                 Get-DbaDbQueryStoreOption ───────▶ QueryStoreOptions
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | ソース | メイン機能の実装 |
| Get-DbaDbQueryStoreOption.ps1 | `public/Get-DbaDbQueryStoreOption.ps1` | ソース | 変更後の設定取得 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Copy-DbaDbQueryStoreOption.ps1 | `public/Copy-DbaDbQueryStoreOption.ps1` | ソース | 本機能を利用するコマンド |
